# Cuentas del contacto

Estos métodos trabajan con las [cuentas del contacto](https://support.cleverapp.pro/es/chatbots/contacts/accounts-referrals#cuentas), un saldo interno en el bot: bonos, puntos, un depósito. Son las mismas cuentas con las que trabajan los bloques [Recargar la cuenta del contacto](https://support.cleverapp.pro/es/chatbots/blocks/contact-data/top-up-balance) y [Cargo en la cuenta del contacto](https://support.cleverapp.pro/es/chatbots/blocks/contact-data/debit-balance), y que se muestran en la pestaña «Cuentas» de la ficha del contacto. Por ejemplo, un sistema de pagos puede abonar bonos al contacto tras una compra en tu sitio web, y el bot puede mostrar el saldo con la función `getBalance`.

Un contacto tiene una cuenta independiente para cada moneda. Las operaciones de la API aparecen en el historial de la cuenta como «Abono por API» y «Cargo por API».

> [!WARNING]
> Las cuentas del contacto son saldos internos del bot (bonos, puntos, depósito), no cuentas bancarias: la plataforma no transfiere dinero a través de ellas y no es un servicio de pagos. Lleva un registro de las operaciones que envías por la API en tu propio sistema; te servirá para conciliar los saldos.

> [!IMPORTANT]
> Los importes se envían y se devuelven **en las unidades menores de la moneda** (céntimos) como un entero. `15000` en una cuenta `USD` significa 150 $. En las monedas sin parte fraccionaria, como `JPY`, la unidad es el yen entero. Una sola recarga o un solo cargo es como máximo de 10¹⁴ unidades menores (un billón de dólares en USD); un importe mayor devuelve `422`.

## getContactAccounts

Devuelve todas las cuentas de un contacto.

```endpoint
GET POST https://app.cleverapp.pro/api/v1/getContactAccounts
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | entero | sí | ID del contacto |

```bash title="Solicitud"
curl -G "https://app.cleverapp.pro/api/v1/getContactAccounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "contact_id=678"
```
```json title="Respuesta 200"
{
  "data": [
    {
      "id": 4521,
      "currency": "USD",
      "amount": 15000,
      "amount_note": "150 USD",
      "created_at": "2026-09-14T10:22:05+00:00",
      "updated_at": "2026-10-01T18:40:12+00:00",
      "blocked_at": null
    }
  ]
}
```

| Campo | Descripción |
|---|---|
| `id` | ID de la cuenta: pásalo a los demás métodos como `account_id` |
| `currency` | Código de moneda ISO 4217 |
| `amount` | Saldo en las unidades menores de la moneda |
| `amount_note` | Saldo en unidades mayores con el código de moneda, para mostrarlo |
| `created_at`, `updated_at` | Cuándo se abrió la cuenta y cuándo cambió por última vez |
| `blocked_at` | Cuándo se bloqueó la cuenta; `null`, no está bloqueada. No se puede hacer un cargo en una cuenta bloqueada |

Las cuentas se listan en el orden en que se abrieron.

## addContactAccount

Abre al contacto una cuenta en una moneda. El mismo método también está disponible como `createContactAccount`.

```endpoint
POST https://app.cleverapp.pro/api/v1/addContactAccount
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | entero | sí | ID del contacto |
| `currency` | cadena | sí | Código de moneda ISO 4217 en mayúsculas: `USD`, `EUR`, `GBP` |

```bash title="Solicitud"
curl -X POST "https://app.cleverapp.pro/api/v1/addContactAccount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "currency": "USD"}'
```
```json title="Respuesta 201"
{
  "data": {
    "id": 4521,
    "currency": "USD",
    "amount": 0,
    "amount_note": "0 USD",
    "created_at": "2026-10-03T12:00:00+00:00",
    "updated_at": "2026-10-03T12:00:00+00:00",
    "blocked_at": null
  }
}
```
```json title="Respuesta 422"
{
  "message": "Account with the currency already exists",
  "code": "currency_exists",
  "errors": {
    "currency": [
      "Account with the currency already exists"
    ]
  }
}
```

Detalles:

- Si el contacto ya tiene una cuenta en esta moneda: `422` con un error en el campo `currency`.
- Los bloques del flujo no necesitan la cuenta de antemano: el bloque «Recargar la cuenta del contacto» la abre por sí mismo. Los métodos de recarga de la API sí la necesitan, porque trabajan por `account_id`.

## deleteContactAccount

Elimina una cuenta del contacto.

```endpoint
POST https://app.cleverapp.pro/api/v1/deleteContactAccount
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account_id` | entero | sí | ID de la cuenta |

```bash title="Solicitud"
curl -X POST "https://app.cleverapp.pro/api/v1/deleteContactAccount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521}'
```
```json title="Respuesta 422"
{
  "message": "You can not delete the account with a balance of 150 USD",
  "code": "account_not_empty",
  "errors": {
    "account_id": [
      "You can not delete the account with a balance of 150 USD"
    ]
  }
}
```

La respuesta tiene el estado `204` y no tiene cuerpo.

Solo se puede eliminar una cuenta vacía. Si tiene dinero: `422` con un error en el campo `account_id`; primero carga el saldo restante.

## addFundsToContactAccount

Recarga una cuenta.

```endpoint
POST https://app.cleverapp.pro/api/v1/addFundsToContactAccount
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account_id` | entero | sí | ID de la cuenta |
| `amount` | entero | sí | Importe en las unidades menores de la moneda, de 1 a 100 000 000 000 000 (10¹⁴) |
| `description` | cadena | sí | Concepto del abono, hasta 255 caracteres. Se registra en el historial de la cuenta |

```bash title="Solicitud"
curl -X POST "https://app.cleverapp.pro/api/v1/addFundsToContactAccount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 15000, "description": "Bono por el pedido A-1024"}'
```
```json title="Respuesta 200"
{
  "data": {
    "id": 4521,
    "currency": "USD",
    "amount": 15000,
    "amount_note": "150 USD",
    "created_at": "2026-10-03T12:00:00+00:00",
    "updated_at": "2026-10-03T12:05:41+00:00",
    "blocked_at": null
  }
}
```

Una cuenta bloqueada se puede recargar igualmente.

## withdrawFundsFromContactAccount

Hace un cargo en una cuenta.

```endpoint
POST https://app.cleverapp.pro/api/v1/withdrawFundsFromContactAccount
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account_id` | entero | sí | ID de la cuenta |
| `amount` | entero | sí | Importe en las unidades menores de la moneda, de 1 a 100 000 000 000 000 (10¹⁴) |
| `description` | cadena | sí | Concepto del cargo, hasta 255 caracteres. Se registra en el historial de la cuenta |

```bash title="Solicitud"
curl -X POST "https://app.cleverapp.pro/api/v1/withdrawFundsFromContactAccount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 5000, "description": "Gastos de envío"}'
```
```json title="Respuesta 200"
{
  "data": {
    "id": 4521,
    "currency": "USD",
    "amount": 10000,
    "amount_note": "100 USD",
    "created_at": "2026-10-03T12:00:00+00:00",
    "updated_at": "2026-10-03T12:07:15+00:00",
    "blocked_at": null
  }
}
```
```json title="Respuesta 422"
{
  "message": "Insufficient funds. Current balance 100 USD",
  "code": "insufficient_funds",
  "errors": {
    "account_id": [
      "Insufficient funds. Current balance 100 USD"
    ]
  }
}
```

Un cargo nunca deja la cuenta por debajo de cero, ni siquiera con solicitudes simultáneas. Si el cargo no es posible, el método no cambia nada y responde con `422` y un error en el campo `account_id`:

| `code` | Motivo |
|---|---|
| `account_blocked` | La cuenta está bloqueada: desbloquéala en la ficha del contacto |
| `insufficient_funds` | La cuenta tiene menos que `amount`; el texto muestra el saldo actual |

Primero se comprueba el bloqueo y luego el saldo.

## Errores de las cuentas

- No hay ningún contacto o cuenta con ese ID, el contacto está eliminado o su bot está eliminado: `404`.
- Contacto o cuenta de un bot ajeno: `403`.
- Los errores propios de estos métodos son `422` con los campos `message`, `code` y `errors`. El texto del error está en el idioma de la solicitud (el encabezado `Accept-Language`), así que en tu código comprueba `code`:

| `code` | Método | Motivo |
|---|---|---|
| `currency_exists` | `addContactAccount` | Ya existe una cuenta en esta moneda |
| `account_not_empty` | `deleteContactAccount` | La cuenta todavía tiene dinero |
| `account_blocked` | `withdrawFundsFromContactAccount` | La cuenta está bloqueada |
| `insufficient_funds` | `withdrawFundsFromContactAccount` | No hay dinero suficiente en la cuenta |

Los errores generales de la API se describen en [Errores](https://support.cleverapp.pro/es/api#errores).