Lote de merchants
Crea o actualiza hasta 500 merchants en una llamada. Cada ítem sigue exactamente la regla de Crear o actualizar merchant: la clave es el merchant_ref, lo que no cambió no se guarda, y repetir el lote no duplica nada.
El lote es siempre parcial: cada ítem se guarda o se rechaza por su cuenta, y la respuesta dice qué pasó con cada uno, en el mismo orden del envío.
Endpoint
Sección titulada «Endpoint»https://api.rapidchargeback.com/api/v1/merchants/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 merchants, cada uno con los campos de Crear o actualizar merchant |
on_name_conflict | enum | No | error (por defecto) o append_ref, para todos los ítems. El on_name_conflict de un ítem vale más que este |
- Cuerpo de hasta 5 MB. Por encima,
413 PAYLOAD_TOO_LARGE. - Un campo distinto de
itemsyon_name_conflicten el envoltorio, oitemsvacío o con más de 500: el lote entero se rechaza con422 VALIDATION_ERROR, sin guardar nada.
Repetidos en el mismo lote
Sección titulada «Repetidos en el mismo lote»El primer ítem vale; los siguientes se rechazan, sin guardar:
- mismo
merchant_ref(sin distinguir mayúsculas ni acentos):MERCHANT_REF_DUPLICATE_IN_BATCH; - mismo
nameen referencias distintas (sinappend_ref):MERCHANT_NAME_DUPLICATE_IN_BATCH.
Ejemplo de solicitud
Sección titulada «Ejemplo de solicitud»curl -X POST https://api.rapidchargeback.com/api/v1/merchants/batch \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "merchant_ref": "PB-1001", "name": "Loja Exemplo" }, { "merchant_ref": "PB-1002", "name": "Loja Exemplo Dois", "merchant_url": "https://lojaexemplodois.com" }, { "merchant_ref": "PB-1003", "name": "Loja Exemplo" } ] }'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, "updated": 0, "unchanged": 1 }, "results": [ { "index": 0, "result": "unchanged", "merchant_ref": "PB-1001", "merchant": { "id": "00000000-0000-0000-0000-000000000001", "name": "Loja Exemplo", "merchant_ref": "PB-1001", "status": "active", "created_at": "2026-11-06T12:00:00.000Z", "updated_at": "2026-11-06T12:00:00.000Z" } }, { "index": 1, "result": "created", "merchant_ref": "PB-1002", "merchant": { "id": "00000000-0000-0000-0000-000000000002", "name": "Loja Exemplo Dois", "merchant_ref": "PB-1002", "status": "active", "created_at": "2026-11-07T12:00:00.000Z", "updated_at": "2026-11-07T12:00:00.000Z" } }, { "index": 2, "result": "error", "merchant_ref": "PB-1003", "status": 422, "error": { "code": "MERCHANT_NAME_DUPLICATE_IN_BATCH", "message": "name appears more than once in the batch", "params": { "name": "Loja Exemplo" } } } ] }}| Campo | Descripción |
|---|---|
total | Ítems enviados |
succeeded | Ítems creados, actualizados o sin cambios (total - failed) |
failed | Ítems rechazados |
counts | Cuántos de cada uno: created, updated, unchanged |
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, updated, unchanged o error |
results[].merchant_ref | El merchant_ref que enviaste en el ítem (null si no vino texto) |
results[].merchant | En el éxito: el resumen del merchant, el mismo de Listar merchants |
results[].warnings | Cuando hay: el aviso SERVICE_FIELDS_NOT_APPLIED (ver Aviso de dato que no se aplica en el momento) |
results[].status | En el error: el HTTP que el ítem tendría solo |
results[].error | En el error: code, message y, cuando hay, params |
Los errores de cada ítem son los de Crear o actualizar merchant, más los dos de repetidos en el lote.
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 merchants a la vez. El segundo lote enviado mientras el primero todavía se está guardando se rechaza entero, sin guardar nada: 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, o campo desconocido en el envoltorio |
| 413 | PAYLOAD_TOO_LARGE | Cuerpo por encima de 5 MB |
| 429 | RATE_LIMIT_EXCEEDED | Más de 60 escrituras por minuto (cada lote cuenta como una) |
| 429 | BATCH_IN_PROGRESS | Otro lote de merchants de tu empresa todavía en curso |
| 403 | KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKED | Ver Crear o actualizar merchant |
| 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ó vuelveunchanged. - Volumen: 3.000 merchants son 6 llamadas de 500. 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.