> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ledger e saldo

> O que é o ledger, quando lançamentos são criados, relação com saldo e como consultar e interpretar entradas.

## 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

| Evento                              | Tipo de lançamento                           |
| ----------------------------------- | -------------------------------------------- |
| Cash-in atinge status `PAID`        | **Crédito** (`pix_cash_in_credit`)           |
| Cash-out atinge status `CONFIRMED`  | **Débito** (`pix_cash_out_debit`)            |
| Refund-in atinge status `CONFIRMED` | **Débito** (`pix_cash_in_reversal_debit`)    |
| Cash-out atinge status `REVERSED`   | **Crédito** (`pix_cash_out_reversal_credit`) |

<Note>
  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.
</Note>

## Campos principais de uma entrada

| Campo          | Tipo         | Descrição                                                                                                      |
| -------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
| `id`           | UUID         | Identificador único da entrada no ledger.                                                                      |
| `operation`    | string       | `credit` ou `debit`.                                                                                           |
| `entry_type`   | string       | Ex.: `pix_cash_in_credit`, `pix_cash_out_debit`, `pix_cash_in_reversal_debit`, `pix_cash_out_reversal_credit`. |
| `amount_cents` | integer      | Valor em **centavos**.                                                                                         |
| `created_at`   | ISO 8601 UTC | Data/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:

```bash theme={null}
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:

```bash theme={null}
curl "https://api.clearpago.com.br/api/pix/ledger/{id}" \
  -H "Authorization: Bearer <seu_api_token>"
```

Referência completa: [GET /api/pix/ledger](/api-reference/list-ledger-entries) e [GET /api/pix/ledger/{id}](/api-reference/get-ledger-entry).

## 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

* [Arquitetura](/core-concepts/architecture)
* [Listagem do ledger (API)](/api-reference/list-ledger-entries)
* [Reconciliação](/ledger-and-reconciliation/reconciliation)
* [Visão geral do ledger](/ledger-and-reconciliation/ledger-overview)