Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

Cria ou atualiza até 500 merchants numa chamada. Cada item segue exatamente a regra de Criar ou atualizar merchant: a chave é o merchant_ref, o que não mudou não é gravado, e repetir o lote não duplica nada.

O lote é sempre parcial: cada item é gravado ou recusado por conta própria, e a resposta diz o que aconteceu com cada um, na mesma ordem do envio.

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

CampoTipoObrigatórioDescrição
itemsarraySimDe 1 a 500 merchants, cada um com os campos de Criar ou atualizar merchant
on_name_conflictenumNãoerror (padrão) ou append_ref, para todos os itens. O on_name_conflict de um item vale mais que este
  • Corpo de até 5 MB. Acima disso, 413 PAYLOAD_TOO_LARGE.
  • Campo fora de items e on_name_conflict no envelope, items vazio ou com mais de 500: o lote inteiro é recusado com 422 VALIDATION_ERROR, sem gravar nada.

O primeiro item vale; os seguintes são recusados, sem gravar:

  • mesmo merchant_ref (sem diferenciar maiúsculas nem acentos): MERCHANT_REF_DUPLICATE_IN_BATCH;
  • mesmo name em referências diferentes (sem append_ref): MERCHANT_NAME_DUPLICATE_IN_BATCH.

Janela do 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 sempre que o lote foi processado, mesmo com itens recusados. Confira failed e o result de cada item.

{
"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" }
}
}
]
}
}
CampoDescrição
totalItens enviados
succeededItens criados, atualizados ou sem mudança (total - failed)
failedItens recusados
countsQuantos de cada: created, updated, unchanged
resultsUm por item, na ordem do array enviado
results[].indexPosição do item no array enviado, a partir de 0
results[].resultcreated, updated, unchanged ou error
results[].merchant_refO merchant_ref que você mandou no item (null se não veio texto)
results[].merchantNo sucesso: o resumo do merchant, o mesmo de Listar merchants
results[].warningsQuando houver: o aviso SERVICE_FIELDS_NOT_APPLIED (ver Aviso de dado que não vale na hora)
results[].statusNo erro: o HTTP que o item teria sozinho
results[].errorNo erro: code, message e, quando houver, params

Os erros de cada item são os de Criar ou atualizar merchant, mais os dois de repetidos no 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."
}
}

A sua empresa tem um lote de merchants por vez. O segundo lote enviado enquanto o primeiro ainda está sendo gravado é recusado inteiro, sem gravar nada: espere o Retry-After e mande de novo.

HTTPCódigoQuando
422VALIDATION_ERROREnvelope inválido: items ausente, vazio, com mais de 500, ou campo desconhecido no envelope
413PAYLOAD_TOO_LARGECorpo acima de 5 MB
429RATE_LIMIT_EXCEEDEDMais de 60 escritas por minuto (cada lote conta uma)
429BATCH_IN_PROGRESSOutro lote de merchants da sua empresa ainda em andamento
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDVer Criar ou atualizar merchant
503SERVICE_UNAVAILABLEIndisponibilidade temporária: repita depois do Retry-After

  • Repetir é seguro. Depois de um 503 ou de uma queda de conexão, mande o mesmo lote: o que já foi gravado volta unchanged.
  • Volume: 3.000 merchants são 6 chamadas de 500. Mande um lote depois do outro, não em paralelo.
  • Auth, rate limit, códigos de erro: ver Autenticação e Códigos de resposta.