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

# Monitoramento operacional

> O que monitorar, como detectar operações presas, divergências entre webhook e consulta, e práticas de suporte a incidentes.

## Por que monitorar

O modelo assíncrono da ClearPago funciona bem em condições normais, mas estados intermediários prolongados, webhooks perdidos e falhas de rede exigem visibilidade ativa. Sem monitoramento, operações presas podem impactar usuários, saldo disponível e relatórios financeiros.

## O que monitorar

### Indicadores de saúde (mínimos)

| Métrica                                        | Sinal de alerta                                 |
| ---------------------------------------------- | ----------------------------------------------- |
| Cash-ins em `PENDING` há mais de X minutos     | Possível problema de pagamento ou rede          |
| Cash-outs em `DISPATCHED` há mais de Y minutos | BaaS pode estar lento; verificar reconciliação  |
| Transações em `PROVIDER_RESULT_UNKNOWN`        | Reconciliação ativa; monitorar resolução        |
| Transações em `RECONCILIATION_REQUIRED`        | Requer ação imediata de suporte                 |
| Webhooks sem resposta no tempo esperado        | Possível problema no seu endpoint ou na entrega |
| Taxa de verificação de assinatura com falha    | Possível rotação de chave ou ataque             |

`TODO: calibrar os valores de X e Y (janelas de alerta) com base na experiência de produção e nos SLAs da plataforma.`

### Indicadores de ledger

| Métrica                                     | Sinal de alerta                                               |
| ------------------------------------------- | ------------------------------------------------------------- |
| Saldo negativo inesperado                   | Débito sem crédito correspondente; verificar ordem de eventos |
| Ausência de lançamento após `PAID`          | Delay de worker; monitorar por alguns minutos                 |
| Divergência entre soma de webhooks e ledger | Possível evento duplicado ou perdido                          |

## Queries de monitoramento (exemplos)

### Cash-ins antigos em PENDING

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

Use `start_date` e `end_date` para restringir o período e identificar os mais antigos.

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

### Refunds pendentes

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

## Divergências entre webhook e GET

Quando o estado do seu sistema difere do retornado pela API:

| Cenário                                                 | Causa provável                       | Ação                                                           |
| ------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------- |
| GET retorna `PAID` mas sistema está `PENDING`           | Webhook perdido ou não processado    | Atualizar pelo GET; investigar logs do endpoint.               |
| Webhook `PAID` mas GET retorna `PENDING`                | Webhook chegou antes da persistência | Aguardar 10–30s e consultar novamente.                         |
| Webhook e GET discordantes em status terminais          | Dois eventos de estados diferentes   | Usar o GET como autoritativo; verificar chave de idempotência. |
| GET retorna `CONFIRMED` mas ledger não tem o lançamento | Delay de worker do ledger            | Aguardar alguns minutos; consultar ledger novamente.           |

**Regra geral:** `GET /.../{id}` é sempre mais atual que o último evento de webhook recebido. Em caso de conflito, confie na consulta direta.

## Práticas de suporte a incidentes

### O que coletar antes de abrir um ticket

1. **`id` da transação** (UUID retornado no `201`).
2. **`externalId`** que você enviou.
3. **`X-Correlation-ID`** das chamadas relevantes.
4. **Timestamp** aproximado da criação e do momento em que o problema foi detectado.
5. **Status atual** retornado pelo `GET`.
6. **Payloads** de webhooks recebidos (se houver).
7. **Logs** do seu endpoint de webhook para o período.

### Escalation path

`TODO: confirmar o canal de suporte e SLA de resposta para incidentes de produção.` Veja [Checklist de produção](/go-live/production-checklist).

## Alertas recomendados

Configure alertas no seu sistema de observabilidade para:

* **Cash-in em `PENDING`** há mais de 10 minutos após a expiração esperada do QR.
* **Cash-out em `DISPATCHED`** há mais de 15 minutos.
* **Qualquer transação em `RECONCILIATION_REQUIRED`**.
* **Taxa de erro 5xx** no seu endpoint de webhook acima de N%.
* **Webhook sem chegada** para um cash-in `PAID` há mais de 5 minutos (se você tiver polling).
* **Divergência de saldo** entre seu sistema e o ledger da ClearPago.

## Referências

* [Guia de reconciliação](/guides/reconcile-transactions)
* [Reconciliação (conceito)](/ledger-and-reconciliation/reconciliation)
* [Modelo de status](/core-concepts/status-model)
* [Troubleshooting](/errors/troubleshooting)
* [Observabilidade (go-live)](/go-live/observability-checklist)