Cuentas

CRUD sobre las cuentas financieras de tu empresa (banco, efectivo, PayPal, Stripe, caja chica). Los incomes y expenses se asocian siempre a una cuenta, y la cuenta lleva su balance corriente.

Las cuentas del sistema (las que Finova crea internamente para transferencias y depósitos) son visibles vía GET /accounts pero no pueden modificarse ni eliminarse por API — recibirás 403 system_account_protected.

El objeto Account

{
  "id":            "65b3a1f1234567890abcdef0",
  "name":          "BBVA MXN",
  "description":   "Cuenta principal de operaciones.",
  "account_type":  "bank",
  "currency":      "mxn",
  "balance_cents": 1837500,
  "balance":       18375.0,
  "created_at":    "2026-01-15T14:23:11Z",
  "updated_at":    "2026-05-20T09:01:42Z"
}

Campos

Campo	Tipo	Descripción
id	string	ObjectId.
name	string	Nombre interno.
description	string	Descripción libre.
account_type	enum	bank, cash, paypal, stripe, petty_cash, other.
currency	string	ISO 4217 lowercase (mxn, usd).
balance_cents	integer	Balance corriente en centavos.
balance	float	Mismo balance como decimal (sólo lectura, redondeado a 2).
created_at / updated_at	string	ISO 8601 UTC.

---

Listar cuentas

GET/api/v1/accountsread-accounts

Lista todas las cuentas (incluye las del sistema). Soporta los mismos query params de paginación que el resto de la API (guía).

cURL

curl 'https://developers.fi-nova.com/api/v1/accounts' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'

JavaScript

const res = await fetch(
  'https://developers.fi-nova.com/api/v1/accounts',
  { headers: { Authorization: 'Bearer finova_sk_TU_SECRETO' } }
);
const { data } = await res.json();

---

Obtener una cuenta

GET/api/v1/accounts/:idread-accounts

---

Crear una cuenta

POST/api/v1/accountscreate-accounts

Campos aceptados en data: name, description, account_type, currency, balance_cents.

balance_cents inicial debe coincidir con el saldo real de la cuenta el día que la das de alta. Finova mantendrá el balance a partir de ahí sumando ingresos y restando egresos.

cURL

curl -X POST https://developers.fi-nova.com/api/v1/accounts \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "name":          "BBVA MXN",
      "account_type":  "bank",
      "currency":      "mxn",
      "balance_cents": 1837500
    }
  }'

---

Actualizar una cuenta

PUT/api/v1/accounts/:idupdate-accounts

Campos modificables: name, description, currency, balance_cents. El account_type no se permite cambiar después de crear la cuenta porque cambia la semántica de los reportes (caja vs. banco).

---

Eliminar una cuenta

DELETE/api/v1/accounts/:iddelete-accounts

Eliminar una cuenta también decrementa el balance global de tu empresa en esa moneda. Si la cuenta tiene movimientos asociados (incomes, expenses, transfers), esos quedan huérfanos del lado de la cuenta — considera transferir primero el saldo a otra cuenta si quieres preservar la historia limpia.

Cuentas del sistema (system: true) no se pueden eliminar — 403 system_account_protected.