Faturas geradas automaticamente, com NFe e retenções aplicadas.
Worker dedicado processa faturamento diário às 01:00 UTC. PDF, link de pagamento, NFe e webhooks gerados sem intervenção manual.
Funcionalidade
5
estados de fatura
24/7
geração automática
PDF
gerado nativamente
NFe
vinculada automaticamente
Estados modelados em InvoiceStatus
Draft
Criada mas ainda não finalizada. Pode ser editada (line items, valores, vencimento).
- Próximo: → open (via finalize)
Open
Finalizada e enviada ao cliente. Aguardando pagamento. Régua de comunicação ativa.
- Próximo: → paid | void | uncollectible
Paid
Quitada. paidAt registrado. NFe emitida se nfeIssuancePolicy = on_full_payment. Webhook invoice.paid disparado.
- Estado final (refund gera novo Payment)
Void
Anulada manualmente. Não afeta MRR retroativamente. voidedAt + razão registrados.
- Estado final
Uncollectible
Marcada como perda de receita. Usada em write-offs contábeis. Gerada pelo dunning após esgotar tentativas.
- Estado final
O que você pode fazer
Geração Automática
Worker invoice-generation (diário 01:00 UTC) varre subscriptions com currentPeriodEnd ≤ hoje e gera faturas idempotentes.
- Idempotência via (subscription_id, period_start)
- Reason rastreado (subscription_cycle | subscription_create | manual)
- Skip de faturas em trial sem cartão
Composição de Valores
Cada fatura calcula subtotal + tax − discount = total. Retenções na fonte subtraídas do valor líquido (netValueCents).
- Discount: cupons + créditos aplicados automaticamente
- Tax: ISS + outros conforme TaxRule
- Withholdings: IRRF, CSRF, INSS, ISS retido
Line Items Detalhados
InvoiceLineItem por produto/serviço. type distingue subscription, addon, usage, one-off, proration, tax, discount.
- Período coberto (periodStart / periodEnd)
- ServiceItem vinculado (LC 116 para NFS-e)
- Proration details em JSON quando aplicável
Geração de PDF
PDF profissional renderizado server-side via PDFKit. Layout customizável por empresa (logo, cores, campos extras).
- Download individual ou em lote
- URL assinada com expiração
- Storage S3 com path por organização
Envio Automático por Email
Email transacional via AWS SES. Templates configuráveis por organização. Variáveis dinâmicas (nome, valor, vencimento, link).
- Template padrão pronto para uso
- Editor HTML/texto livre
- Tracking de delivery (em desenvolvimento)
Lembretes Pré-Vencimento
Régua de comunicação configurável: −7, −3, −1 dias e dia do vencimento. Pós-vencimento até suspensão.
- Email, in-app, webhook
- Pausável por cliente
- Templates personalizáveis por evento
Fatura Manual / Avulsa
Crie faturas one-off sem vincular a assinatura. Útil para serviços pontuais, ajustes, cobranças complementares.
- Line items livres
- Vencimento e desconto configuráveis
- Mesmo fluxo de NFe e cobrança
Vinculação com NFe
nfeIssuancePolicy define quando emitir: disabled, on_finalization, on_full_payment, per_installment.
- NFS-e via NFe.io ou provider próprio
- Retry automático em falhas (worker nfe-retry a cada 30min)
- Cancelamento via API
Criar fatura avulsa via API
bash
curl -X POST https://api.billing.kobana.com.br/v1/invoices \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"billing_account_id": "ba_abc123",
"due_date": "2026-06-30",
"collection_method": "manual_charge",
"line_items": [
{
"description": "Consultoria sob demanda — Junho/2026",
"quantity": 8,
"unit_amount_cents": 25000,
"service_item_id": "svc_consultoria"
}
]
}'response
{
"id": "inv_xyz789",
"number": "INV-001234",
"status": "draft",
"subtotal_cents": 200000,
"tax_cents": 5000,
"total_cents": 205000,
"due_date": "2026-06-30",
"pdf_url": "https://billing.kobana.com.br/.../inv_xyz789.pdf"
}