Cuenta y transacciones · Zafirox SDK

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.

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

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); `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:

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

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);
}