Lote de enrollments
Solicita hasta 500 enrollments en una llamada, de uno o varios merchants. Cada ítem sigue la regla de Solicitar enrollment: los mismos campos, los mismos errores, y la solicitud repetida vuelve existing, sin crear otra.
Solicita cada enrollment una vez, cuando el vendedor entra en tu base: no incluyas los enrollments en un envío diario (ver Guía de sincronización).
Endpoint
Sección titulada «Endpoint»https://api.rapidchargeback.com/api/v1/enrollments/batchAutenticación
Sección titulada «Autenticación»Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonCuerpo de la solicitud
Sección titulada «Cuerpo de la solicitud»| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
items | array | Sí | De 1 a 500 solicitudes, cada una con los campos de Solicitar enrollment, incluido su propio merchant_id o merchant_ref |
mode | enum | No | partial (por defecto) o all_or_nothing |
- Cuerpo de hasta 2 MB. Por encima,
413 PAYLOAD_TOO_LARGE. - Un campo distinto de
itemsymodeen el envoltorio, oitemsvacío o con más de 500: el lote entero se rechaza con422 VALIDATION_ERROR, sin guardar nada.
mode | Qué pasa |
|---|---|
partial | Cada ítem se guarda o se rechaza por su cuenta. existing cuenta como éxito |
all_or_nothing | Rapid revisa todos los ítems antes. Si alguno falla, no se guarda nada y el lote vuelve 422 ENROLLMENT_BATCH_INVALID con la lista de los ítems rechazados. existing no cuenta como falla; ENROLLMENT_PREVIOUSLY_REJECTED sí |
Repetidos en el mismo lote
Sección titulada «Repetidos en el mismo lote»El mismo identificador en dos ítems del lote (descriptor sin distinguir mayúsculas, espacios repetidos ni espacios alrededor del *, o el mismo BIN + CAID): el primero vale y los siguientes se rechazan con ENROLLMENT_DUPLICATE_IN_BATCH.
Tope de pendientes
Sección titulada «Tope de pendientes»Si las solicitudes nuevas del lote llevan a tu empresa por encima de 20.000 enrollments esperando aprobación, el lote entero se rechaza con 422 ENROLLMENT_PENDING_LIMIT, sin guardar nada.
Ejemplo de solicitud
Sección titulada «Ejemplo de solicitud»curl -X POST https://api.rapidchargeback.com/api/v1/enrollments/batch \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \ -H "Content-Type: application/json" \ -d '{ "mode": "partial", "items": [ { "merchant_ref": "PB-1001", "enrollment_type": "descriptor", "descriptor_value": "LOJA EXEMPLO", "descriptor_rule": "exact", "products": ["alert"] }, { "merchant_ref": "PB-1002", "enrollment_type": "bin_caid", "bin": "424242", "caid": "123456789", "products": ["alert"] }, { "merchant_ref": "PB-1002", "enrollment_type": "descriptor", "descriptor_value": "loja exemplo", "descriptor_rule": "exact", "products": ["alert"] } ] }'Respuesta
Sección titulada «Respuesta»200 OK siempre que el lote se procesó, incluso con ítems rechazados. Revisa failed y el result de cada ítem.
{ "data": { "total": 3, "succeeded": 2, "failed": 1, "counts": { "created": 1, "existing": 1 }, "results": [ { "index": 0, "result": "existing", "merchant_ref": "PB-1001", "enrollment": { "id": "00000000-0000-0000-0000-0000000000aa", "merchant_id": "00000000-0000-0000-0000-000000000001", "merchant_ref": "PB-1001", "enrollment_type": "descriptor", "descriptor_value": "loja exemplo", "descriptor_rule": "exact", "bin": null, "caid": null, "arn": null, "products": { "alert": { "status": "active", "rejection_reason": null, "approved_at": "2026-11-07T15:00:00.000Z" }, "prevention": null }, "created_at": "2026-11-06T12:00:00.000Z", "updated_at": "2026-11-07T15:00:00.000Z" } }, { "index": 1, "result": "created", "merchant_ref": "PB-1002", "enrollment": { "id": "00000000-0000-0000-0000-0000000000ab", "...": "objeto Enrollment" } }, { "index": 2, "result": "error", "merchant_ref": "PB-1002", "status": 422, "error": { "code": "ENROLLMENT_DUPLICATE_IN_BATCH", "message": "Descriptor \"loja exemplo\" appears more than once in the batch", "params": { "identifier": "Descriptor \"loja exemplo\"" } } } ] }}| Campo | Descripción |
|---|---|
total, succeeded, failed | Ítems enviados, aceptados (created o existing) y rechazados |
counts | Cuántos de cada uno: created, existing |
results | Uno por ítem, en el orden del array enviado |
results[].index | Posición del ítem en el array enviado, desde 0 |
results[].result | created, existing o error |
results[].merchant_ref | El merchant_ref que enviaste en el ítem (null si vino merchant_id) |
results[].enrollment | En el éxito: el objeto Enrollment, el mismo de Solicitar enrollment |
results[].status, results[].error | En el error: el HTTP que el ítem tendría solo y el error (code, message, params) |
Todo o nada rechazado
Sección titulada «Todo o nada rechazado»HTTP/1.1 422 Unprocessable Entity{ "error": { "code": "ENROLLMENT_BATCH_INVALID", "message": "1 of 3 items were not accepted. Nothing was created.", "params": { "count": 1, "total": 3 }, "details": { "errors": [ { "index": 2, "code": "ENROLLMENT_DUPLICATE_IN_BATCH", "message": "Descriptor \"loja exemplo\" appears more than once in the batch", "params": { "identifier": "Descriptor \"loja exemplo\"" } } ] } }}Otro lote en curso
Sección titulada «Otro lote en curso»HTTP/1.1 429 Too Many RequestsRetry-After: 5{ "error": { "code": "BATCH_IN_PROGRESS", "message": "Another batch from this account is still being processed. Try again in a few seconds." }}Tu empresa tiene un lote de enrollments a la vez. El segundo lote enviado mientras el primero todavía se está guardando se rechaza entero: espera el Retry-After y envíalo de nuevo.
Errores del lote entero
Sección titulada «Errores del lote entero»| HTTP | Código | Cuándo |
|---|---|---|
| 422 | VALIDATION_ERROR | Envoltorio inválido: items ausente, vacío, con más de 500, mode fuera de la lista o campo desconocido en el envoltorio |
| 422 | ENROLLMENT_BATCH_INVALID | Todo o nada con algún ítem rechazado (params.count, params.total, details.errors) |
| 422 | ENROLLMENT_PENDING_LIMIT | El lote llevaría a tu empresa por encima de 20.000 pendientes (params.limit) |
| 413 | PAYLOAD_TOO_LARGE | Cuerpo por encima de 2 MB |
| 429 | RATE_LIMIT_EXCEEDED | Más de 60 escrituras por minuto (cada lote cuenta como una) |
| 429 | BATCH_IN_PROGRESS | Otro lote de enrollments de tu empresa todavía en curso |
| 403 | KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKED | Empresa sin registro aprobado, inactiva o bloqueada |
| 503 | SERVICE_UNAVAILABLE | No disponible temporalmente: repite después del Retry-After |
- Repetir es seguro. Después de un
503o de una caída de conexión, envía el mismo lote: lo que ya se guardó vuelveexisting. Si recibesBATCH_IN_PROGRESS, el lote anterior todavía se está guardando: espera y repite. - Envía un lote después del otro, no en paralelo.
- Auth, rate limit, códigos de error: ver Autenticación y Códigos de respuesta.