Skip to main content

​
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)

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

​
Queries de monitoramento (exemplos)

​
Cash-ins antigos em PENDING

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

​
Cash-outs em estado ambíguo

​
Refunds pendentes

​
Divergências entre webhook e GET

Quando o estado do seu sistema difere do retornado pela API: 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.

​
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