Erros de Negócio — /business-errors
O transporte deu certo — HTTP 200, RFC executada, INSERT aceito — e mesmo assim a mensagem não fez
o que deveria fazer. O destino respondeu “ordem não liberada”, “CPF inválido”, “período contábil
fechado”. Para o CMS, tecnicamente, foi sucesso.
Os Erros de Negócio corrigem essa leitura: são regras que olham o conteúdo do que entrou ou do que voltou e dizem “isto foi uma falha”.
Sem essa classificação, um destino que rejeita tudo aparece nos painéis como 100% de sucesso — e o problema só é descoberto quando alguém sente falta do dado, dias depois.
Anatomia de uma regra
| Campo | Papel |
|---|---|
| Aplicação | A Aplicação dona da regra. Uma regra nunca atravessa Aplicações |
| Onde a regra vale | Definições escolhidas, ou toda a Aplicação |
| Código do Erro | Opcional. O código do sistema de origem, para agrupar nos relatórios |
| Termos de Busca | O que procurar no payload. Vários termos separados por ; |
| Validar contra | Entrada, Saída ou Ambos |
| Motivo | Texto livre explicando por que aquele erro costuma acontecer |
| Bloqueia Interface | Se detectar, para a interface inteira |
| Ativo | Liga/desliga a regra sem apagá-la |
Onde a regra vale: Definições escolhidas ou a Aplicação inteira
Uma regra vale para várias Definições ao mesmo tempo, inclusive de Interfaces diferentes da mesma Aplicação. “Período contábil fechado” costuma ser o mesmo texto em toda integração financeira, e não precisa ser cadastrado uma vez por Definição.
| Escopo | Alcance |
|---|---|
| Definições escolhidas | Só as que você marcar na lista |
| Toda a Aplicação | Todas as Definições da Aplicação, inclusive as criadas depois |
Com Toda a Aplicação, o CMS mantém os vínculos sozinho: uma Definição nova — criada à mão, por import, por pack ou por assistente — já nasce coberta pela regra. Na lista, essas regras trazem a etiqueta Aplicação.
Um Erro de Negócio nunca atravessa Aplicações. “Toda a Aplicação” é o alcance máximo, e é por isso que a Aplicação é escolhida antes de tudo no formulário.
Numa regra de escopo Toda a Aplicação não existe “desvincular só desta Definição” — a próxima sincronização devolveria o vínculo. Para tirá-la de circulação, mude o escopo ou exclua a regra.
Termos de busca: OR, não AND
ordem_error;quantidade=0 significa “qualquer um destes”. Basta um termo aparecer no payload
para a mensagem ser classificada. Um termo só se comporta exatamente como antes de existir a
separação por ;.
A comparação é por conteúdo literal (substring), não por expressão regular — é o que permite colar o trecho da mensagem de erro do sistema de origem e funcionar.
O que fica gravado na mensagem é o texto inteiro do campo Termos de Busca, não o termo que casou. É por esse texto que o relatório de Erros de Negócio agrupa — editar o campo depois muda o agrupamento das mensagens novas.
Validar contra: entrada, saída ou ambos
| Direção | Olha |
|---|---|
| Entrada | O payload que a interface recebeu |
| Saída | O retorno que o destino devolveu |
| Ambos | Os dois |
A maioria das regras é de Saída — é lá que mora a resposta do destino. Entrada é útil para recusar cedo uma mensagem malformada, antes de gastar uma chamada ao destino.
Alguns tipos de Coleta não têm lado de entrada — uma assinatura MQTT, por exemplo, é recepção passiva. Ali, uma regra de Entrada simplesmente nunca casa; não gera erro nem aviso.
Bloqueio de interface
Este é o mecanismo que diferencia o CMS de um simples log de erro.
Marcando Bloqueia Interface, a primeira mensagem que casar a regra para a interface. As
mensagens seguintes ficam na fila, intactas, esperando. O bloqueio fica registrado com origem
ERRO_NEGOCIO, o texto da regra e o ID da mensagem que o causou.
Por que isso é desejável: sem o bloqueio, um destino em estado inválido — período fechado, cadastro faltando, sistema em manutenção lógica — receberia centenas de mensagens que ele vai rejeitar uma a uma. Todas viram erro, todas precisam ser reprocessadas depois, e o histórico fica poluído.
Como liberar
O desbloqueio é registrado com a origem:
| Origem | Quando |
|---|---|
| Manual | Alguém liberou a interface na tela de Interfaces ou na Danger Zone |
| Reprocessamento | A mensagem que causou o bloqueio foi reprocessada com sucesso |
| Cancelamento | A mensagem que causou o bloqueio foi cancelada |
Os dois últimos são o caminho normal: resolva a causa e a interface libera sozinha. Todo o histórico fica no relatório de Bloqueio de Interfaces.
Bloqueio é uma decisão de negócio, não técnica. “CPF inválido” quase nunca deve bloquear — é um problema daquela mensagem. “Período contábil fechado” quase sempre deve — nenhuma mensagem vai passar até alguém abrir o período.
Regras automáticas
Algumas regras não são digitadas aqui: o CMS as mantém sincronizadas a partir de outra tela, e elas aparecem na lista com a etiqueta AUTO. Nelas, o único campo editável é Bloqueia Interface — o resto pertence à tela de origem.
| Etiqueta AUTO gerada por | Origem |
|---|---|
| Tags OPC UA obrigatórias | Tags de Leitura da Coleta / Tags de Escrita da Entrega, marcadas “obrigatório” |
| Tags Modbus obrigatórias | Idem, no adaptador Modbus |
| Payload de Entrada obrigatório | Campos marcados “obrigatório” no popup Parâmetros Função SAP de uma Entrega SAP RFC |
A lógica dessas regras é invertida em relação às normais: em vez de “este termo apareceu”, elas verificam “estes valores estão presentes”. Valor nulo, vazio ou zero conta como ausente — o que num CLP é exatamente o caso a tratar: uma tag que não foi escrita neste ciclo devolve zero, não erro.
Isso resolve um problema real de chão de fábrica: o CLP responde com sucesso e devolve zero em todas as tags porque a peça ainda não passou. Sem essa regra, o CMS gravaria uma medição de zero como se fosse leitura válida.
O que acontece com a mensagem
A mensagem classificada fica com status Erro Negócio e guarda o texto da regra que casou e o motivo cadastrado. Ela aparece em:
- Mensagens com Erro, onde pode ser reprocessada em lote;
- no relatório de Erros de Negócio, agrupada por aplicação, interface e definição;
- no alerta Erro de Negócio, se houver um configurado — ver Alertas.
Permissão
A Ferramenta é /business-errors. Como as demais telas agrupadas por Aplicação, ela exige também
que o usuário enxergue a Aplicação e a Interface correspondentes.