Cuentas del contacto#

Estos métodos trabajan con las cuentas del contacto, 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 y Cargo en la cuenta del contacto, 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».

Advertencia

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.

Importante

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.

curl -G "https://app.cleverapp.pro/api/v1/getContactAccounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "contact_id=678"

{
  "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
    }
  ]
}

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.

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

{
  "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
  }
}

{
  "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.

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}'

{
  "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.

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

{
  "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.

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

{
  "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
  }
}

{
  "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:

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:

Los errores generales de la API se describen en Errores.