# Clientes (/docs/customers)

<Endpoint method="POST" path="/v1/customers" href="/docs/api/customers/create-customer" />

Un cliente se registra con **tu propio identificador** (`external_id`), así lo encuentras siempre desde tu sistema.

| Campo | Obligatorio | Qué es |
| --- | --- | --- |
| `external_id` | Sí | Tu id, hasta 128 caracteres. |
| `type` | Sí | `individual` o `business`. |
| `country` | Sí | País de residencia o constitución (ISO alfa-2). |
| `display_name` | Sí | Nombre, hasta 200 caracteres. |
| `profile` | Según el país | Datos de identidad (abajo). |
| `metadata` | No | Hasta 20 claves tuyas. Nunca datos personales. |

## El perfil [#el-perfil]

| Campo | Para |
| --- | --- |
| `first_name`, `last_name` | Personas. Van juntos. |
| `date_of_birth` | Personas, `AAAA-MM-DD`. |
| `identity_document_type`, `identity_document` | Van juntos. Tipos: `DNI`, `RUC`, `CE`, `PAS`, `PTP`, `PASSPORT`, `NATIONAL_ID`, `RESIDENCE_PERMIT`, `TAX_ID`, `DRIVER_LICENSE`. |
| `identity_document_country` | País que emitió el documento. |
| `email`, `phone`, `tax_id` | Contacto e impuestos. |
| `registration_number` | Empresas. |
| `address` | `line1`, `line2`, `city`, `state`, `postal_code`, `country`. |

**Qué pide cada país** lo dice `customer_fields` en capabilities. Por ejemplo, un pago en soles pide que el remitente sea una persona (`individual`) con nombre, apellidos, fecha de nacimiento, documento y ciudad.

<Callout type="warn" title="Completa el perfil antes de pagar">
Los datos del remitente se validan cuando el pago sale al banco, no al crearlo. Un pago con un remitente incompleto se acepta y luego falla con `failure_code: invalid_instruction`. Valida el perfil contra `customer_fields` antes de pagar.
</Callout>

## Repetir el registro [#repetir-el-registro]

Si envías otra vez el mismo `external_id` con los mismos datos, recibes el cliente existente (`200`). Con otros datos, `409 external_id_conflict`.

## Estados [#estados]

| `status` | Qué significa |
| --- | --- |
| `active` | Normal. |
| `blocked` | Caibo lo detuvo: no se paga a sus beneficiarios. |
| `closed` | Cerrado, definitivo. |

Con <Endpoint method="PATCH" path="/v1/customers/{id}" href="/docs/api/customers/update-customer" /> cambias `metadata` o lo cierras (`status: closed`). `compliance_status` (`unverified`, `pending`, `verified`, `rejected`, `review`) lo cambian solo las verificaciones de Caibo.

Eventos: `customer.created`, `customer.updated`, `customer.status_changed`. Los eventos nunca incluyen el perfil.