Guía de sincronización
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
Sección titulada «1. Merchants: la base entera, todos los días»Envía tu base de vendedores por el 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_DUPLICATEcon elmerchant_iddel merchant que ya tiene el nombre. Guarda la referencia en él una vez con Editar merchant (PATCHconmerchant_ref); a partir de ahí el lote lo actualiza. merchant_refno distingue mayúsculas ni acentos.PB-a1ypb-A1son la misma referencia. Si tu sistema tiene vendedores que solo difieren en eso, la API rechaza el segundo conMERCHANT_REF_CONFLICTen 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
Sección titulada «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). Solicita cada uno una vez, cuando el vendedor entra en tu base, con Solicitar enrollment o el 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 conretry_rejected: true.
3. Seguir la aprobación
Sección titulada «3. Seguir la aprobación»Consulta 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):
- Guarda el mayor
updated_atque recibiste. - En la consulta siguiente, envía ese valor menos 2 minutos como
updated_since. - Ignora el par (
id,updated_at) que ya procesaste. - 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
Sección titulada «4. Alertas con tu vendedor»Cada alerta trae el merchant_ref del vendedor, en la consulta de alertas y en el webhook 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
Sección titulada «5. Salida de un vendedor»Lista sus enrollments con Listar enrollments filtrando por merchant_ref y solicita la desactivación 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.
6. Uso del mes por vendedor
Sección titulada «6. Uso del mes por vendedor»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
Sección titulada «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
Sección titulada «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.