Skip to main content

​
O que é o ledger

O ledger é o livro-razão da plataforma ClearPago. Cada operação Pix confirmada gera um lançamento (entrada) com tipo, valor em centavos e referência ao recurso de origem. O ledger é a fonte autoritativa para:
  • Calcular o saldo disponível da conta.
  • Reconciliar créditos (recebimentos confirmados, reversões de cash-out) e débitos (envios confirmados, devoluções de recebimento).
  • Auditar operações por período.

​
Quando um lançamento é criado

Lançamentos só são criados em estados terminais confirmados. Operações em PENDING, DISPATCHED, PROVIDER_RESULT_UNKNOWN ou RECONCILIATION_REQUIRED ainda não impactam o ledger.

​
Campos principais de uma entrada

TODO: confirmar campos adicionais (referência ao cash-in/cash-out id, saldo resultante, etc.) com a spec OpenAPI interna.

​
Como consultar

Use GET /api/pix/ledger para listar entradas com paginação por cursor e filtros:
Para um lançamento específico:
Referência completa: GET /api/pix/ledger e GET /api/pix/ledger/.

​
Relação com saldo

O saldo disponível é a soma acumulada de créditos menos débitos no ledger. A plataforma é a fonte autoritativa; não calcule saldo localmente com base em webhooks, pois reentregas e reconciliações podem alterar a sequência percebida de eventos. TODO: endpoint de saldo (GET /balance ou similar) — verificar se existe rota dedicada para consulta de saldo consolidado.

​
Paginação por cursor (recomendado)

O endpoint de listagem suporta paginação por cursor (preferível para grandes volumes) além de page/limit. Use o cursor retornado na resposta para a próxima página e preserve o intervalo de datas para consistência em exports.

​
Boas práticas de reconciliação com o ledger

  • Consulte por data inclusiva (start_date/end_date em YYYY-MM-DD) para intervalos de fechamento.
  • Filtre por entry_type para separar recebimentos, envios, devoluções e reversões.
  • Não use o ledger para checar estado ativo de transações — use GET /api/pix/cash-in/{id} ou GET /api/pix/cash-out/{id} para status ao vivo.
  • Correlacione com id do recurso para cruzar entradas de ledger com registros de cash-in/cash-out na sua base.

​
Referências