# Lote de enrollments

> Solicita hasta 500 enrollments en una llamada, de varios merchants, en modo parcial (por defecto) o todo o nada, con el resultado de cada ítem en el orden enviado.

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

Solicita hasta **500 enrollments** en una llamada, de uno o varios merchants. Cada ítem sigue la regla de [Solicitar enrollment](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-enrollment/): los mismos campos, los mismos errores, y la solicitud repetida vuelve `existing`, sin crear otra.

Solicita cada enrollment una vez, cuando el vendedor entra en tu base: no incluyas los enrollments en un envío diario (ver [Guía de sincronización](https://doc.rapidchargeback.com/es/canais/merchants/guia-de-sincronizacao/)).

## Endpoint

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

## Autenticación

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

---

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `items` | array | Sí | De 1 a 500 solicitudes, cada una con los campos de [Solicitar enrollment](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-enrollment/#cuerpo-de-la-solicitud), incluido su propio `merchant_id` o `merchant_ref` |
| `mode` | enum | No | `partial` (por defecto) o `all_or_nothing` |

- Cuerpo de hasta **2 MB**. Por encima, `413 PAYLOAD_TOO_LARGE`.
- Un campo distinto de `items` y `mode` en el envoltorio, o `items` vacío o con más de 500: el lote entero se rechaza con `422 VALIDATION_ERROR`, sin guardar nada.

### Modos

| `mode` | Qué pasa |
|---|---|
| `partial` | Cada ítem se guarda o se rechaza por su cuenta. `existing` cuenta como éxito |
| `all_or_nothing` | Rapid revisa todos los ítems antes. Si alguno falla, no se guarda nada y el lote vuelve `422 ENROLLMENT_BATCH_INVALID` con la lista de los ítems rechazados. `existing` no cuenta como falla; `ENROLLMENT_PREVIOUSLY_REJECTED` sí |

### Repetidos en el mismo lote

El mismo identificador en dos ítems del lote (descriptor sin distinguir mayúsculas, espacios repetidos ni espacios alrededor del `*`, o el mismo BIN + CAID): el primero vale y los siguientes se rechazan con `ENROLLMENT_DUPLICATE_IN_BATCH`.

### Tope de pendientes

Si las solicitudes nuevas del lote llevan a tu empresa por encima de **20.000** enrollments esperando aprobación, el lote entero se rechaza con `422 ENROLLMENT_PENDING_LIMIT`, sin guardar nada.

---

## Ejemplo de solicitud

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

---

## Respuesta

### Éxito

`200 OK` siempre que el lote se procesó, incluso con ítems rechazados. Revisa `failed` y el `result` de cada ítem.

```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 | Descripción |
|---|---|
| `total`, `succeeded`, `failed` | Ítems enviados, aceptados (`created` o `existing`) y rechazados |
| `counts` | Cuántos de cada uno: `created`, `existing` |
| `results` | Uno por ítem, en el orden del array enviado |
| `results[].index` | Posición del ítem en el array enviado, desde 0 |
| `results[].result` | `created`, `existing` o `error` |
| `results[].merchant_ref` | El `merchant_ref` que enviaste en el ítem (`null` si vino `merchant_id`) |
| `results[].enrollment` | En el éxito: el objeto Enrollment, el mismo de [Solicitar enrollment](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-enrollment/#creado) |
| `results[].status`, `results[].error` | En el error: el HTTP que el ítem tendría solo y el error (`code`, `message`, `params`) |

### Todo o nada rechazado

```
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\"" }
        }
      ]
    }
  }
}
```

### Otro lote en curso

```
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."
  }
}
```

Tu empresa tiene un lote de enrollments a la vez. El segundo lote enviado mientras el primero todavía se está guardando se rechaza entero: espera el `Retry-After` y envíalo de nuevo.

### Errores del lote entero

| HTTP | Código | Cuándo |
|---|---|---|
| 422 | `VALIDATION_ERROR` | Envoltorio inválido: `items` ausente, vacío, con más de 500, `mode` fuera de la lista o campo desconocido en el envoltorio |
| 422 | `ENROLLMENT_BATCH_INVALID` | Todo o nada con algún ítem rechazado (`params.count`, `params.total`, `details.errors`) |
| 422 | `ENROLLMENT_PENDING_LIMIT` | El lote llevaría a tu empresa por encima de 20.000 pendientes (`params.limit`) |
| 413 | `PAYLOAD_TOO_LARGE` | Cuerpo por encima de 2 MB |
| 429 | `RATE_LIMIT_EXCEEDED` | Más de 60 escrituras por minuto (cada lote cuenta como una) |
| 429 | `BATCH_IN_PROGRESS` | Otro lote de enrollments de tu empresa todavía en curso |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Empresa sin registro aprobado, inactiva o bloqueada |
| 503 | `SERVICE_UNAVAILABLE` | No disponible temporalmente: repite después del `Retry-After` |

---

## Notas

- **Repetir es seguro.** Después de un `503` o de una caída de conexión, envía el mismo lote: lo que ya se guardó vuelve `existing`. Si recibes `BATCH_IN_PROGRESS`, el lote anterior todavía se está guardando: espera y repite.
- **Envía un lote después del otro**, no en paralelo.
- **Auth, rate limit, códigos de error:** ver [Autenticación](https://doc.rapidchargeback.com/es/referencia/autenticacao/) y [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/).
