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

# Reconciliação

> Por que existe reconciliação, quando ela é acionada, como o integrador deve agir e quando escalar.

## O que é reconciliação

**Reconciliação** é o mecanismo da plataforma para resolver o estado de transações cujo resultado não pôde ser confirmado de forma imediata — seja por falha de rede, timeout ou resposta ambígua do BaaS.

Quando o despacho de uma operação retorna uma resposta inconclusiva, a plataforma marca a transação com `PROVIDER_RESULT_UNKNOWN` e inicia um ciclo de consultas ao BaaS. Se o BaaS responder com clareza, a transação é resolvida automaticamente. Se as tentativas se esgotarem, o estado avança para `RECONCILIATION_REQUIRED`.

## Estados que indicam reconciliação ativa

| Status                    | Significado                                          | Ação do integrador                           |
| ------------------------- | ---------------------------------------------------- | -------------------------------------------- |
| `PROVIDER_RESULT_UNKNOWN` | Resposta ambígua do BaaS; reconciliação em andamento | Monitore com `GET`; não conclua a operação.  |
| `RECONCILIATION_REQUIRED` | Tentativas esgotadas sem resultado claro             | Escale para suporte; não conclua a operação. |

<Warning>
  **Nunca** trate `PROVIDER_RESULT_UNKNOWN` ou `RECONCILIATION_REQUIRED` como `PAID`, `CONFIRMED`, `FAILED` ou qualquer outro estado terminal. A operação ainda pode ser resolvida em qualquer direção.
</Warning>

## Como a reconciliação automática funciona

1. Transação entra em `PROVIDER_RESULT_UNKNOWN` após resposta ambígua.
2. Worker de reconciliação consulta o BaaS em intervalos crescentes (backoff).
3. Se o BaaS confirmar: transação vai a `PAID` / `CONFIRMED` e notificação é despachada ao comerciante.
4. Se o BaaS informar falha: transação vai a `FAILED` e reserva é liberada.
5. Se o BaaS não responder após N tentativas: transação vai a `RECONCILIATION_REQUIRED`.

## O que fazer em cada estado

### `PROVIDER_RESULT_UNKNOWN`

* **Polling com `GET`** periodicamente (ex.: a cada 60 segundos por até 15 minutos).
* Aguarde o webhook `pix_cash_out` ou `pix_cash_in` com resultado.
* **Não reenvie** a operação enquanto o estado for ambíguo.

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

### `RECONCILIATION_REQUIRED`

* **Escale para suporte** com o `id` da transação e o `X-Correlation-ID`.
* Mantenha a operação como "em análise" na sua base.
* Não registre como sucesso ou falha até resolução.
* Informe o usuário final que há uma análise em andamento, se necessário.

## Reconciliação pelo integrador

Além da reconciliação automática da plataforma, o integrador deve fazer sua própria reconciliação periódica para garantir consistência entre o sistema interno e a plataforma.

### Reconciliação diária recomendada

1. **Liste as transações do dia** com `GET /api/pix/cash-in?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD`.
2. Compare com os registros internos.
3. Para cada divergência:
   * Transação na plataforma mas não no sistema interno: verificar se webhook foi perdido.
   * Transação no sistema interno com status diferente da plataforma: atualizar pelo dado da plataforma.
4. Repita para cash-out, refund e ledger.

### Reconciliação do ledger

```bash theme={null}
# Exporte o ledger do período
curl "https://api.clearpago.com.br/api/pix/ledger?start_date=2026-04-01&end_date=2026-04-01&limit=100" \
  -H "Authorization: Bearer <seu_api_token>"
```

Compare soma de créditos e débitos com o esperado pelo seu sistema financeiro.

## Divergências comuns e como resolver

| Divergência                                       | Causa                                                | Resolução                                                                           |
| ------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Webhook `PAID` mas GET mostra `PENDING`           | Webhook chegou antes do estado ser persistido (raro) | Aguardar alguns segundos e consultar novamente.                                     |
| GET mostra `PAID` mas webhook não chegou          | Webhook perdido (5xx no seu endpoint)                | Reconciliar via GET; corrigir endpoint; verificar logs.                             |
| Valor no ledger diferente do webhook              | Tarifa calculada diferente                           | Consultar `GET /api/pix/ledger/{id}` para detalhe; `fee_amount_cents` pode diferir. |
| Cash-out `CONFIRMED` mas sem lançamento no ledger | Atraso de worker                                     | Aguardar alguns minutos; consultar ledger novamente.                                |

## Janelas de tempo orientativas

`TODO: confirmar com a equipe de produto` os SLAs exatos de reconciliação automática. Os valores abaixo são **orientativos**:

| Evento                                       | Janela esperada                         |
| -------------------------------------------- | --------------------------------------- |
| Cash-in normal (rede estável)                | Segundos a 1–2 minutos                  |
| Cash-out normal (despacho imediato)          | Segundos a poucos minutos               |
| Reconciliação de `PROVIDER_RESULT_UNKNOWN`   | 5–15 minutos (N tentativas com backoff) |
| `RECONCILIATION_REQUIRED` → resolução manual | Variável; abrir ticket de suporte       |

## Referências

* [Monitoramento operacional](/ledger-and-reconciliation/operational-monitoring)
* [Guia de reconciliação de transações](/guides/reconcile-transactions)
* [Modelo de status](/core-concepts/status-model)
* [Troubleshooting](/errors/troubleshooting)