VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pulse (alertas)

Regras do Pulse

Lista, cria, edita e apaga as regras que definem o que o Pulse vigia e com que sensibilidade.

Listar regras do Pulse

Devolve as regras que o Pulse usa para vigiar a loja. Na primeira consulta de uma loja, a plataforma cria três regras padrão, desligadas: queda de faturamento (revenue), de pedidos (orders_count) e de aprovação de pagamento (payment_approval).

GET/api/v1/admin/pulse/rulesAdmin

Lista as regras de alerta

Exige o privilégio view_reports.

Exemplo de requisição (Listar regras)

bash
curl "$BASE_URL/api/v1/admin/pulse/rules" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar regras)

200Regras
json
[
  {
    "id": "55c6c3c9-530c-48d2-ba2e-d30050ece7ab",
    "metric": "orders_count",
    "window_minutes": 60,
    "threshold_pct": 50,
    "min_events": 5,
    "cooldown_minutes": 120,
    "channels": [
      "inbox",
      "whatsapp"
    ],
    "whatsapp_number": "+5511987654321",
    "quiet_start": 23,
    "quiet_end": 7,
    "is_active": true
  }
]

Campos da resposta

iduuid
Identificador da regra.
metricstring
revenueorders_countpayment_approval
O que a regra vigia.
window_minutesinteger
Janela deslizante, em minutos, em que o valor atual é medido. Padrão 60.
threshold_pctinteger
Queda mínima, em %, em relação ao normal para disparar o alerta.
min_eventsinteger
Trava de volume mínimo que evita alerta em horário de pouco movimento. Em payment_approval é o número de pagamentos concluídos na janela.
cooldown_minutesinteger
Intervalo mínimo entre alertas da mesma regra.
channelsarray
Onde avisar: inbox (sino do painel) e/ou whatsapp.
whatsapp_numberstring
Número que recebe o aviso por WhatsApp. Vazio se não usa.
quiet_startinteger
Hora (0 a 23) em que o silêncio começa, no fuso da loja.
quiet_endinteger
Hora (0 a 23) em que o silêncio termina.
is_activeboolean
Regra ligada. As regras padrão nascem desligadas.

Erros (Listar regras)

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

Diferente de outras rotas do painel, aqui o corpo da resposta é a própria lista de regras, sem objeto em volta. Os campos abaixo descrevem cada item.

Criar regra do Pulse

Cria uma regra, por exemplo uma segunda regra de faturamento com janela de 30 minutos. Só existe uma regra por par metric e window_minutes.

POST/api/v1/admin/pulse/rulesAdmin

Cria uma regra de alerta

Exige o privilégio manage_settings.

Corpo da requisição

metricstringobrigatório
revenueorders_countpayment_approval
Métrica vigiada.
window_minutesintegerpadrão: 60
Janela em minutos.
threshold_pctinteger
Queda mínima em %.
min_eventsinteger
Volume mínimo de eventos.
cooldown_minutesinteger
Intervalo mínimo entre alertas.
channelsarraypadrão: ['inbox']
inboxwhatsapp
Canais de aviso.
whatsapp_numberstring
Número de WhatsApp, com DDI (+5511987654321).
quiet_startinteger
Início do silêncio (hora 0 a 23).
quiet_endinteger
Fim do silêncio (hora 0 a 23).
is_activeboolean
Liga a regra.

Exemplo de requisição (Criar regra)

bash
curl -X POST "$BASE_URL/api/v1/admin/pulse/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "metric": "revenue",
  "window_minutes": 30,
  "threshold_pct": 40,
  "min_events": 3,
  "cooldown_minutes": 60,
  "channels": [
    "inbox"
  ],
  "quiet_start": 22,
  "quiet_end": 6,
  "is_active": false
}'

Resposta (Criar regra)

201Regra criada
json
{
  "id": "55c6c3c9-530c-48d2-ba2e-d30050ece7ab",
  "metric": "revenue",
  "window_minutes": 30,
  "threshold_pct": 40,
  "min_events": 3,
  "cooldown_minutes": 60,
  "channels": [
    "inbox"
  ],
  "whatsapp_number": "",
  "quiet_start": 22,
  "quiet_end": 6,
  "is_active": false
}

Campos da resposta

iduuid
Identificador da regra.
metricstring
revenueorders_countpayment_approval
O que a regra vigia.
window_minutesinteger
Janela deslizante, em minutos, em que o valor atual é medido. Padrão 60.
threshold_pctinteger
Queda mínima, em %, em relação ao normal para disparar o alerta.
min_eventsinteger
Trava de volume mínimo que evita alerta em horário de pouco movimento. Em payment_approval é o número de pagamentos concluídos na janela.
cooldown_minutesinteger
Intervalo mínimo entre alertas da mesma regra.
channelsarray
Onde avisar: inbox (sino do painel) e/ou whatsapp.
whatsapp_numberstring
Número que recebe o aviso por WhatsApp. Vazio se não usa.
quiet_startinteger
Hora (0 a 23) em que o silêncio começa, no fuso da loja.
quiet_endinteger
Hora (0 a 23) em que o silêncio termina.
is_activeboolean
Regra ligada. As regras padrão nascem desligadas.

Erros (Criar regra)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_settings"}
400Corpo inválido, métrica desconhecida, ou já existe regra para esse par métrica/janela.{"error":"failed to create pulse rule","detail":"unknown metric: \"foo\""}
Crie desligada

Crie com is_active false, ajuste os limites e só então ligue com PUT. Uma regra nova com limite baixo demais gera alertas em excesso.

Editar regras do Pulse

Recebe uma lista de regras e atualiza cada uma pelo id. Itens sem id são ignorados em silêncio: esta rota nunca cria. A métrica de uma regra não muda; o resto (limites, canais, silêncio, ligar/desligar, janela) sim.

PUT/api/v1/admin/pulse/rulesAdmin

Altera várias regras de uma vez

Exige o privilégio manage_settings.

Corpo da requisição

[]arrayobrigatório
O corpo inteiro é uma lista. Cada item aceita id (obrigatório), threshold_pct, min_events, cooldown_minutes, channels, whatsapp_number, quiet_start, quiet_end, is_active e window_minutes.

Exemplo de requisição (Editar regras)

bash
curl -X PUT "$BASE_URL/api/v1/admin/pulse/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "id": "55c6c3c9-530c-48d2-ba2e-d30050ece7ab",
    "threshold_pct": 45,
    "min_events": 5,
    "cooldown_minutes": 120,
    "channels": [
      "inbox"
    ],
    "quiet_start": 23,
    "quiet_end": 7,
    "is_active": true,
    "window_minutes": 60
  }
]'

Resposta (Editar regras)

200Regras salvas
json
{
  "ok": true
}

Campos da resposta

okboolean
Sempre true em caso de sucesso.

Erros (Editar regras)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_settings"}
400O corpo não é uma lista JSON válida.{"error":"invalid body","detail":"..."}
500Falha ao gravar (por exemplo, janela repetida em outra regra).{"error":"failed to save pulse rules","detail":"..."}
Substitui todos os campos

Cada item atualiza todos os campos editáveis da regra, não só os enviados: o que faltar vira zero, falso ou vazio (por exemplo is_active desliga a regra e threshold_pct vira 0). Leia a regra, mude o que precisa e envie o objeto completo.

Sem retorno das regras

A resposta só confirma. Para ver o resultado, liste as regras de novo.

Apagar regra do Pulse

Apaga a regra. Responde 204 mesmo se o id não existir. Para só parar de vigiar, desligue a regra com PUT (is_active false).

DELETE/api/v1/admin/pulse/rules/{id}Admin

Remove uma regra

Exige o privilégio manage_settings.

Parâmetros de caminho

iduuidobrigatório
Identificador da regra.

Exemplo de requisição (Apagar regra)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/pulse/rules/55c6c3c9-530c-48d2-ba2e-d30050ece7ab" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar regra)

204Regra apagada

Corpo vazio.

Erros (Apagar regra)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_settings"}
500id que não é UUID, ou falha de banco.{"error":"failed to delete pulse rule","detail":"..."}

Veja também

  • Alertas
Anterior
Pulse (alertas)
Próxima
Alertas do Pulse
Nesta página
  • Listar regras do Pulse
  • Exemplo de requisição (Listar regras)
  • Resposta (Listar regras)
  • Erros (Listar regras)
  • Criar regra do Pulse
  • Exemplo de requisição (Criar regra)
  • Resposta (Criar regra)
  • Erros (Criar regra)
  • Editar regras do Pulse
  • Exemplo de requisição (Editar regras)
  • Resposta (Editar regras)
  • Erros (Editar regras)
  • Apagar regra do Pulse
  • Exemplo de requisição (Apagar regra)
  • Resposta (Apagar regra)
  • Erros (Apagar regra)
  • Veja também