Ingresos

CRUD sobre los ingresos (ventas) de tu empresa. Cada ingreso pertenece a una cuenta y opcionalmente a un cliente, una categoría, un proyecto y un empleado/vendedor.

Efectos colaterales

Crear un Income por API dispara los mismos efectos que crearlo desde la app:

• Suma amount_cents (o paid_amount_cents si lo envías) al balance de la cuenta — crea un Deposit interno.
• Si los items referencian productos, incrementa los contadores de venta de cada producto.
• Si los productos tienen inventario activado, reserva los materiales/unidades correspondientes.
• Dispara automatizaciones con trigger sale_created que estén activas.

Period locking: si tu contabilidad cerró el periodo (mes) al que pertenece occurred_at, recibirás 422 period_locked. La API key no puede saltarse cierres — usa la app web si necesitas re-abrir.

El objeto Income

{
  "id":                       "65c2a1f1234567890abcdef0",
  "occurred_at":              "2026-05-20T14:23:11Z",
  "description":              "Servicio web cliente Laura",
  "amount_cents":             1500000,
  "amount":                   15000.0,
  "paid_amount_cents":        1500000,
  "paid_amount":              15000.0,
  "currency":                 "mxn",
  "paid":                     true,
  "refunded":                 false,
  "from_account_receivable":  false,
  "account_id":               "65b3a1f1234567890abcdef0",
  "account_name":             "BBVA MXN",
  "customer_id":              "65a1b2c3d4e5f6789012abcd",
  "customer_name":            "Laura Méndez",
  "category_id":              null,
  "category_name":            "Servicios",
  "project_id":               null,
  "project_name":             null,
  "employee_id":              null,
  "employee_name":            null,
  "created_at":               "2026-05-20T14:23:12Z",
  "updated_at":               "2026-05-20T14:23:12Z"
}

Sobre GET /incomes/:id el response también incluye items (line items embedded).

Campos

Campo	Tipo	Descripción
id	string	ObjectId.
occurred_at	string	Fecha del ingreso (ISO 8601).
description	string	Texto libre.
amount_cents / amount	int / float	Total en centavos / decimal.
paid_amount_cents	int	Monto efectivamente cobrado (puede ser menor a amount_cents para crédito parcial).
currency	string	ISO 4217 lowercase.
paid	bool	true si está cobrado al 100% — false genera una cuenta por cobrar.
refunded	bool	Marca si fue reembolsado.
from_account_receivable	bool	true cuando el ingreso se creó al cerrar un AR (no lo envíes manualmente).
account_id / account_name	string	Cuenta destino.
customer_id / customer_name	string	Cliente (opcional).
category_id / category_name	string	Categoría (opcional).
project_id / project_name	string	Proyecto (opcional).
employee_id / employee_name	string	Vendedor / responsable (opcional).

---

Listar ingresos

GET/api/v1/incomesread-incomes

Paginado estándar. Ver guía de paginación.

Acepta search (alias q): búsqueda full-text/autocomplete sobre description, category_name, customer_name, employee_name y account_name. Devuelve hasta los 100 ingresos más relevantes, luego paginados.

---

Obtener un ingreso

GET/api/v1/incomes/:idread-incomes

Devuelve el ingreso completo incluyendo items (line items embedded).

---

Crear un ingreso

POST/api/v1/incomescreate-incomes

Campos aceptados en data: account_id (requerido), customer_id, category_id, amount_cents (requerido), paid_amount_cents, currency, occurred_at, description, paid, project_id, employee_id, items.

items es un array de line items embedded. Cada item:

Campo	Tipo	Descripción
name	string	Etiqueta del concepto.
quantity	number	Cantidad.
unit_price_cents	int	Precio unitario en centavos.
product_id	string	Asocia a un producto del catálogo (opcional).
variant_id	string	Para productos variables.
tax_percent	float	Tasa de impuesto del item.
discount_cents	int	Descuento aplicado al item.

Al leer (GET /incomes/:id), cada item incluye además su id y unit_price (decimal, espejo de unit_price_cents).

cURL

curl -X POST https://developers.fi-nova.com/api/v1/incomes \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "account_id":   "65b3a1f1234567890abcdef0",
      "customer_id":  "65a1b2c3d4e5f6789012abcd",
      "amount_cents": 1500000,
      "currency":     "mxn",
      "occurred_at":  "2026-05-20T14:23:11Z",
      "description":  "Servicio web cliente Laura",
      "paid":         true,
      "items": [
        { "name": "Diseño", "quantity": 1, "unit_price_cents": 1500000 }
      ]
    }
  }'

---

Actualizar un ingreso

PUT/api/v1/incomes/:idupdate-incomes

Mismos campos que create. Si cambias occurred_at a otro periodo, ambos periodos deben estar abiertos — si alguno está bloqueado, 422 period_locked.

---

Eliminar un ingreso

DELETE/api/v1/incomes/:iddelete-incomes

Eliminar revierte los efectos colaterales (depósito, balance de cuenta, contadores de producto, reserva de inventario). Si el ingreso está en un periodo cerrado, recibes 422 period_locked.