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

# Reconciliar transações

> Quando usar reconciliação, como tratar estados ambíguos, divergências entre webhook e GET, e práticas operacionais.

## O que é reconciliação

**Reconciliação** é o processo de resolver estados inconclusivos de transações consultando o BaaS diretamente. Ela ocorre de forma **automática** pela plataforma em estados como `PROVIDER_RESULT_UNKNOWN` e `RECONCILIATION_REQUIRED`, mas também é relevante para o integrador no monitoramento operacional.

## Quando a reconciliação é necessária

| Situação                          | Causa                                                                   |
| --------------------------------- | ----------------------------------------------------------------------- |
| `PROVIDER_RESULT_UNKNOWN`         | Resposta ambígua do BaaS (timeout, 5xx, EOF) na chamada de despacho.    |
| `RECONCILIATION_REQUIRED`         | Tentativas automáticas esgotadas sem resultado claro.                   |
| Webhook não recebido              | Entrega falhou; o estado real pode ser diferente do que você persistiu. |
| Divergência entre webhook e `GET` | Reentrega antiga ou processamento fora de ordem.                        |

## O que fazer em cada situação

### 1. Status `PROVIDER_RESULT_UNKNOWN`

A plataforma está consultando o BaaS periodicamente. **Não aja antes do resultado.**

```bash theme={null}
# Consulte periodicamente (ex.: a cada 30 segundos por até 5 minutos)
curl https://api.clearpago.com.br/api/pix/cash-out/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <seu_api_token>"
```

* Se transicionar para `CONFIRMED`: processe como sucesso.
* Se transicionar para `FAILED`: processe como falha; reserva foi liberada.
* Se permanecer por mais de 10–15 minutos: acione suporte.

### 2. Status `RECONCILIATION_REQUIRED`

As tentativas automáticas foram esgotadas. **Ação humana ou escalonamento é necessário.**

* Acione o canal de suporte com o `id` da transação e o `X-Correlation-ID`.
* Não conclua a operação (pago/falhou) no seu sistema até resolução.
* Guarde o estado como "em análise" internamente.

### 3. Webhook não recebido no tempo esperado

Após o tempo máximo esperado (ex.: 5–10 minutos para cash-in), consulte diretamente:

```bash theme={null}
curl https://api.clearpago.com.br/api/pix/cash-in/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <seu_api_token>"
```

* Se `PAID`: o pagamento foi confirmado mesmo sem webhook; processe localmente.
* Se `PENDING`: ainda aguardando; defina um novo timeout e monitore.
* Se `EXPIRED` ou `FAILED`: encerre o fluxo conforme a regra de negócio.

### 4. Divergência entre webhook e GET

Pode ocorrer quando um webhook atrasado chega com um status "anterior" ao que já está na base.

**Regra:** o estado obtido via `GET /.../{id}` é **autoritativo**. Atualize conforme o `GET` e descarte transições para estados "anteriores".

```
webhook: PENDING → ignorar se GET já mostra PAID
webhook: PAID → processar se GET confirma PAID
```

## Fluxo de monitoramento operacional

Para manter a saúde da integração:

```mermaid theme={null}
flowchart TD
  A[Transação criada] --> B{Webhook recebido?}
  B -- Sim --> C[Verificar assinatura]
  C --> D[Processar evento]
  B -- Não --> E{Timeout?}
  E -- Não --> F[Aguardar]
  F --> B
  E -- Sim --> G[GET /pix/{resource}/{id}]
  G --> H{Status?}
  H -- Terminal --> D
  H -- PROVIDER_RESULT_UNKNOWN --> I[Monitorar + retry GET]
  H -- RECONCILIATION_REQUIRED --> J[Escalar para suporte]
  I --> K{Resolvido?}
  K -- Sim --> D
  K -- Não / timeout --> J
```

## Boas práticas

* **Defina timeouts por tipo de operação.** Cash-in costuma ser mais rápido que cash-out; calibre os tempos de espera.
* **Use `X-Correlation-ID`.** Em escalonamento de suporte, o correlation ID facilita a busca nos logs da plataforma.
* **Monitore a lista de transações** `GET /api/pix/cash-in?status=PENDING&start_date=...` para identificar transações antigas sem resolução.
* **Não reenvie cash-out automaticamente** sem confirmar que o anterior foi `FAILED` — risco de duplicidade financeira.
* **Registre todos os estados** intermediários na sua base para auditoria.

## Listar transações por estado

### Cash-ins pendentes há mais de 1 hora

```bash theme={null}
curl "https://api.clearpago.com.br/api/pix/cash-in?status=PENDING&start_date=2026-04-01&end_date=2026-04-23" \
  -H "Authorization: Bearer <seu_api_token>"
```

### Cash-outs em estado ambíguo

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

## Referências

* [Modelo de status](/core-concepts/status-model)
* [Monitoramento operacional](/ledger-and-reconciliation/operational-monitoring)
* [Códigos de erro e troubleshooting](/errors/troubleshooting)
* [FAQ](/faq/index)