# Cuenta y transacciones

> Consultar la cuenta principal del alcance, su saldo exacto y el historial de transacciones con filtros por tipo y fechas.

## Cuenta principal

`GET /api/v1/client/account` · scope `account:read`.

Devuelve siempre la cuenta del **titular** del alcance, aunque el token pertenezca a un master.

```json
{
  "data": {
    "account_id": "10",
    "uid": "uid_…",
    "balance": "150000.00",
    "currency": "COP",
    "status": "active",
    "created_at": "2026-05-22T15:00:00-05:00",
    "updated_at": null
  },
  "meta": { "api_version": "1", "request_id": "req_…" },
  "errors": []
}
```

- `account_id` es una cadena opaca; no la conviertas a número.
- `balance` es un decimal exacto con dos decimales históricos o cuatro para COP operativo (por ejemplo `"0.0001"`). El SDK conserva la escala y el texto; para operar con él usa una biblioteca decimal (`big.js`, `decimal.js`, `bcmath`…).
- `created_at` siempre está presente: contiene un instante RFC 3339 o `null` si la cuenta no tiene fecha de creación registrada. El SDK lo conserva como `createdAt: Rfc3339Instant | null`, sin sustituir la fecha ausente.

```js
const cuenta = await client.account.get();
console.log(`${cuenta.balance} ${cuenta.currency}`);
```

Si el titular no tiene cuenta digital, la respuesta es `404 RESOURCE_NOT_FOUND`.

## Historial de transacciones

`GET /api/v1/client/account/transactions` · scope `account:transactions:read`.

| Parámetro | Detalle |
| --- | --- |
| `cursor`, `limit` | Paginación (ver [paginación](/docs/paginacion)); `limit` 1..100 |
| `type` | Tipo de transacción del libro (por ejemplo `deposito`, `retiro`); un tipo inexistente responde `422 VALIDATION_ERROR` |
| `from`, `to` | Ventana `AAAA-MM-DD` |

Cada transacción:

```json
{
  "transaction_id": "9812",
  "account_id": "10",
  "subaccount_id": "3",
  "type": "deposito",
  "amount": "50000.00",
  "balance_before": "100000.00",
  "balance_after": "150000.00",
  "description": "Abono orden 2501",
  "reference": "DEP-2026-0042",
  "occurred_at": "2026-09-02T10:15:00-05:00",
  "currency": "COP"
}
```

No se exponen la IP, el operador ni otros datos internos del asiento.

```js
const historial = await client.account.transactions({ from: '2026-09-01', to: '2026-09-30', limit: 100 });
for (const tx of historial.items) {
  console.log(tx.occurredAt, tx.type, tx.amount, tx.balanceAfter);
}
```