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 BRL)
| 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 |
| 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.
Editar Factura
Las facturas draft y open aceptan la edición de todos los campos. Una vez liquidada — paid, void o uncollectible — la factura mantiene sus condiciones bloqueadas:
| Estado | Campos editables |
|---|---|
| draft, open | Todos |
| paid | ID público, suscripción, descripción, ítems, metadatos, ID externo, política de emisión de la NF-e y línea de descripción de la NF-e |
| void, uncollectible | ID público, suscripción, descripción, ítems, metadatos e ID externo |
Empresa, método de cobro, política de intereses y multa, vencimiento, período y pie de página quedan bloqueados. Los ítems pueden corregirse (por la API o con la edición inline de la pestaña de ítems, tras un aviso), pero no mientras la factura tenga una NF-e emitida o en proceso — cancélela antes. La regla vale en el dashboard, la API y el MCP: cambiar un campo bloqueado responde 422 con el código INVOICE_FIELD_LOCKED, listando los campos rechazados. Reenviar un campo bloqueado con el mismo valor ya guardado no se considera un cambio.
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
Capturas de pantalla
Lista de facturas
La pantalla /dashboard/invoices lista todas las facturas con filtros por status, cuenta de cobro, empresa emisora, período y medio de pago. Cada fila muestra el número, el cliente, el valor, el vencimiento, el status y acciones rápidas (descargar PDF, copiar boleto/PIX, marcar como pagada).
Detalle de la factura
La página /dashboard/invoices/[id] muestra la factura completa: ítems (con cantidad y valor unitario), totales, descuentos, créditos aplicados, impuestos retenidos, historial de pagos, NF-e vinculada y línea de tiempo de eventos.
