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 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 |
| 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.
Editar Fatura
Faturas draft e open aceitam a edição de todos os campos. Depois de liquidada — paid, void ou uncollectible — a fatura mantém as condições travadas:
| Status | Campos editáveis |
|---|---|
| draft, open | Todos |
| paid | ID público, assinatura, descrição, itens, metadados, ID externo, política de emissão da NF-e e linha de descrição da NF-e |
| void, uncollectible | ID público, assinatura, descrição, itens, metadados e ID externo |
Empresa, método de cobrança, política de juros e multa, vencimento, competência e rodapé ficam travados. Os itens podem ser corrigidos (no formulário via API ou na edição inline da aba de itens, depois de um aviso), mas não enquanto a fatura tiver NF-e emitida ou em processamento — cancele a nota antes. A regra vale no dashboard, na API e no MCP: mudar um campo travado responde 422 com o código INVOICE_FIELD_LOCKED, listando os campos recusados. Reenviar um campo travado com o mesmo valor já gravado não é considerado mudança.
Finalizar (draft → open)
Ao finalizar uma fatura:
- Valida que existe pelo menos 1 line item
- Valida que a soma das parcelas = total (se parcelada)
- Calcula impostos automaticamente
- Aplica créditos automaticamente (FIFO: expiração mais próxima primeiro, depois mais antigo)
- 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.
