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

EventoTipo de lançamento
Cash-in atinge status PAIDCrédito (pix_cash_in_credit)
Cash-out atinge status CONFIRMEDDébito (pix_cash_out_debit)
Refund-in atinge status CONFIRMEDDébito (pix_cash_in_reversal_debit)
Cash-out atinge status REVERSEDCrédito (pix_cash_out_reversal_credit)
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

CampoTipoDescrição
idUUIDIdentificador único da entrada no ledger.
operationstringcredit ou debit.
entry_typestringEx.: pix_cash_in_credit, pix_cash_out_debit, pix_cash_in_reversal_debit, pix_cash_out_reversal_credit.
amount_centsintegerValor em centavos.
created_atISO 8601 UTCData/hora do lançamento.
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: 
curl "https://api.clearpago.com.br/api/pix/ledger?operation=credit&limit=50" \
  -H "Authorization: Bearer <seu_api_token>"
Para um lançamento específico: 
curl "https://api.clearpago.com.br/api/pix/ledger/{id}" \
  -H "Authorization: Bearer <seu_api_token>"
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. 
GET /api/pix/ledger?cursor=<token_da_pagina_anterior>&limit=100&operation=debit

​
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