Crédito pré-pago é um ledger, não só um saldo

Um saldo é simples de mostrar e perigoso de editar.

Se o cliente tem 100 créditos e consome 7, parece suficiente salvar 93. Essa conta funciona enquanto ninguém precisa explicar o passado.

O número não explica a diferença

Quando o saldo diverge, as perguntas chegam rápido:

• quais eventos consumiram crédito;
• se algum evento foi processado duas vezes;
• quando entrou um bônus;
• qual ajuste foi manual;
• quanto precisa voltar depois de um estorno;
• qual versão do preço converteu uso em crédito.

Uma coluna balance não responde nenhuma delas. Ela guarda o resultado e apaga o cálculo.

Movimentos primeiro, saldo depois

Um ledger registra movimentos. Cada crédito ou débito tem valor, motivo, data e uma chave que identifica a operação de origem.

O saldo é derivado dessa sequência:

+100  compra de pacote
-  7  consumo do evento evt_01
+ 10  crédito promocional
- 12  consumo do evento evt_02
-----
  91  saldo atual

Isso muda a forma de corrigir um erro. Em vez de editar 91 para 98, você adiciona um movimento de correção de 7 com uma justificativa. O histórico continua fechando.

Consumo também precisa de identidade

O identificador do evento de uso é parte da regra financeira.

Se uma retentativa envia o mesmo consumo de novo, a chave permite devolver o resultado anterior sem criar outro débito. Sem essa identidade, a aplicação precisa decidir pela semelhança dos dados — e dois consumos legítimos podem ser idênticos.

Idempotência não é só proteção de API. É o que torna o ledger reproduzível.

Reserva e consumo são decisões diferentes

Alguns produtos só sabem o custo depois de terminar o trabalho. Uma geração pode usar mais tokens; um job pode processar mais registros; uma exportação pode falhar no meio.

Nesses casos, há duas operações possíveis:

1. reservar uma estimativa antes de executar;
2. confirmar o custo real e liberar a diferença depois.

Misturar reserva e débito definitivo cria saldo fantasma. Separá-los deixa claro quanto está disponível, quanto está comprometido e quanto foi realmente consumido.

A regra prática

Se qualquer pessoa pode perguntar “por que esse saldo é esse?”, você já precisa de movimentos.

O saldo continua existindo para leitura rápida. Só deixa de ser a única verdade do sistema.

Na Infi, créditos e consumo fazem parte do mesmo fluxo de medição e cobrança. O ponto de partida está no guia do SDK.