> ## 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 — Visão geral

> O que é o ledger da ClearPago, quando lançamentos são criados, como consultar e como interpretar créditos e débitos.

## 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ção             | Evento que dispara           | Tipo de lançamento |
| -------------------- | ---------------------------- | ------------------ |
| Cash-in pago         | Cash-in atinge `PAID`        | **Crédito**        |
| Cash-out confirmado  | Cash-out atinge `CONFIRMED`  | **Débito**         |
| Refund-in confirmado | Refund-in atinge `CONFIRMED` | **Débito**         |
| Cash-out revertido   | Cash-out atinge `REVERSED`   | **Crédito**        |

<Warning>
  Operações em estados **não terminais** (`PENDING`, `DISPATCHED`, `PROVIDER_RESULT_UNKNOWN`) ainda **não geram lançamentos**. O ledger só reflete resultados definitivos.
</Warning>

## Consultar o ledger

### Listar lançamentos

```bash theme={null}
# Todos os créditos de abril
curl "https://api.clearpago.com.br/api/pix/ledger?operation=credit&start_date=2026-04-01&end_date=2026-04-30" \
  -H "Authorization: Bearer <seu_api_token>"
```

```bash theme={null}
# Todos os débitos, paginação por cursor
curl "https://api.clearpago.com.br/api/pix/ledger?operation=debit&limit=100&cursor=<cursor>" \
  -H "Authorization: Bearer <seu_api_token>"
```

### Detalhe de uma entrada

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

## Parâmetros de consulta

| Parâmetro    | Tipo         | Descrição                                                                                                     |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------- |
| `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` |
| `start_date` | `YYYY-MM-DD` | Data inicial **inclusiva**                                                                                    |
| `end_date`   | `YYYY-MM-DD` | Data final **inclusiva**                                                                                      |
| `limit`      | integer      | Tamanho da página (máx. 100)                                                                                  |
| `cursor`     | string       | Paginação por cursor (preferida para grandes volumes)                                                         |

## Como interpretar uma entrada

```json theme={null}
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "operation": "credit",
  "entry_type": "pix_cash_in_credit",
  "amount_cents": 15075,
  "created_at": "2026-04-01T12:10:00.000Z"
}
```

| Campo                 | Interpretação                                                 |
| --------------------- | ------------------------------------------------------------- |
| `operation: credit`   | Entrada de valor na conta (recebimento ou reversão de envio). |
| `operation: debit`    | Saída de valor da conta (envio ou devolução de recebimento).  |
| `amount_cents: 15075` | R\$ 150,75 em centavos.                                       |
| `entry_type`          | Tipo específico do lançamento.                                |

## Reconciliação com operações

Para cruzar entradas do ledger com as transações correspondentes:

1. Use `entry_type` para identificar o tipo de operação.
2. `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.
3. Compare `amount_cents` com `value_cents` dos webhooks recebidos.
4. 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

* [GET /api/pix/ledger](/api-reference/list-ledger-entries)
* [GET /api/pix/ledger/{id}](/api-reference/get-ledger-entry)
* [Ledger e saldo (conceito)](/core-concepts/ledger-and-balance)
* [Reconciliação](/ledger-and-reconciliation/reconciliation)