Facturas generadas automáticamente, con NFe y retenciones aplicadas.
Worker dedicado procesa la facturación diaria a las 01:00 UTC. PDF, link de pago, NFe y webhooks generados sin intervención manual.
Funcionalidad
5
estados de factura
24/7
generación automática
PDF
generado nativamente
NFe
vinculada automáticamente
Estados modelados en InvoiceStatus
Draft
Creada pero aún no finalizada. Puede editarse (line items, valores, vencimiento).
- Siguiente: → open (vía finalize)
Open
Finalizada y enviada al cliente. Esperando pago. Régua de comunicación activa.
- Siguiente: → paid | void | uncollectible
Paid
Liquidada. paidAt registrado. NFe emitida si nfeIssuancePolicy = on_full_payment. Webhook invoice.paid disparado.
- Estado final (reembolso genera nuevo Payment)
Void
Anulada manualmente. No afecta MRR retroactivamente. voidedAt + razón registrados.
- Estado final
Uncollectible
Marcada como pérdida de ingresos. Usada en write-offs contables. Generada por el dunning al agotar intentos.
- Estado final
Qué puedes hacer
Generación Automática
Worker invoice-generation (diario 01:00 UTC) recorre subscriptions con currentPeriodEnd ≤ hoy y genera facturas idempotentes.
- Idempotencia vía (subscription_id, period_start)
- Razón trazada (subscription_cycle | subscription_create | manual)
- Skip de facturas en trial sin tarjeta
Composición de Valores
Cada factura calcula subtotal + impuesto − descuento = total. Retenciones en la fuente sustraídas del valor neto (netValueCents).
- Descuento: cupones + créditos aplicados automáticamente
- Impuesto: ISS + otros conforme TaxRule
- Retenciones: IRRF, CSRF, INSS, ISS retenido
Line Items Detallados
InvoiceLineItem por producto/servicio. type distingue subscription, addon, usage, one-off, proration, tax, discount.
- Período cubierto (periodStart / periodEnd)
- ServiceItem vinculado (LC 116 para NFS-e)
- Proration details en JSON cuando aplique
Generación de PDF
PDF profesional renderizado server-side vía PDFKit. Layout personalizable por empresa (logo, colores, campos extras).
- Descarga individual o en lote
- URL firmada con expiración
- Storage S3 con path por organización
Envío Automático por Email
Email transaccional vía AWS SES. Templates configurables por organización. Variables dinámicas (nombre, valor, vencimiento, link).
- Template estándar listo para usar
- Editor HTML/texto libre
- Seguimiento de delivery (en desarrollo)
Recordatorios Pre-Vencimiento
Régua de comunicación configurable: −7, −3, −1 días y día del vencimiento. Post-vencimiento hasta suspensión.
- Email, in-app, webhook
- Pausable por cliente
- Templates personalizables por evento
Factura Manual / Avulsa
Crea facturas one-off sin vincular a suscripción. Útil para servicios puntuales, ajustes, cobros complementarios.
- Line items libres
- Vencimiento y descuento configurables
- Mismo flujo de NFe y cobro
Vinculación con NFe
nfeIssuancePolicy define cuándo emitir: disabled, on_finalization, on_full_payment, per_installment.
- NFS-e vía NFe.io o provider propio
- Retry automático en fallos (worker nfe-retry cada 30min)
- Cancelación vía API
Crear factura puntual vía API
bash
curl -X POST https://api.billing.kobana.com.br/v1/invoices \
-H "Authorization: Bearer $KOBANA_TOKEN" \
-H "X-Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"billing_account_id": "8f3b2c1a-5d4e-4f6a-9b7c-2e1d0a9f8b7c",
"due_date": "2026-06-30",
"collection_method": "manual_charge",
"line_items": [
{
"description": "Consultoría bajo demanda — Junio/2026",
"quantity": 8,
"unit_amount": 250.0,
"service_item_id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f"
}
]
}'response
{
"data": {
"id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"number": "INV-001234",
"status": "draft",
"subtotal": 2000.0,
"tax": 0,
"total": 2000.0,
"due_date": "2026-06-30"
}
}