API atual/Referência completa/Pulse (alertas)

Alertas do Pulse

Lista os alertas detectados e marca um alerta como reconhecido.

Listar alertas do Pulse

Devolve os alertas, do mais recente para o mais antigo, no máximo 200. O Pulse avalia as regras ligadas a cada 15 minutos; quando uma métrica cai além do limite, abre (ou atualiza) um alerta. Quando a métrica volta ao normal por duas janelas seguidas, o alerta se resolve sozinho.

GET/api/v1/admin/pulse/alertsAdmin

Lista os alertas disparados

Exige o privilégio view_reports.

Parâmetros de consulta

statusstring

openacknowledgedresolved

Filtra pelo estado. Sem filtro, todos.

Exemplo de requisição (Listar alertas)

bash

curl "$BASE_URL/api/v1/admin/pulse/alerts?status=open" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar alertas)

200Alertas

json

[
  {
    "id": "c1d9a0f2-6a4b-4f6e-9a2d-1f3b7e0b5c44",
    "rule_id": "55c6c3c9-530c-48d2-ba2e-d30050ece7ab",
    "metric": "revenue",
    "status": "open",
    "observed_cents": 18000,
    "expected_cents": 96000,
    "observed_ratio_bps": 0,
    "expected_ratio_bps": 0,
    "impact_cents": 78000,
    "severity": "critical",
    "delivered_channels": [
      "inbox"
    ],
    "first_seen_at": "2026-10-11T15:00:00Z",
    "last_seen_at": "2026-10-11T15:30:00Z"
  }
]

Campos da resposta

iduuid

Identificador do alerta.

rule_iduuid

Regra que disparou.

metricstring

Métrica.

statusstring

open, acknowledged ou resolved.

observed_centsinteger

Valor observado na janela. Para revenue é dinheiro em centavos; para orders_count é a quantidade de pedidos (apesar do nome do campo). Zero em payment_approval.

expected_centsinteger

Valor normal esperado (mediana da mesma hora e dia da semana nas últimas 4 semanas), na mesma unidade de observed_cents.

observed_ratio_bpsinteger

Só em payment_approval: taxa de aprovação observada em pontos-base (10000 = 100%).

expected_ratio_bpsinteger

Só em payment_approval: taxa esperada em pontos-base.

impact_centsinteger

Só em revenue: quanto deixou de entrar (esperado menos observado), em centavos.

severitystring

warning, ou critical quando a queda é de 80% ou mais.

delivered_channelsarray

Canais por onde o aviso realmente saiu.

first_seen_atstring

Primeira detecção, RFC 3339.

last_seen_atstring

Última vez em que a condição foi vista, RFC 3339.

Erros (Listar alertas)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
500	Falha de banco.	`{"error":"failed to list pulse alerts","detail":"..."}`

Reconhecer alerta do Pulse

Muda um alerta de open para acknowledged, para avisar a equipe de que alguém está cuidando. O alerta continua ativo e ainda se resolve sozinho quando a métrica normalizar. Não precisa de corpo.

POST/api/v1/admin/pulse/alerts/{id}/ackAdmin

Marca um alerta como visto

Exige o privilégio view_reports.

Parâmetros de caminho

iduuidobrigatório

Identificador do alerta.

Exemplo de requisição (Reconhecer alerta)

bash

curl -X POST "$BASE_URL/api/v1/admin/pulse/alerts/c1d9a0f2-6a4b-4f6e-9a2d-1f3b7e0b5c44/ack" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Reconhecer alerta)

204Alerta reconhecido

Corpo vazio.

Erros (Reconhecer alerta)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
500	`id` que não é UUID, ou falha de banco.	`{"error":"failed to ack alert","detail":"..."}`

Veja também

Regras do Pulse

Alertas do Pulse

Lista os alertas detectados e marca um alerta como reconhecido.

Listar alertas do Pulse

GET/api/v1/admin/pulse/alertsAdmin

Lista os alertas disparados

Exige o privilégio view_reports.

Parâmetros de consulta

statusstring

openacknowledgedresolved

Filtra pelo estado. Sem filtro, todos.

Exemplo de requisição (Listar alertas)

bash

curl "$BASE_URL/api/v1/admin/pulse/alerts?status=open" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar alertas)

200Alertas

json

[
  {
    "id": "c1d9a0f2-6a4b-4f6e-9a2d-1f3b7e0b5c44",
    "rule_id": "55c6c3c9-530c-48d2-ba2e-d30050ece7ab",
    "metric": "revenue",
    "status": "open",
    "observed_cents": 18000,
    "expected_cents": 96000,
    "observed_ratio_bps": 0,
    "expected_ratio_bps": 0,
    "impact_cents": 78000,
    "severity": "critical",
    "delivered_channels": [
      "inbox"
    ],
    "first_seen_at": "2026-10-11T15:00:00Z",
    "last_seen_at": "2026-10-11T15:30:00Z"
  }
]

Campos da resposta

iduuid

Identificador do alerta.

rule_iduuid

Regra que disparou.

metricstring

Métrica.

statusstring

open, acknowledged ou resolved.

observed_centsinteger

Valor observado na janela. Para revenue é dinheiro em centavos; para orders_count é a quantidade de pedidos (apesar do nome do campo). Zero em payment_approval.

expected_centsinteger

Valor normal esperado (mediana da mesma hora e dia da semana nas últimas 4 semanas), na mesma unidade de observed_cents.

observed_ratio_bpsinteger

Só em payment_approval: taxa de aprovação observada em pontos-base (10000 = 100%).

expected_ratio_bpsinteger

Só em payment_approval: taxa esperada em pontos-base.

impact_centsinteger

Só em revenue: quanto deixou de entrar (esperado menos observado), em centavos.

severitystring

warning, ou critical quando a queda é de 80% ou mais.

delivered_channelsarray

Canais por onde o aviso realmente saiu.

first_seen_atstring

Primeira detecção, RFC 3339.

last_seen_atstring

Última vez em que a condição foi vista, RFC 3339.

Erros (Listar alertas)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
500	Falha de banco.	`{"error":"failed to list pulse alerts","detail":"..."}`

Reconhecer alerta do Pulse

POST/api/v1/admin/pulse/alerts/{id}/ackAdmin

Marca um alerta como visto

Exige o privilégio view_reports.

Parâmetros de caminho

iduuidobrigatório

Identificador do alerta.

Exemplo de requisição (Reconhecer alerta)

bash

curl -X POST "$BASE_URL/api/v1/admin/pulse/alerts/c1d9a0f2-6a4b-4f6e-9a2d-1f3b7e0b5c44/ack" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Reconhecer alerta)

204Alerta reconhecido

Corpo vazio.

Erros (Reconhecer alerta)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
500	`id` que não é UUID, ou falha de banco.	`{"error":"failed to ack alert","detail":"..."}`

Veja também

Regras do Pulse