Alertas — `/alerts`

Alertas agrupados por Aplicação, com tipo, destinatários e canais

Uma integração que para em silêncio é pior que uma que falha alto. Os alertas existem para que o silêncio deixe de ser possível: cada evento relevante do CMS pode virar notificação, e-mail ou webhook, com destinatários escolhidos por você.

Como um alerta é configurado

Um alerta é a combinação de quatro coisas:

Tipo de evento — o que precisa acontecer.
Escopo — Aplicação, e conforme o tipo também Interface e Definição.
Destinatários — quais usuários do CMS recebem.
Canais — notificação in-app (sempre), e-mail, webhook e/ou chamado numa ferramenta de Help Desk.

A combinação tipo + aplicação + interface + definição é única: não existem duas configurações disputando o mesmo evento. Tentar criar a segunda é recusado com mensagem clara. A exceção é Condição Atendida: cada configuração tem a sua condição, e a mesma Coleta pode ter várias.

Ao criar uma Aplicação, Interface, Definição ou Erro de Negócio, o CMS pré-cadastra as configurações de alerta aplicáveis — desativadas e sem destinatários. Elas aparecem na lista esperando que alguém diga quem deve ser avisado, em vez de precisarem ser criadas do zero.

Tipos de evento

Nível Aplicação

Não pedem Interface: valem para a aplicação inteira.

Evento	Dispara quando
Aplicação Offline	O keep-alive da aplicação falha
Aplicação Online	A aplicação volta a responder

O corpo do alerta de aplicação offline inclui, em linhas separadas, as observações cadastradas na Aplicação e o erro capturado pelo keep-alive. Isso transforma um “está offline” em algo acionável: quem recebe a mensagem já lê o telefone do responsável e o erro de rede.

Nível Interface

Evento	Dispara quando
Interface Bloqueada	A interface é bloqueada, manualmente ou por erro de negócio
Interface Desbloqueada	A interface é liberada
Mensagens Acumuladas em Interface	A fila passa do limite configurado na Interface
Erro de Coleta	Uma coleta falha ao ler a origem
Interface com Agendador Pausado	O agendador da interface está inativo
Conexão Perdida	Cai a conexão persistente da Coleta — MQTT, SAP IDoc, OPC UA ou Modbus
Diretório Inacessível	A pasta de uma coleta de arquivos deixou de responder
Dispositivo Sparkplug Offline	Um edge node ou device anunciou `NDEATH` / `DDEATH`

Conexão Perdida e Dispositivo Sparkplug Offline são coisas diferentes. O primeiro é a queda do broker; o segundo é a queda do equipamento com o broker de pé. Confundir os dois manda a equipe errada para o lugar errado.

Nível Definição

Estes pedem também a Definição, porque o interessante é saber qual integração falhou:

Evento	Dispara quando
Erro de Entrega	Falha técnica ao entregar (rede, timeout, HTTP de erro)
Erro de Negócio	O destino respondeu, mas a resposta casou uma regra de Erro de Negócio
Condição Atendida	O dado coletado passou a atender a condição configurada — só em Coletas. A volta dispara Condição Normalizada
Falha no iFlow (SAP CPI)	O SAP CPI aceitou a Entrega, mas o iFlow terminou em falha depois, dentro do tenant — só em Entregas para Aplicação SAP CPI. Ver Status no SAP CPI

Condição Atendida é o alerta sobre o conteúdo da leitura: temperatura acima de 80 por 5 minutos, status diferente de OK. Ele tem campos próprios — a condição, Separar por, a duração mínima e a mensagem — e as regras de disparo estão em Condições sobre o dado.

Erro de Entrega não se aplica a Interfaces de Coleta. Numa Coleta, a falha de leitura é Erro de Coleta; o que existe de “erro de definição” ali é o Erro de Negócio. A tela recusa a combinação inválida em vez de criar um alerta que nunca dispararia.

Mensagens acumuladas

O limite não fica no alerta, e sim na Interface (campo de alerta de mensagens acumuladas). Um agendador de sistema — Check-msg-acumulada-alert — varre as interfaces a cada minuto e dispara o alerta de quem passou do teto. É por isso que esse alerta chega com até um minuto de atraso, por construção.

Destinatários

Só aparecem na lista os usuários com “Aceita receber alertas?” marcado no cadastro, e que tenham acesso à Aplicação/Interface do alerta. Se a lista vier vazia, é isso que está faltando — a tela diz explicitamente.

Um alerta pode ser configurado para vários usuários; cada um recebe sua própria cópia, e a leitura é individual.

Canais

Canal	Como funciona	Requisito
Notificação in-app	Sino no cabeçalho, com contagem de não lidos	Nenhum
E-mail	Uma mensagem por destinatário	SMTP em Configurações → E-mail
Webhook	Um POST com o alerta em JSON	Webhook habilitado em Configurações
Chamado	Abre um chamado em cada destino escolhido em Abrir chamado em	Uma ferramenta ativada e um destino — ver Help Desk

A notificação in-app é sempre gravada — mesmo com e-mail e webhook desligados, o alerta fica no histórico e no sino. Cada usuário vê os seus últimos não lidos, pode dispensar um a um ou marcar todos como lidos.

O webhook, e o que ele resolve

O canal marcado como WhatsApp na tela envia, na verdade, um POST para a URL configurada em Configurações — tipicamente uma automação (n8n, Power Automate, Zapier) que decide o que fazer com aquilo. O corpo é padronizado:


{
  "tipo": "APLICACAO_OFFLINE",
  "mensagem": "🔴 Aplicação MES - Manufacturing Execution System está offline!\n...",
  "disparadoEm": "2026-08-26T13:40:02.145Z",
  "aplicacao": { "id": 1, "sigla": "MES", "descricao": "..." },
  "fila": null,
  "definicaoMensagem": null,
  "definicaoColeta": null,
  "contexto": { "erro": "connect ETIMEDOUT 10.0.3.7:8080" },
  "destinatarios": [
    { "id": 4, "nome": "...", "login": "...", "email": "...", "telefone": "..." }
  ]
}

Repare que os telefones dos destinatários vão no payload: é o que permite à automação disparar WhatsApp, SMS ou ligação sem consultar o CMS. O endpoint aceita Basic Auth opcional.

Como o payload carrega dados de contato, aponte o webhook apenas para um endpoint sob seu controle. Ele sai do CMS com tudo que a automação precisa para falar com as pessoas.

Chamado

O campo Abrir chamado em escolhe em quais destinos de chamado o alerta abre um chamado — cada destino com o ícone, a sigla e a descrição da ferramenta, para não haver dúvida sobre em qual sistema ele vai abrir. Um alerta pode abrir em mais de um destino ao mesmo tempo.

A lista não traz os destinos marcados como Disponível na abertura manual: esses são do botão Abrir chamado da mensagem com erro, com campos que um operador preenche. Um destino já vinculado continua na lista, para poder ser desligado.

Em Aplicação Offline aparece também Só abrir chamado após (minutos), com 5 de padrão: o e-mail sai na hora, e o chamado só se a Aplicação continuar fora depois desse tempo. A deduplicação, o alerta de recuperação e o que acontece quando a própria ferramenta cai estão em Help Desk.

Achar o que está ativo

Uma Aplicação acumula dezenas de alertas pré-cadastrados e desativados, e os poucos ativos se perdem no meio deles. Três recursos respondem “onde está ligado?” sem abrir linha por linha:

Contagem por nível. Os grupos Aplicação, Interface e Definição trazem, à direita, quantos alertas estão ativos e inativos — na mesma coluna dos contadores da Aplicação. Correndo o olho para baixo, dá para ver em qual nível estão os ativos.
Resumo da Aplicação aberta. Uma faixa no topo mostra onde estão os ativos, com um selo por local — a própria Aplicação, cada Interface, cada Definição, com a quantidade — e por quais canais eles avisam: e-mail, WhatsApp e chamado.
Ver onde está ativo. O botão da faixa, ou o contador verde no cabeçalho da Aplicação (sem precisar expandir), abre um popup com os alertas ativos agrupados pelo local em que valem, com os canais, os destinos de chamado, os destinatários e o lápis que abre a edição.

Os alertas ativos de uma Aplicação, agrupados por onde valem

A contagem, a faixa e o popup respeitam os filtros e a busca da tela.

Onde mais os alertas aparecem

No sino do cabeçalho, com contagem de não lidos.
No Painel de Aplicações e no Cockpit, como alerta sonoro e título de aba piscando quando uma aplicação monitorada cai.
Na tela de Definições, onde os alertas daquela definição podem ser configurados sem passar por aqui.

Permissão

A Ferramenta é /alerts. Como todas as telas agrupadas por Aplicação, o usuário só enxerga alertas das Aplicações e Interfaces a que tem acesso.

Alertas — /alerts