Envio em lote

Cria múltiplas transações em uma única requisição (até 1000 por chamada).

Use o envio em lote quando você precisa sincronizar grandes volumes (ex: carga inicial, reprocessamento de um dia inteiro). O processamento é por transação: o sucesso de uma não depende do sucesso das outras.

Endpoint

POSThttps://api.rapidchargeback.com/api/v1/transactions/batch

Autenticação

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

---

Corpo da requisição

Campo	Tipo	Descrição
transactions	array	Lista de transações (mín. 1, máx. 1000)

Cada item do array segue o mesmo schema de Criar transação: mesmos campos obrigatórios, opcionais, aninhados e validações.

---

Validações

• O array transactions deve ter entre 1 e 1000 itens. Problema no envelope (array ausente, vazio ou acima de 1000) rejeita a requisição inteira
• O corpo da requisição pode ter até 5 MB, o que cobre 1000 transações com todos os campos preenchidos. Acima disso a resposta é 413 PAYLOAD_TOO_LARGE e nada é criado: divida em lotes menores
• Dentro do array, cada transação é validada individualmente: campo inválido, campo obrigatório ausente, texto acima do limite, duplicata, merchant inexistente. Tudo isso vira erro daquela linha
• Erro em uma linha não bloqueia as outras: as válidas são criadas e a resposta diz quais falharam
• Duplicata dentro do próprio lote (mesmo external_source e external_id duas vezes) cria a primeira e falha a segunda

---

Exemplo de requisição

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 }]
      }
    ]
  }'

---

Exemplos de resposta

O lote responde 200, e não 201: numa chamada que cria algumas linhas e falha outras, o status sozinho não diz o resultado. Quem diz é o corpo. Confira sempre failed e errors, nunca só o código HTTP.

Resultados mistos (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 item em results contém:

• external_id: identifica a transação no seu sistema.
• tx_id: UUID gerado pela Rapid (guarde para operações futuras).
• warnings: avisos de campos ausentes (não bloqueiam a criação).

Cada item em errors contém:

• index: posição da linha no array que você enviou, começando em zero. É por aqui que você localiza a linha quando o campo inválido é justamente o external_id.
• external_id: identifica qual transação falhou, ou string vazia se o valor enviado não era válido.
• status: código HTTP equivalente do erro (422 validação, 404 merchant inexistente, 409 duplicata).
• error: mensagem descritiva.

created + failed é sempre o total de linhas enviadas. results e errors saem na ordem de entrada.

Todas criadas com sucesso (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": []
  }
}

Linha com campo inválido (200)

Uma linha reprovada na validação não derruba as outras: ela aparece em errors com 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)"
      }
    ]
  }
}

Erro de validação do batch (fora do array)

Se o array transactions estiver vazio, faltando ou exceder 1000 itens, a requisição inteira é rejeitada:

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

---

Comportamentos do lote que vale conhecer

• merchant_ref desconhecido cria o vendedor (com merchant_name, se enviado) e não retorna 404.
• Duplicata dentro do mesmo lote (mesmo external_source/external_id duas vezes) falha na segunda linha com TRANSACTION_DUPLICATE; a primeira é criada.
• A ordem de results é a ordem de entrada.