Pulse (alertas)
Alertas automáticos de queda em faturamento, pedidos e aprovação de pagamento, com regras configuráveis.
O Pulse vigia os números da loja e avisa quando algo anda muito abaixo do normal: por exemplo, o faturamento da última hora caiu pela metade em relação a uma terça-feira típica. Isso costuma indicar um problema (checkout quebrado, gateway de pagamento fora do ar) que o lojista quer saber logo, e não no relatório do dia seguinte. Esta seção cobre as regras (o que vigiar e quão sensível) e os alertas (o que foi detectado).
Como funciona
A cada 15 minutos o Pulse mede a métrica na janela da regra (por exemplo, os últimos 60 minutos) e compara com o valor normal daquele horário. Se a queda chegar ao threshold_pct e houver volume suficiente (min_events), abre um alerta e avisa pelos canais da regra. Enquanto a condição durar dentro do cooldown_minutes (contado desde a primeira detecção), o mesmo alerta é apenas atualizado (last_seen_at) e ninguém é avisado de novo; passado esse prazo, se a queda continua, um novo alerta é aberto e o aviso sai outra vez. Quando a métrica volta ao normal por duas avaliações seguidas, o alerta passa a resolved.
| Estado do alerta | Significado |
|---|---|
open | Detectado e ainda ativo. |
acknowledged | Alguém da equipe marcou como visto (rota ack). |
resolved | A métrica voltou ao normal. |
| Métrica | O que mede |
|---|---|
revenue | Soma do valor dos pedidos na janela (centavos). |
orders_count | Quantidade de pedidos na janela. |
payment_approval | Taxa de pagamentos aprovados entre os concluídos na janela. |
Conceitos importantes
Baseline
O "normal" é a mediana do mesmo horário e dia da semana nas últimas 4 semanas, no fuso de São Paulo. Uma loja nova, sem histórico, não gera alertas até acumular dados.
Volume mínimo
min_events evita alarme falso em horários de pouco movimento: com poucos pedidos, uma oscilação normal parece uma queda enorme.
Canais e horário de silêncio
inbox coloca o aviso no sino do painel. whatsapp envia uma mensagem ao whatsapp_number (e exige o módulo de WhatsApp ativo). O horário de silêncio (quiet_start a quiet_end, que pode atravessar a meia-noite) adia só o WhatsApp; um alerta critical ignora o silêncio.
Severidade
warning para quedas a partir do limite; critical a partir de 80%.
Dinheiro e taxas
Valores em dinheiro vêm em centavos (impact_cents: 78000 = R$ 780,00). Taxas vêm em pontos-base (10000 = 100%).
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/admin/pulse/rules | Lista as regras de alerta | admin |
| POST | /api/v1/admin/pulse/rules | Cria uma regra de alerta | admin |
| PUT | /api/v1/admin/pulse/rules | Altera várias regras de uma vez | admin |
| DELETE | /api/v1/admin/pulse/rules/{id} | Remove uma regra | admin |
| GET | /api/v1/admin/pulse/alerts | Lista os alertas disparados | admin |
| POST | /api/v1/admin/pulse/alerts/{id}/ack | Marca um alerta como visto | admin |
Erros comuns
- Mandar só
{"id": ..., "is_active": true}noPUT: os outros campos são zerados. - Tentar criar regras com o
PUT: itens semidsão ignorados; use oPOST. - Criar uma métrica fora das três: recusado com
unknown metric. - Criar duas regras com a mesma métrica e janela: a segunda é recusada.
- Ler
observed_centsdeorders_countcomo dinheiro: é quantidade de pedidos. - Contar com o
ackpara confirmar a existência do alerta: ele responde 204 sempre.