Envío por lotes

Crea varias transacciones en una sola solicitud (hasta 1000 por llamada).

Usa el envío por lotes cuando necesitas sincronizar grandes volúmenes (ej.: carga inicial, reprocesamiento de un día entero). El procesamiento es por transacción: el éxito de una no depende del éxito de las demás.

Endpoint

POST https://api.rapidchargeback.com/api/v1/transactions/batch

Autenticación

Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

---

Cuerpo de la solicitud

Campo	Tipo	Descripción
transactions	array	Lista de transacciones (mín. 1, máx. 1000)

Cada ítem del array sigue el mismo schema de Crear transacción: los mismos campos obligatorios, opcionales y anidados, y las mismas validaciones.

---

Validaciones

• El array transactions debe tener entre 1 y 1000 ítems. Un problema en el envoltorio (array ausente, vacío o con más de 1000) rechaza la solicitud entera
• El cuerpo de la solicitud puede tener hasta 5 MB, lo que cubre 1000 transacciones con todos los campos completos. Por encima de eso la respuesta es 413 PAYLOAD_TOO_LARGE y no se crea nada: divídelo en lotes más chicos
• Dentro del array, cada transacción se valida individualmente: campo inválido, campo obligatorio ausente, texto por encima del límite, duplicado, merchant inexistente. Todo eso se convierte en error de esa línea
• Un error en una línea no bloquea las demás: las válidas se crean y la respuesta indica cuáles fallaron
• Un duplicado dentro del propio lote (mismo external_source y external_id dos veces) crea la primera y hace fallar la segunda

---

Ejemplo de solicitud

curl -X POST https://api.rapidchargeback.com/api/v1/transactions/batch \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "merchant_id": "00000000-0000-0000-0000-000000000001",
        "external_source": "custom",
        "external_id": "TXN-2026-001",
        "transaction_date": "2026-04-01T10:00:00Z",
        "amount": 150.00,
        "currency": "USD",
        "card_last4": "4242",
        "items": [{ "product_description": "Item A", "unit_price": 150.00 }]
      },
      {
        "merchant_id": "00000000-0000-0000-0000-000000000001",
        "external_source": "custom",
        "external_id": "TXN-2026-002",
        "transaction_date": "2026-04-01T11:00:00Z",
        "amount": 200.00,
        "currency": "BRL",
        "card_last4": "1234",
        "items": [{ "product_description": "Item B", "unit_price": 200.00 }]
      }
    ]
  }'

---

Ejemplos de respuesta

El lote responde 200, no 201: en una llamada que crea algunas líneas y falla otras, el estado por sí solo no dice el resultado. Lo dice el cuerpo. Revisa siempre failed y errors, nunca solo el código HTTP.

Resultados mixtos (200)

{
  "data": {
    "created": 1,
    "failed": 1,
    "results": [
      {
        "external_id": "TXN-2026-001",
        "tx_id": "00000000-0000-0000-0000-000000000042",
        "warnings": ["card_bin missing: reduces match accuracy"]
      }
    ],
    "errors": [
      {
        "index": 1,
        "external_id": "TXN-2026-002",
        "status": 409,
        "error": "Transaction already exists"
      }
    ]
  }
}

Cada ítem en results contiene:

• external_id: identifica la transacción en tu sistema.
• tx_id: UUID generado por Rapid (guárdalo para operaciones futuras).
• warnings: avisos de campos ausentes (no bloquean la creación).

Cada ítem en errors contiene:

• index: posición de la línea en el array que enviaste, empezando en cero. Es así como ubicas la línea cuando el campo inválido es justamente el external_id.
• external_id: identifica qué transacción falló, o string vacío si el valor enviado no era válido.
• status: código HTTP equivalente del error (422 validación, 404 merchant inexistente, 409 duplicado).
• error: mensaje descriptivo.

created + failed es siempre el total de líneas enviadas. results y errors salen en el orden de entrada.

Todas creadas con éxito (200)

{
  "data": {
    "created": 2,
    "failed": 0,
    "results": [
      { "external_id": "TXN-2026-001", "tx_id": "uuid-1", "warnings": [] },
      { "external_id": "TXN-2026-002", "tx_id": "uuid-2", "warnings": [] }
    ],
    "errors": []
  }
}

Línea con un campo inválido (200)

Una línea rechazada en la validación no tumba a las demás: aparece en errors con status: 422.

{
  "data": {
    "created": 1,
    "failed": 1,
    "results": [
      { "external_id": "TXN-2026-001", "tx_id": "uuid-1", "warnings": [] }
    ],
    "errors": [
      {
        "index": 1,
        "external_id": "TXN-2026-002",
        "status": 422,
        "error": "Currency must be 3 uppercase letters (ISO 4217)"
      }
    ]
  }
}

Error de validación del batch (fuera del array)

Si el array transactions está vacío, falta o supera los 1000 ítems, se rechaza la solicitud entera:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Array must contain at most 1000 element(s)"
  }
}

---

Comportamientos del lote que vale la pena conocer

• Un merchant_ref desconocido crea el vendedor (con merchant_name, si se envía) y no devuelve 404.
• Un duplicado dentro del mismo lote (mismo external_source/external_id dos veces) falla en la segunda línea con TRANSACTION_DUPLICATE; la primera se crea.
• El orden de results es el orden de entrada.