Créditos

O sistema de créditos permite adicionar saldo na conta do cliente que é automaticamente aplicado em faturas futuras.

Tipos de Crédito

Tipo	Descrição
promotional	Créditos promocionais (podem expirar)
adjustment	Ajustes administrativos de saldo
refund	Crédito gerado por reembolso
manual	Adição manual de crédito

Campos do Crédito

Campo	Descrição
Conta de cobrança	Cliente que recebe o crédito
Empresa	Empresa emissora (para escopo de aplicação)
Tipo	Tipo do crédito
Valor (centavos)	Valor total do crédito
Valor restante	Saldo ainda não utilizado
Descrição	Motivo ou descrição do crédito
Expira em	Data de expiração (null = nunca expira)

Aplicação Automática de Créditos

Quando uma fatura é finalizada, o sistema aplica créditos automaticamente usando a estratégia FIFO:

Ordem de Aplicação

1. Créditos que expiram mais cedo (prioridade para evitar perda)
2. Créditos mais antigos (quando a data de expiração é igual)

Regras de Escopo por Empresa

• Se a fatura tem empresa: aplica créditos da mesma empresa e créditos sem empresa
• Se a fatura não tem empresa: aplica apenas créditos sem empresa

Processo (em transação atômica)

1. Busca créditos não expirados com saldo disponível
2. Para cada crédito: aplica o mínimo entre (saldo do crédito, valor restante da fatura)
3. Cria registro de CreditApplication para rastreabilidade
4. Atualiza o saldo do crédito e da fatura
5. Se a fatura for totalmente paga: marca como paid
6. Atualiza o balanceCents da conta de cobrança

Restauração de Créditos

Quando uma fatura é anulada (void), todos os créditos aplicados são restaurados:

• Cada crédito tem seu saldo restante aumentado
• Os registros de CreditApplication são removidos
• A fatura volta ao status open
• O saldo da conta de cobrança é atualizado

Expiração de Créditos

Créditos com data de expiração são automaticamente zerados quando a data passa:

• O amountRemaining é definido como 0
• O saldo da conta de cobrança é reduzido

Operações

• Adicionar crédito: Cria crédito e incrementa o saldo da conta
• Ajustar saldo: Adiciona ou subtrai créditos
• Crédito de reembolso: Cria crédito do tipo refund
• Crédito promocional: Cria crédito com expiração opcional
• Deletar crédito: Apenas se nunca utilizado (saldo restante = valor total)
• Consultar saldo disponível: Retorna total disponível, créditos ativos e créditos expirando

Captura de tela

A tela /dashboard/credits lista todos os créditos da organização, com filtros por status, origem (downgrade, refund, ajuste manual, promoção), conta de cobrança e período. A interface também permite criar créditos avulsos e ver o saldo agregado por cliente.