Ir al contenido

↑↓ navegar ↵ abrir Ctrl↵ nueva pestaña esc cerrar

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_DUPLICATE con el merchant_id del merchant que ya tiene el nombre. Guarda la referencia en él una vez con 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

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 con retry_rejected: true.

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):

  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.

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.

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.

Uso por merchant devuelve cuántas alertas facturables tuvo cada vendedor en el ciclo de facturación actual o en un ciclo cerrado.

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ímiteValor
Ítems por lote500
Escrituras por minuto (cada lote cuenta como una)60 por empresa
Lotes al mismo tiempo1 de merchants y 1 de enrollments por empresa (BATCH_IN_PROGRESS)
Enrollments esperando aprobación20.000 por empresa (ENROLLMENT_PENDING_LIMIT)
Consultas de uso por minuto10 por empresa

Ver también Rate limit.