Lote de enrollments
Pede até 500 enrollments numa chamada, de um ou vários merchants. Cada item segue a regra de Pedir enrollment: os mesmos campos, os mesmos erros, e o pedido repetido volta existing, sem criar outro.
Peça cada enrollment uma vez, quando o vendedor entra na sua base: não inclua os enrollments num envio diário (ver Guia de sincronização).
Endpoint
Seção intitulada “Endpoint”https://api.rapidchargeback.com/api/v1/enrollments/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 pedidos, cada um com os campos de Pedir enrollment, inclusive o merchant_id ou merchant_ref próprio |
mode | enum | Não | partial (padrão) ou all_or_nothing |
- Corpo de até 2 MB. Acima disso,
413 PAYLOAD_TOO_LARGE. - Campo fora de
itemsemodeno envelope,itemsvazio ou com mais de 500: o lote inteiro é recusado com422 VALIDATION_ERROR, sem gravar nada.
mode | O que acontece |
|---|---|
partial | Cada item é gravado ou recusado por conta própria. existing conta como sucesso |
all_or_nothing | A Rapid confere todos os itens antes. Se algum falhar, nada é gravado e o lote volta 422 ENROLLMENT_BATCH_INVALID com a lista dos itens recusados. existing não conta como falha; ENROLLMENT_PREVIOUSLY_REJECTED conta |
Repetidos no mesmo lote
Seção intitulada “Repetidos no mesmo lote”O mesmo identificador em dois itens do lote (descriptor sem diferenciar maiúsculas, espaços repetidos nem espaços em volta do *, ou o mesmo BIN + CAID): o primeiro vale e os seguintes são recusados com ENROLLMENT_DUPLICATE_IN_BATCH.
Teto de pendentes
Seção intitulada “Teto de pendentes”Se os pedidos novos do lote passarem a sua empresa de 20.000 enrollments esperando aprovação, o lote inteiro é recusado com 422 ENROLLMENT_PENDING_LIMIT, sem gravar nada.
Exemplo de requisição
Seção intitulada “Exemplo de requisição”curl -X POST https://api.rapidchargeback.com/api/v1/enrollments/batch \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \ -H "Content-Type: application/json" \ -d '{ "mode": "partial", "items": [ { "merchant_ref": "PB-1001", "enrollment_type": "descriptor", "descriptor_value": "LOJA EXEMPLO", "descriptor_rule": "exact", "products": ["alert"] }, { "merchant_ref": "PB-1002", "enrollment_type": "bin_caid", "bin": "424242", "caid": "123456789", "products": ["alert"] }, { "merchant_ref": "PB-1002", "enrollment_type": "descriptor", "descriptor_value": "loja exemplo", "descriptor_rule": "exact", "products": ["alert"] } ] }'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, "existing": 1 }, "results": [ { "index": 0, "result": "existing", "merchant_ref": "PB-1001", "enrollment": { "id": "00000000-0000-0000-0000-0000000000aa", "merchant_id": "00000000-0000-0000-0000-000000000001", "merchant_ref": "PB-1001", "enrollment_type": "descriptor", "descriptor_value": "loja exemplo", "descriptor_rule": "exact", "bin": null, "caid": null, "arn": null, "products": { "alert": { "status": "active", "rejection_reason": null, "approved_at": "2026-11-07T15:00:00.000Z" }, "prevention": null }, "created_at": "2026-11-06T12:00:00.000Z", "updated_at": "2026-11-07T15:00:00.000Z" } }, { "index": 1, "result": "created", "merchant_ref": "PB-1002", "enrollment": { "id": "00000000-0000-0000-0000-0000000000ab", "...": "objeto Enrollment" } }, { "index": 2, "result": "error", "merchant_ref": "PB-1002", "status": 422, "error": { "code": "ENROLLMENT_DUPLICATE_IN_BATCH", "message": "Descriptor \"loja exemplo\" appears more than once in the batch", "params": { "identifier": "Descriptor \"loja exemplo\"" } } } ] }}| Campo | Descrição |
|---|---|
total, succeeded, failed | Itens enviados, aceitos (created ou existing) e recusados |
counts | Quantos de cada: created, existing |
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, existing ou error |
results[].merchant_ref | O merchant_ref que você mandou no item (null se veio merchant_id) |
results[].enrollment | No sucesso: o objeto Enrollment, o mesmo de Pedir enrollment |
results[].status, results[].error | No erro: o HTTP que o item teria sozinho e o erro (code, message, params) |
Tudo ou nada recusado
Seção intitulada “Tudo ou nada recusado”HTTP/1.1 422 Unprocessable Entity{ "error": { "code": "ENROLLMENT_BATCH_INVALID", "message": "1 of 3 items were not accepted. Nothing was created.", "params": { "count": 1, "total": 3 }, "details": { "errors": [ { "index": 2, "code": "ENROLLMENT_DUPLICATE_IN_BATCH", "message": "Descriptor \"loja exemplo\" appears more than once in the batch", "params": { "identifier": "Descriptor \"loja exemplo\"" } } ] } }}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 enrollments por vez. O segundo lote enviado enquanto o primeiro ainda está sendo gravado é recusado inteiro: 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, mode fora da lista ou campo desconhecido no envelope |
| 422 | ENROLLMENT_BATCH_INVALID | Tudo ou nada com algum item recusado (params.count, params.total, details.errors) |
| 422 | ENROLLMENT_PENDING_LIMIT | O lote passaria a sua empresa de 20.000 pendentes (params.limit) |
| 413 | PAYLOAD_TOO_LARGE | Corpo acima de 2 MB |
| 429 | RATE_LIMIT_EXCEEDED | Mais de 60 escritas por minuto (cada lote conta uma) |
| 429 | BATCH_IN_PROGRESS | Outro lote de enrollments da sua empresa ainda em andamento |
| 403 | KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKED | Empresa sem cadastro aprovado, inativa ou bloqueada |
| 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 voltaexisting. Se receberBATCH_IN_PROGRESS, o lote anterior ainda está sendo gravado: espere e repita. - 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.