Ir al contenido

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

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

POST https://api.rapidchargeback.com/api/v1/enrollments/batch
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

CampoTipoObligatorioDescripción
itemsarraySíDe 1 a 500 solicitudes, cada una con los campos de Solicitar enrollment, incluido su propio merchant_id o merchant_ref
modeenumNopartial (por defecto) o all_or_nothing
  • Cuerpo de hasta 2 MB. Por encima, 413 PAYLOAD_TOO_LARGE.
  • Un campo distinto de items y mode en el envoltorio, o items vacío o con más de 500: el lote entero se rechaza con 422 VALIDATION_ERROR, sin guardar nada.
modeQué pasa
partialCada ítem se guarda o se rechaza por su cuenta. existing cuenta como éxito
all_or_nothingRapid 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í

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.

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.


Ventana de terminal
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"] }
]
}'

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\"" }
}
}
]
}
}
CampoDescripción
total, succeeded, failedÍtems enviados, aceptados (created o existing) y rechazados
countsCuántos de cada uno: created, existing
resultsUno por ítem, en el orden del array enviado
results[].indexPosición del ítem en el array enviado, desde 0
results[].resultcreated, existing o error
results[].merchant_refEl merchant_ref que enviaste en el ítem (null si vino merchant_id)
results[].enrollmentEn el éxito: el objeto Enrollment, el mismo de Solicitar enrollment
results[].status, results[].errorEn el error: el HTTP que el ítem tendría solo y el error (code, message, params)
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\"" }
}
]
}
}
}
HTTP/1.1 429 Too Many Requests
Retry-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.

HTTPCódigoCuándo
422VALIDATION_ERROREnvoltorio inválido: items ausente, vacío, con más de 500, mode fuera de la lista o campo desconocido en el envoltorio
422ENROLLMENT_BATCH_INVALIDTodo o nada con algún ítem rechazado (params.count, params.total, details.errors)
422ENROLLMENT_PENDING_LIMITEl lote llevaría a tu empresa por encima de 20.000 pendientes (params.limit)
413PAYLOAD_TOO_LARGECuerpo por encima de 2 MB
429RATE_LIMIT_EXCEEDEDMás de 60 escrituras por minuto (cada lote cuenta como una)
429BATCH_IN_PROGRESSOtro lote de enrollments de tu empresa todavía en curso
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDEmpresa sin registro aprobado, inactiva o bloqueada
503SERVICE_UNAVAILABLENo disponible temporalmente: repite después del Retry-After

  • Repetir es seguro. Después de un 503 o de una caída de conexión, envía el mismo lote: lo que ya se guardó vuelve existing. Si recibes BATCH_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.