> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción

> Gestiona los clientes de tus transacciones.

## ¿Qué es un Cliente?

Un cliente es la representación de una persona natural o jurídica dentro de OnePay. Es el objeto central al que se asocian métodos de pago (tarjetas, cuentas bancarias), cobros y dispersiones.

**Debes crear un cliente antes de poder:**

* Registrar tarjetas o cuentas bancarias
* Crear cargos (débitos directos)
* Enviar dispersiones (payouts)
* Crear suscripciones

## ¿Cuándo crear un Cliente?

| Escenario                                        | ¿Necesitas un cliente?                |
| ------------------------------------------------ | ------------------------------------- |
| Enviar un link de pago (`POST /payments`)        | No (solo necesitas `phone` o `email`) |
| Debitar una tarjeta o cuenta (`POST /charges`)   | Sí                                    |
| Dispersar dinero a un tercero (`POST /cashouts`) | Sí                                    |
| Crear una suscripción recurrente                 | Sí                                    |
| Emitir una tarjeta (Issuing)                     | Sí                                    |

## Tipos de cliente

* **`natural`**: Persona natural (identificada con CC, CE o PASSPORT)
* **`company`**: Persona jurídica (identificada con NIT)

## Ejemplo rápido

```bash theme={null}
curl https://api.onepay.la/v1/customers \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: cli-001" \
  -d '{
    "user_type": "natural",
    "first_name": "María",
    "last_name": "López",
    "email": "maria@ejemplo.com",
    "phone": "+573201112233",
    "document_type": "CC",
    "document_number": "1060500333"
  }'
```

## Relaciones

```
Cliente
  ├── Cuentas bancarias (/accounts)
  ├── Tarjetas (/cards)
  ├── Suscripciones (/subscriptions)
  ├── Tarjetas emitidas (/issuing/cards)
  └── Billetera (/wallets)
```

Para consultar los métodos de pago de un cliente específico, usa:

* [Cuentas del cliente](accounts) - `GET /customers/{id}/accounts`
* [Tarjetas del cliente](cards) - `GET /customers/{id}/cards`
* [Tarjetas emitidas](issuing-cards) - `GET /customers/{id}/issuing-cards`

## Endpoints

| Método   | Endpoint                  | Descripción           |
| -------- | ------------------------- | --------------------- |
| `POST`   | [/customers](create)      | Crear cliente         |
| `GET`    | [/customers](list)        | Listar clientes       |
| `GET`    | [/customers/{id}](detail) | Detalle de un cliente |
| `DELETE` | [/customers/{id}](delete) | Eliminar cliente      |