Lote de merchants
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.
Endpoint
Seção intitulada “Endpoint”https://api.rapidchargeback.com/api/v1/merchants/batchAutenticação
Seção intitulada “Autenticação”Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonCorpo da requisição
Seção intitulada “Corpo da requisição”| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items | array | Sim | De 1 a 500 merchants, cada um com os campos de Criar ou atualizar merchant |
on_name_conflict | enum | Não | error (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
itemseon_name_conflictno envelope,itemsvazio ou com mais de 500: o lote inteiro é recusado com422 VALIDATION_ERROR, sem gravar nada.
Repetidos no mesmo lote
Seção intitulada “Repetidos no mesmo lote”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
nameem referências diferentes (semappend_ref):MERCHANT_NAME_DUPLICATE_IN_BATCH.
Exemplo de requisição
Seção intitulada “Exemplo de requisição”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" } ] }'Resposta
Seção intitulada “Resposta”Sucesso
Seção intitulada “Sucesso”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" } } } ] }}| Campo | Descrição |
|---|---|
total | Itens enviados |
succeeded | Itens criados, atualizados ou sem mudança (total - failed) |
failed | Itens recusados |
counts | Quantos de cada: created, updated, unchanged |
results | Um por item, na ordem do array enviado |
results[].index | Posição do item no array enviado, a partir de 0 |
results[].result | created, updated, unchanged ou error |
results[].merchant_ref | O merchant_ref que você mandou no item (null se não veio texto) |
results[].merchant | No sucesso: o resumo do merchant, o mesmo de Listar merchants |
results[].warnings | Quando houver: o aviso SERVICE_FIELDS_NOT_APPLIED (ver Aviso de dado que não vale na hora) |
results[].status | No erro: o HTTP que o item teria sozinho |
results[].error | No 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.
Outro lote em andamento
Seção intitulada “Outro lote em andamento”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." }}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.
Erros do lote inteiro
Seção intitulada “Erros do lote inteiro”| HTTP | Código | Quando |
|---|---|---|
| 422 | VALIDATION_ERROR | Envelope inválido: items ausente, vazio, com mais de 500, ou campo desconhecido no envelope |
| 413 | PAYLOAD_TOO_LARGE | Corpo acima de 5 MB |
| 429 | RATE_LIMIT_EXCEEDED | Mais de 60 escritas por minuto (cada lote conta uma) |
| 429 | BATCH_IN_PROGRESS | Outro lote de merchants da sua empresa ainda em andamento |
| 403 | KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKED | Ver Criar ou atualizar merchant |
| 503 | SERVICE_UNAVAILABLE | Indisponibilidade temporária: repita depois do Retry-After |
- Repetir é seguro. Depois de um
503ou de uma queda de conexão, mande o mesmo lote: o que já foi gravado voltaunchanged. - 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.