Ir al contenido

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

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.

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

CampoTipoObligatorioDescripción
itemsarraySíDe 1 a 500 merchants, cada uno con los campos de Crear o actualizar merchant
on_name_conflictenumNoerror (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 items y on_name_conflict 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.

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 name en referencias distintas (sin append_ref): MERCHANT_NAME_DUPLICATE_IN_BATCH.

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

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" }
}
}
]
}
}
CampoDescripción
totalÍtems enviados
succeededÍtems creados, actualizados o sin cambios (total - failed)
failedÍtems rechazados
countsCuántos de cada uno: created, updated, unchanged
resultsUno por ítem, en el orden del array enviado
results[].indexPosición del ítem en el array enviado, desde 0
results[].resultcreated, updated, unchanged o error
results[].merchant_refEl merchant_ref que enviaste en el ítem (null si no vino texto)
results[].merchantEn el éxito: el resumen del merchant, el mismo de Listar merchants
results[].warningsCuando hay: el aviso SERVICE_FIELDS_NOT_APPLIED (ver Aviso de dato que no se aplica en el momento)
results[].statusEn el error: el HTTP que el ítem tendría solo
results[].errorEn 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.

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

HTTPCódigoCuándo
422VALIDATION_ERROREnvoltorio inválido: items ausente, vacío, con más de 500, o campo desconocido en el envoltorio
413PAYLOAD_TOO_LARGECuerpo por encima de 5 MB
429RATE_LIMIT_EXCEEDEDMás de 60 escrituras por minuto (cada lote cuenta como una)
429BATCH_IN_PROGRESSOtro lote de merchants de tu empresa todavía en curso
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDVer Crear o actualizar merchant
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 unchanged.
  • 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.