# Solicitar enrollment

> Solicita el enrollment de un descriptor o BIN + CAID para un merchant. La solicitud pasa por la aprobación del equipo de Rapid; repetirla devuelve el mismo enrollment.

Página: https://doc.rapidchargeback.com/es/canais/enrollments/pedir-enrollment/

Solicita un enrollment para un merchant de tu empresa (ver [Enrollments: visión general](https://doc.rapidchargeback.com/es/canais/enrollments/visao-geral/)). Todo producto solicitado nace `pending` y pasa por la aprobación del equipo de Rapid. Solicitar de nuevo el mismo enrollment devuelve el que ya existe, sin crear otro.

Para varios a la vez, incluso de merchants distintos, usa el [Lote de enrollments](https://doc.rapidchargeback.com/es/canais/enrollments/lote-de-enrollments/).

## Endpoint

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

## Autenticación

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

---

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `merchant_id` | string (UUID) | Uno de los dos | El `id` del merchant |
| `merchant_ref` | string (hasta 100) | Uno de los dos | El ID del vendedor en tu sistema (ver [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/)) |
| `enrollment_type` | enum | Sí | `descriptor` o `bin_caid`, sin distinguir mayúsculas |
| `descriptor_value` | string (hasta 255) | En `descriptor` | El nombre en el resumen del titular |
| `descriptor_rule` | enum | En `descriptor` | `exact` (igual) o `startswith` (empieza con, al menos 5 caracteres) |
| `bin` | string | En `bin_caid` | Solo dígitos, de 6 a 10 |
| `caid` | string (hasta 50) | En `bin_caid` | El identificador de la tienda en el adquirente |
| `arn` | string (hasta 100) | No | Acquirer Reference Number de una transacción de la tienda, cuando lo tengas |
| `products` | array | Sí | `alert`, `prevention` o los dos, sin repetir |
| `retry_rejected` | boolean | No | `true` para solicitar de nuevo un identificador que el equipo rechazó (ver [Rechazado antes](#rechazado-antes)). Por defecto `false` |

- Envía `merchant_id` **o** `merchant_ref`, nunca los dos.
- El texto se recorta. Un campo fuera de la tabla se rechaza con `422 VALIDATION_ERROR` (`Unknown field: <nombre>`).
- `prevention` exige el merchant con `store_name`, `merchant_url` y `contact_phone` y, según el caso, dirección completa y los datos de la tienda (descripción, logo, MCC, términos, política de reembolso y atención). Si falta algo, `422 MERCHANT_INCOMPLETE_FOR_PREVENTION` lo indica en `params.fields`.

---

## Solicitud repetida y conflictos

| Situación | Respuesta |
|---|---|
| El identificador ya está en uso **en el mismo merchant**, con el mismo tipo, la misma regla y todos los productos solicitados | `200`, `meta.result: "existing"`, con el enrollment que ya existe. No se guarda nada |
| En uso en tu empresa fuera de ese caso (otro merchant, otra regla, falta un producto) | `409 ENROLLMENT_DUPLICATE`, con `enrollment_id` y `merchant_id` del enrollment en uso |
| En uso por otra empresa | `409 ENROLLMENT_DUPLICATE`, solo con el identificador |
| Rechazado antes por el equipo | `409 ENROLLMENT_PREVIOUSLY_REJECTED` (ver abajo) |

"En uso" es `pending`, `active` o `deactivation_requested`. La comparación del descriptor ignora mayúsculas, espacios repetidos y espacios alrededor del `*`.

### Rechazado antes

Si el equipo rechazó la última solicitud de ese identificador para el mismo merchant y tipo, y no hay nada en uso para él, solicitarlo de nuevo responde `409 ENROLLMENT_PREVIOUSLY_REJECTED`, con el `enrollment_id` de la solicitud rechazada y el `rejection_reason`, cuando el equipo escribió el motivo. Así un reenvío automático no vuelve a poner en la cola una solicitud ya rechazada.

Corrige lo que motivó el rechazo y envíala con `retry_rejected: true` para solicitarla de nuevo. Un identificador desactivado a tu pedido (`inactive`) no bloquea: el vendedor que vuelve se puede solicitar normalmente.

---

## Ejemplo de solicitud

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/enrollments \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ref": "PB-1001",
    "enrollment_type": "descriptor",
    "descriptor_value": "LOJA EXEMPLO",
    "descriptor_rule": "exact",
    "products": ["alert"]
  }'
```

---

## Respuesta

### Creado

```
HTTP/1.1 201 Created
```

```json
{
  "data": {
    "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": "pending", "rejection_reason": null, "approved_at": null },
      "prevention": null
    },
    "created_at": "2026-11-06T12:00:00.000Z",
    "updated_at": "2026-11-06T12:00:00.000Z"
  },
  "meta": { "result": "created" }
}
```

| Campo | Descripción |
|---|---|
| `id` | ID del enrollment. Es el `merchant_enrollment_id` de las alertas que coincidan con él |
| `merchant_id`, `merchant_ref` | El merchant del enrollment (`merchant_ref` es `null` si el merchant no tiene referencia) |
| `enrollment_type` | `descriptor` o `bin_caid` |
| `descriptor_value`, `descriptor_rule` | En `descriptor`. El valor sale guardado en minúsculas |
| `bin`, `caid` | En `bin_caid` |
| `arn` | El ARN informado, o `null` |
| `products.alert`, `products.prevention` | `null` si el producto no se solicitó; si no, `status`, `rejection_reason` (motivo del rechazo) y `approved_at` (cuándo se aprobó) |
| `created_at`, `updated_at` | Cuándo se solicitó y cuándo cambió por última vez |

Los estados están en [Estado de cada producto](https://doc.rapidchargeback.com/es/canais/enrollments/visao-geral/#estado-de-cada-producto).

### Ya existía

`200 OK`, con el enrollment existente y `"meta": { "result": "existing" }`.

### Identificador en uso

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "ENROLLMENT_DUPLICATE",
    "message": "Descriptor \"LOJA EXEMPLO\" is already in use on the platform",
    "params": { "identifier": "Descriptor \"LOJA EXEMPLO\"" }
  }
}
```

### Rechazado antes

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "ENROLLMENT_PREVIOUSLY_REJECTED",
    "message": "This identifier was rejected in a previous request. Send retry_rejected: true to request it again.",
    "params": {
      "enrollment_id": "00000000-0000-0000-0000-0000000000aa",
      "rejection_reason": "Descriptor no encontrado en las transacciones de la tienda"
    }
  }
}
```

### Errores

| HTTP | Código | Cuándo |
|---|---|---|
| 404 | `MERCHANT_NOT_FOUND` | El merchant no existe en tu empresa |
| 409 | `ENROLLMENT_DUPLICATE` | Identificador en uso (`params.identifier`; `enrollment_id` y `merchant_id` cuando es de tu empresa) |
| 409 | `ENROLLMENT_PREVIOUSLY_REJECTED` | Rechazado antes; envía `retry_rejected: true` para solicitarlo de nuevo |
| 409 | `MERCHANT_REF_CONFLICT` | El `merchant_ref` solo difiere del guardado en mayúsculas o acentos (`params.merchant_id`, `params.merchant_ref`) |
| 422 | `FIELD_REQUIRED` | Falta un campo obligatorio (`params.field`) |
| 422 | `FIELD_TOO_LONG` | Campo por encima del límite (`params.field`, `params.max`) |
| 422 | `FIELD_INVALID_OPTION` | Valor fuera de la lista (`params.field`, `params.options`) |
| 422 | `FIELD_INVALID` | Valor inválido, como un producto repetido (`params.field`) |
| 422 | `BIN_INVALID` | `bin` fuera de 6 a 10 dígitos |
| 422 | `VALIDATION_ERROR` | Campo desconocido, `merchant_id` y `merchant_ref` juntos o ninguno de los dos (`params.field`) |
| 422 | `DESCRIPTOR_LOOKS_LIKE_BIN_CAID` | El descriptor parece un BIN/CAID: solicítalo como `bin_caid` |
| 422 | `DESCRIPTOR_PREFIX_TOO_SHORT` | `startswith` con menos de 5 caracteres (`params.min`) |
| 422 | `ENROLLMENT_NO_PRODUCT` | `products` vacío |
| 422 | `PROVIDER_UNAVAILABLE` | El producto no acepta ese tipo de enrollment (`params.product`, `params.type`) |
| 422 | `MERCHANT_INCOMPLETE_FOR_PREVENTION` | Faltan datos de registro del merchant para la Prevención (`params.fields`) |
| 422 | `ENROLLMENT_PENDING_LIMIT` | Tu empresa ya tiene 20.000 enrollments esperando aprobación (`params.limit`) |
| 403 | `PRODUCT_NOT_ACTIVE` | Tu empresa no tiene el producto activo (`params.product`) |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Empresa sin registro aprobado, inactiva o bloqueada |
| 429 | `RATE_LIMIT_EXCEEDED` | Más de 60 escrituras por minuto |
| 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 la misma solicitud: si ya se guardó, vuelve `existing`.
- **Las solicitudes sueltas durante un lote** de tu empresa esperan a que el lote termine y pueden recibir `503`. Envía las sueltas después del lote.
- **La API no aprueba** ni elige nada más allá de la solicitud: la aprobación es siempre del equipo de Rapid. La respuesta llega al responsable de tu cuenta en el panel y por correo, y la ves en la [lista de enrollments](https://doc.rapidchargeback.com/es/canais/enrollments/listar-enrollments/).
- **Actividad:** cada solicitud aparece en la Actividad del panel como hecha por la integración.
