O que é o ledger
O ledger (livro-razão) da ClearPago registra todos os movimentos financeiros confirmados da sua conta. Cada operação Pix que alcança um estado terminal de sucesso gera um lançamento com tipo, valor em centavos, referência à transação de origem e timestamp.
O ledger é a fonte primária para:
- Cálculo de saldo disponível.
- Reconciliação financeira com o seu ERP ou planilha.
- Auditoria de movimentações por período.
- Suporte a devoluções (verificação do teto disponível).
Quando lançamentos são criados
Operações em estados não terminais (PENDING, DISPATCHED, PROVIDER_RESULT_UNKNOWN) ainda não geram lançamentos. O ledger só reflete resultados definitivos.
Consultar o ledger
Listar lançamentos
Detalhe de uma entrada
Parâmetros de consulta
Como interpretar uma entrada
Para cruzar entradas do ledger com as transações correspondentes:
- Use
entry_type para identificar o tipo de operação.
TODO: campo de referência ao cash-in/cash-out id na entrada do ledger — confirmar se existe campo transaction_id ou resource_id na resposta.- Compare
amount_cents com value_cents dos webhooks recebidos.
- Caso encontre divergência, use
GET /api/pix/cash-in/{id} ou GET /api/pix/cash-out/{id} para consultar o estado atual.
Saldo disponível
O saldo disponível é a diferença acumulada entre créditos e débitos no ledger. A plataforma é a fonte autoritativa.
TODO: endpoint de saldo consolidado (GET /balance ou similar) — verificar existência com a equipe.
Boas práticas de fechamento
- Exporte o ledger por período fechado (ex.: por dia) usando
start_date e end_date.
- Use paginação por cursor para volumes grandes.
- Não modifique entradas do ledger no seu sistema — elas são imutáveis.
- Reconcilie diariamente com seu sistema financeiro interno para identificar divergências cedo.
Referências
