Facturas
Las facturas representan cobros enviados a los clientes. Cada factura contiene line items que detallan los productos y valores cobrados.
Estados de la Factura
draft → open → paid
↓ ↓
void uncollectible
| Status | Descripción |
|---|---|
| draft | Borrador. Puede ser editada, se pueden agregar/eliminar ítems |
| open | Finalizada. Cobrable, puede recibir pagos y tener créditos aplicados |
| paid | Totalmente pagada |
| void | Anulada. Los créditos aplicados son restaurados, las cuotas canceladas |
| uncollectible | Marcada como incobrable (write-off) |
Campos de la Factura
Identificación
| Campo | Descripción |
|---|---|
| Número | Número secuencial único (formato: INV-YYYY-NNNNNN) |
| Cuenta de cobro | Cliente que recibirá la factura |
| Suscripción | Suscripción asociada (opcional) |
| Empresa | Empresa emisora (para multi-empresa) |
Valores (en centavos, ÷100 para reales)
| Campo | Descripción |
|---|---|
| Subtotal | Suma de los line items antes de descuentos e impuestos |
| Descuento | Total de descuento aplicado |
| Impuestos | Total de impuestos calculados |
| Total retenido | Impuestos retenidos (PIS/COFINS/IRPJ) |
| Valor neto | Valor neto después de retenciones |
| Total | Valor final (subtotal - descuento + impuestos) |
| Valor adeudado | Monto total a pagar |
| Valor pagado | Monto ya recibido |
| Valor restante | Saldo pendiente |
Configuración
| Campo | Descripción |
|---|---|
| Método de cobro | charge_automatically, manual_charge o manual_invoice |
| Razón de cobro | subscription_cycle, subscription_create, subscription_update o manual |
| Política de NF-e | disabled, on_finalization, on_full_payment o per_installment |
| Fecha de vencimiento | Calculada a partir de los días de plazo del cliente |
Line Items
Cada factura contiene ítems de línea que detallan los cobros:
| Campo | Descripción |
|---|---|
| Tipo | subscription o invoiceitem |
| Descripción | Texto descriptivo |
| Cantidad | Cantidad cobrada |
| Valor unitario | Precio por unidad (en centavos) |
| Valor total | Cantidad × valor unitario |
| Proration | Si el ítem es un prorrateo proporcional |
| Período | Inicio y fin del período cobrado |
Operaciones
Crear Factura
Al crear una factura, informe:
- Cuenta de cobro (obligatorio)
- Line items con descripción, cantidad y valor
- Fecha de vencimiento (o usa los días de plazo del cliente)
- Cuotas (opcional, mínimo 2, la suma debe ser igual al total)
- Política de NF-e (opcional)
El número de la factura se genera automáticamente usando lock advisory de PostgreSQL para prevenir duplicación.
Finalizar (draft → open)
Al finalizar una factura:
- Valida que exista al menos 1 line item
- Valida que la suma de las cuotas = total (si tiene cuotas)
- Calcula impuestos automáticamente
- Aplica créditos automáticamente (FIFO: vencimiento más próximo primero, luego más antiguo)
- Si el método es
charge_automatically: intenta cobrar inmediatamente
Marcar como Pagada
- Soporta pagos parciales
- Al recibir el valor total, el status cambia a
paid - Crea un registro de transacción
Anular (Void)
Al anular una factura:
- Los créditos aplicados son restaurados automáticamente
- Las cuotas pendientes son canceladas
- El motivo de la anulación es almacenado
Deshacer Pago
Revierte una factura de paid a open:
- Restablece el valor pagado a cero
- Crea una transacción de ajuste (valor negativo)
- Almacena el motivo en el metadata
Marcar como Incobrable
Marca la factura como write-off. Irreversible. Ningún intento automático de pago será realizado.
Generación Automática de Números
Los números de factura se generan secuencialmente por año usando advisory locks de PostgreSQL. Formato: INV-\{año\}-\{secuencial con 6 dígitos\}.
Ejemplo: INV-2026-000147