# Lote de enrollments

> Pede até 500 enrollments numa chamada, de vários merchants, no modo parcial (padrão) ou tudo ou nada, com o resultado de cada item na ordem enviada.

Página: https://doc.rapidchargeback.com/canais/enrollments/lote-de-enrollments/

Pede até **500 enrollments** numa chamada, de um ou vários merchants. Cada item segue a regra de [Pedir enrollment](https://doc.rapidchargeback.com/canais/enrollments/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](https://doc.rapidchargeback.com/canais/merchants/guia-de-sincronizacao/)).

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/enrollments/batch
```

## Autenticação

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

---

## 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](https://doc.rapidchargeback.com/canais/enrollments/pedir-enrollment/#corpo-da-requisição), 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 `items` e `mode` no envelope, `items` vazio ou com mais de 500: o lote inteiro é recusado com `422 VALIDATION_ERROR`, sem gravar nada.

### Modos

| `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

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 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

```bash
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

### Sucesso

`200 OK` sempre que o lote foi processado, mesmo com itens recusados. Confira `failed` e o `result` de cada item.

```json
{
  "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](https://doc.rapidchargeback.com/canais/enrollments/pedir-enrollment/#criado) |
| `results[].status`, `results[].error` | No erro: o HTTP que o item teria sozinho e o erro (`code`, `message`, `params`) |

### Tudo ou nada recusado

```
HTTP/1.1 422 Unprocessable Entity
```

```json
{
  "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

```
HTTP/1.1 429 Too Many Requests
Retry-After: 5
```

```json
{
  "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

| 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` |

---

## Notas

- **Repetir é seguro.** Depois de um `503` ou de uma queda de conexão, mande o mesmo lote: o que já foi gravado volta `existing`. Se receber `BATCH_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](https://doc.rapidchargeback.com/referencia/autenticacao/) e [Códigos de resposta](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/).
