# Guía de sincronización

> El flujo recomendado para mantener a tus vendedores, sus enrollments y las alertas al día con Rapid por la API, sin duplicar nada.

Página: https://doc.rapidchargeback.com/es/canais/merchants/guia-de-sincronizacao/

Esta guía es para quien tiene muchos vendedores (tiendas, marcas, subcuentas) y quiere mantener su registro en Rapid igual al de su propio sistema, solicitar los enrollments y vincular cada alerta al vendedor correcto. Todo se apoya en el `merchant_ref`, el ID del vendedor en **tu** sistema.

## 1. Merchants: la base entera, todos los días

Envía tu base de vendedores por el [Lote de merchants](https://doc.rapidchargeback.com/es/canais/merchants/lote-de-merchants/), hasta 500 por llamada, una vez al día (o cuando cambie). La clave es el `merchant_ref`:

- un vendedor nuevo se vuelve un merchant nuevo (`created`);
- un vendedor que cambió se actualiza (`updated`);
- un vendedor igual no se guarda (`unchanged`), así que reenviar la base entera no genera cambios falsos.

Cuidados:

- **Merchant que ya estaba en el panel, sin referencia.** El lote responde `MERCHANT_DUPLICATE` con el `merchant_id` del merchant que ya tiene el nombre. Guarda la referencia en él una vez con [Editar merchant](https://doc.rapidchargeback.com/es/canais/merchants/editar-merchant/) (`PATCH` con `merchant_ref`); a partir de ahí el lote lo actualiza.
- **`merchant_ref` no distingue mayúsculas ni acentos.** `PB-a1` y `pb-A1` son la misma referencia. Si tu sistema tiene vendedores que solo difieren en eso, la API rechaza el segundo con `MERCHANT_REF_CONFLICT` en vez de juntar los dos.
- **La referencia no se cambia** después de guardada (`MERCHANT_REF_IMMUTABLE`).

## 2. Enrollments: se solicitan una vez, cuando el vendedor entra

El enrollment es lo que vincula las alertas a un merchant: su descriptor o su BIN + CAID (ver [Enrollments](https://doc.rapidchargeback.com/es/canais/enrollments/visao-geral/)). Solicita cada uno **una vez**, cuando el vendedor entra en tu base, con [Solicitar enrollment](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-enrollment/) o el [Lote de enrollments](https://doc.rapidchargeback.com/es/canais/enrollments/lote-de-enrollments/). No incluyas los enrollments en el envío diario.

- Solicitar de nuevo el mismo enrollment devuelve `existing`, sin crear otro: repetir después de una falla es seguro.
- Toda solicitud pasa por la aprobación del equipo de Rapid y nace `pending`.
- Una solicitud rechazada por el equipo no vuelve sola: solicitarla de nuevo responde `ENROLLMENT_PREVIOUSLY_REJECTED`. Corrige el dato y envíala con `retry_rejected: true`.

## 3. Seguir la aprobación

Consulta [Listar enrollments](https://doc.rapidchargeback.com/es/canais/enrollments/listar-enrollments/) con `updated_since` cada pocos minutos. La regla es la misma en las tres listas que aceptan este filtro (merchants, enrollments y alertas):

1. Guarda el mayor `updated_at` que recibiste.
2. En la consulta siguiente, envía ese valor **menos 2 minutos** como `updated_since`.
3. Ignora el par (`id`, `updated_at`) que ya procesaste.
4. Lee las páginas hasta `total_pages`.

El estado de cada producto del enrollment dice dónde está: `pending`, `active`, `rejected` (con `rejection_reason`), `deactivation_requested` o `inactive`.

## 4. Alertas con tu vendedor

Cada alerta trae el `merchant_ref` del vendedor, en la [consulta de alertas](https://doc.rapidchargeback.com/es/callback/consultar-alertas/) y en el [webhook](https://doc.rapidchargeback.com/es/canais/webhook/payload/) en formato `v2` (en `merchant.merchant_ref`), junto con el `merchant_enrollment_id` del enrollment que coincidió. Para buscar las alertas de un vendedor, filtra por `merchant_ref`. Para buscar lo que cambió, usa `updated_since` con la misma regla del paso 3.

## 5. Salida de un vendedor

Lista sus enrollments con [Listar enrollments](https://doc.rapidchargeback.com/es/canais/enrollments/listar-enrollments/) filtrando por `merchant_ref` y [solicita la desactivación](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-desativacao/) de cada uno. El equipo de Rapid la confirma, y el enrollment sigue recibiendo alertas hasta la confirmación. Si quieres, marca el merchant con `status: "inactive"` en [Editar merchant](https://doc.rapidchargeback.com/es/canais/merchants/editar-merchant/).

## 6. Uso del mes por vendedor

[Uso por merchant](https://doc.rapidchargeback.com/es/canais/uso/uso-por-merchant/) devuelve cuántas alertas facturables tuvo cada vendedor en el ciclo de facturación actual o en un ciclo cerrado.

## 7. Antes de la carga real

Todavía no hay ambiente de prueba: toda solicitud de enrollment hecha en tu cuenta entra de verdad en la cola de aprobación del equipo de Rapid. Antes de la primera carga grande, habla con el soporte de Rapid para acordar cómo validar tu integración.

---

## Límites que valen para este flujo

| Límite | Valor |
|---|---|
| Ítems por lote | 500 |
| Escrituras por minuto (cada lote cuenta como una) | 60 por empresa |
| Lotes al mismo tiempo | 1 de merchants y 1 de enrollments por empresa (`BATCH_IN_PROGRESS`) |
| Enrollments esperando aprobación | 20.000 por empresa (`ENROLLMENT_PENDING_LIMIT`) |
| Consultas de uso por minuto | 10 por empresa |

Ver también [Rate limit](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/#rate-limit).
