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

# Checklist de observabilidade

> Logs, métricas, alertas, correlation ID e reconciliação operacional para manter a integração saudável em produção.

## Correlation ID

<Check>`X-Correlation-ID` gerado e enviado em **todas** as requisições à API.</Check>
<Check>Valor do `X-Correlation-ID` registrado nos logs junto a cada chamada para rastreabilidade cruzada.</Check>
<Check>`event.correlation_id` do webhook (quando presente) correlacionado com o log de criação do recurso.</Check>
<Check>Em incidentes: `X-Correlation-ID` disponível para envio ao suporte da ClearPago.</Check>

## Logs

<Check>Log de criação de cada recurso: `id`, `externalId`, timestamp, status inicial.</Check>
<Check>Log de cada webhook recebido: `event_type`, `event.id`, status, timestamp de chegada.</Check>
<Check>Log do resultado da verificação de assinatura (válida/inválida) — **sem** logar o conteúdo do header completo.</Check>
<Check>Log de cada transição de status processada no seu sistema.</Check>
<Check>Log de cada lançamento no ledger lido (para auditoria de reconciliação).</Check>
<Check>Dados pessoais (documentos, nomes) **não** logados em texto claro.</Check>
<Check>Logs com nível estruturado (JSON) para facilitar buscas e filtros.</Check>
<Check>Retenção de logs definida: mínimo 90 dias, idealmente 1 ano para auditoria Pix.</Check>

## Métricas

<Check>**Taxa de sucesso de cash-in**: % de cobranças que chegam a `PAID` vs. criadas.</Check>
<Check>**Tempo médio de liquidação de cash-in**: da criação ao webhook `pix_cash_in` com `PAID`.</Check>
<Check>**Taxa de sucesso de cash-out**: % de envios que chegam a `CONFIRMED`.</Check>
<Check>**Tempo médio de confirmação de cash-out**: da criação ao webhook `pix_cash_out` com `CONFIRMED`.</Check>
<Check>**Webhooks recebidos vs. eventos esperados**: detecta entregas perdidas.</Check>
<Check>**Taxa de verificação de assinatura com falha**: detecta rotação de chave ou tentativas de replay.</Check>
<Check>**Transações em `PROVIDER_RESULT_UNKNOWN`** (contagem ao longo do tempo).</Check>
<Check>**Transações em `RECONCILIATION_REQUIRED`** (alerta crítico se > 0).</Check>

## Alertas

<Check>Alerta crítico: qualquer transação em `RECONCILIATION_REQUIRED`.</Check>
<Check>Alerta de atenção: transação em `PROVIDER_RESULT_UNKNOWN` por mais de 15 minutos.</Check>
<Check>Alerta de atenção: cash-in em `PENDING` após a data de expiração do QR.</Check>
<Check>Alerta de atenção: taxa de erro 5xx no endpoint de webhook acima de 1%.</Check>
<Check>Alerta de atenção: certificado TLS do endpoint de webhook com menos de 30 dias para expirar.</Check>
<Check>Alerta de informação: cash-out `REVERSED` recebido (ação financeira necessária).</Check>

## Reconciliação operacional

<Check>Processo de reconciliação diária definido: lista de transações vs. registros internos.</Check>
<Check>Automação de detecção de divergências (status diferente entre plataforma e seu sistema).</Check>
<Check>Checagem de ledger diária: soma de créditos e débitos coerente com saldo esperado.</Check>
<Check>Alertas para divergências de saldo acima de um threshold definido.</Check>

## Rastreabilidade de incidentes

<Check>Runbook documentado com os passos para investigar: cash-in não confirmado, webhook perdido, cash-out preso.</Check>
<Check>Dashboard operacional com visão em tempo real de transações por estado.</Check>
<Check>Canal de escalonamento para suporte ClearPago documentado e testado.</Check>

## Referências

* [Monitoramento operacional](/ledger-and-reconciliation/operational-monitoring)
* [Reconciliação](/ledger-and-reconciliation/reconciliation)
* [Checklist de produção](/go-live/production-checklist)
* [Checklist de segurança](/go-live/security-checklist)