Faturas

Faturas representam cobranças enviadas aos clientes. Cada fatura contém line items detalhando os produtos e valores cobrados.

Estados da Fatura

draft → open → paid
  ↓       ↓
 void  uncollectible

Status	Descrição
draft	Rascunho. Pode ser editada, ter itens adicionados/removidos
open	Finalizada. Cobrável, pode receber pagamentos e ter créditos aplicados
paid	Totalmente paga
void	Anulada. Créditos aplicados são restaurados, parcelas canceladas
uncollectible	Marcada como incobrável (write-off)

Campos da Fatura

Identificação

Campo	Descrição
Número	Número sequencial único (formato: INV-YYYY-NNNNNN)
Conta de cobrança	Cliente que receberá a fatura
Assinatura	Assinatura associada (opcional)
Empresa	Empresa emissora (para multi-empresa)

Valores (em centavos, ÷100 para reais)

Campo	Descrição
Subtotal	Soma dos line items antes de descontos e impostos
Desconto	Total de desconto aplicado
Impostos	Total de impostos calculados
Total retido	Impostos retidos (PIS/COFINS/IRPJ)
Valor líquido	Valor líquido após retenções
Total	Valor final (subtotal - desconto + impostos)
Valor devido	Montante total a pagar
Valor pago	Montante já recebido
Valor restante	Saldo pendente

Configuração

Campo	Descrição
Método de cobrança	charge_automatically, manual_charge ou manual_invoice
Razão de cobrança	subscription_cycle, subscription_create, subscription_update ou manual
Política de NF-e	disabled, on_finalization, on_full_payment ou per_installment
Data de vencimento	Calculada a partir dos dias de prazo do cliente

Line Items

Cada fatura contém itens de linha que detalham as cobranças:

Campo	Descrição
Tipo	subscription ou invoiceitem
Descrição	Texto descritivo
Quantidade	Quantidade cobrada
Valor unitário	Preço por unidade (em centavos)
Valor total	Quantidade × valor unitário
Proration	Se o item é um rateio proporcional
Período	Início e fim do período cobrado

Operações

Criar Fatura

Ao criar uma fatura, informe:

• Conta de cobrança (obrigatório)
• Line items com descrição, quantidade e valor
• Data de vencimento (ou usa os dias de prazo do cliente)
• Parcelas (opcional, mínimo 2, soma deve ser igual ao total)
• Política de NF-e (opcional)

O número da fatura é gerado automaticamente usando lock advisory do PostgreSQL para prevenir duplicação.

Finalizar (draft → open)

Ao finalizar uma fatura:

1. Valida que existe pelo menos 1 line item
2. Valida que a soma das parcelas = total (se parcelada)
3. Calcula impostos automaticamente
4. Aplica créditos automaticamente (FIFO: expiração mais próxima primeiro, depois mais antigo)
5. Se o método for charge_automatically: tenta cobrar imediatamente

Marcar como Paga

• Suporta pagamentos parciais
• Ao receber o valor total, o status muda para paid
• Cria um registro de transação

Anular (Void)

Ao anular uma fatura:

• Créditos aplicados são restaurados automaticamente
• Parcelas pendentes são canceladas
• O motivo da anulação é armazenado

Desfazer Pagamento

Reverte uma fatura de paid para open:

• Reseta o valor pago para zero
• Cria uma transação de ajuste (valor negativo)
• Armazena o motivo no metadata

Marcar como Incobrável

Marca a fatura como write-off. Irreversível. Nenhuma tentativa automática de pagamento será feita.

Geração Automática de Números

Os números de fatura são gerados sequencialmente por ano usando advisory locks do PostgreSQL. Formato: INV-{ano}-{sequencial com 6 dígitos}.

Exemplo: INV-2026-000147

Capturas de tela

Lista de faturas

A tela /dashboard/invoices lista todas as faturas com filtros por status, conta de cobrança, empresa emissora, período e meio de pagamento. Cada linha mostra número, cliente, valor, vencimento, status e ações rápidas (baixar PDF, copiar boleto/PIX, marcar como paga).

Detalhe da fatura

A página /dashboard/invoices/[id] mostra a fatura completa: itens (com quantidade e valor unitário), totais, descontos, créditos aplicados, impostos retidos, histórico de pagamentos, NF-e vinculada e linha do tempo de eventos.