Cadastros

Estas quatro telas são a espinha dorsal da configuração. A ordem de criação importa: Aplicação → Interface → Definição/Coleta.

Aplicações — /applications

Cadastro dos sistemas integrados. Além de nome e sigla, a Aplicação controla:

• Monitoramento de disponibilidade — o tipo de keep-alive (HTTP, banco, MQTT, OPC UA, Modbus, SAP, PI…) e a Conexão Externa usada; alimenta o Painel de Aplicações e o relatório de uptime
• Prioridade, ícone e logotipo — o que ordena e identifica a aplicação nos painéis
• Observações — texto livre que aparece no Cockpit e no corpo do alerta de aplicação offline; na prática, o telefone de quem atende aquele sistema
• Agrupamento — praticamente toda tela do sistema filtra por aplicação

Os botões da linha

Uma Aplicação recém-criada e ainda sem Interface mostra um convite no topo da tela, oferecendo o assistente correspondente. É a forma mais rápida de sair do zero.

URL própria ou Conexão Externa

Uma Aplicação HTTP tem duas formas de dizer onde o sistema dela está, escolhidas no campo Endereço:

• URL própria — a URL, a URL de Keep Alive e o certificado ficam na própria Aplicação. É o padrão, e é como toda Aplicação HTTP funcionava antes.
• Conexão Externa — os três valores vêm de uma Conexão HTTP e aparecem travados, com cadeado. Trocar o endereço na conexão troca em todas as Aplicações ligadas a ela, e nas Entregas HTTP delas.

Use a Conexão Externa quando mais de uma Aplicação fala com o mesmo servidor. A Credencial continua na Aplicação nos dois modos. Na lista, a Aplicação ligada mostra um ícone de tomada ao lado da URL, com o nome da conexão.

Transformar em Conexão Externa. Na edição de uma Aplicação HTTP com URL própria, o link abaixo da URL cria uma Conexão HTTP com os dados dela e a liga à conexão. A janela sugere as outras Aplicações que usam o mesmo endereço, sem nenhuma marcada, e avisa quando o Keep Alive ou o certificado de alguma delas é diferente: ao ser ligada, ela passa a usar os da conexão. Só vai junto o que for marcado. É preciso ter permissão de criar Conexões Externas.

O Tipo de Conexão, depois que há Coleta ou Entrega

O Tipo de Conexão de uma Aplicação decide como todas as Coletas e Entregas dela executam. Por isso, na edição de uma Aplicação que já tem alguma Coleta ou Entrega, o campo abre travado, com cadeado e a quantidade de Coletas e Entregas que dependem dele. Não há como destravar: trocar HTTP por SQL, por exemplo, deixaria as Entregas HTTP sem endereço e as Coletas SQL sem banco. O servidor recusa a troca também pela API, pelo MCP e por import.

Continua permitido:

• trocar a Conexão Externa por outra do mesmo tipo;
• editar a URL, e passar uma Aplicação HTTP de URL própria para Conexão Externa e de volta;
• trocar o tipo de uma Aplicação que só tem Interfaces, sem Coleta nem Entrega.

Nas Aplicações InfluxDB com Coleta ou Entrega InfluxDB, as conexões InfluxDB de outra versão aparecem desabilitadas no seletor: cada versão (1.8, 2.x, 3.x) fala uma linguagem de consulta e grava por um endereço diferente.

Interfaces — /interfaces

CRUD das interfaces de processamento, com:

• Tipo: ENTREGA ou COLETA
• Ordem de processamento: SEQUENCIAL (ordem preservada) ou PARALELO (throughput)
• Agendamento: cron ou intervalo fixo — é o que vira o job em Agendadores
• Dias de retenção de mensagens: por quanto tempo as mensagens desta interface são mantidas antes do expurgo automático da madrugada
• Alerta de mensagens acumuladas: o teto a partir do qual o alerta dispara
• Bloquear / liberar: segura a entrega sem perder mensagens

Dentro do cartão de cada Aplicação, as Interfaces vêm separadas em dois blocos — Coleta e Entrega — com as mesmas faixas de título e as mesmas cores de Definição de Mensagem. Numa aplicação com dez interfaces, o badge colorido da sigla não deixava ver de longe quantas eram de cada lado.

Todo bloqueio e desbloqueio é registrado — manual ou automático por erro de negócio, com autor e duração — e sai no relatório de Bloqueio de Interfaces.

As ferramentas de chamado ativadas em Help Desk aparecem aqui numa categoria própria, Help Desk, depois de Arquivos — com a Interface por onde os chamados saem. É por ela que se bloqueia, libera ou acompanha a fila de chamados. Elas não aparecem em Aplicações: nascem e são desativadas pela aba Help Desk.

Definições — /definitions

O contrato de entrega. Os campos que mais geram dúvida:

Permitir reenvio

A chave Permitir reenvio fica no cabeçalho do formulário, ao lado do Testar, na Entrega e na Coleta — vale para a Definição inteira, e já aparece em Nova e Duplicar. Vem desligada: se o destino não trata duplicidade, reenviar pode lançar o mesmo dado duas vezes, e quem configura a integração é quem sabe se ele aguenta. Como reenviar está em Mensagens.

Validações de Recebimento

A seção reúne o que vale para a mensagem quando ela chega ao CMS: o Content-Type e a validação dele, o tamanho máximo do payload, Ativar WebService (WSDL) — com a opção de WS-Security no cabeçalho — e a chave Expor como ferramenta MCP.

Logo abaixo fica a URL da API Dinâmica desta Entrega, POST /api/{interface}/{sigla}, com botão de copiar — o mesmo visual da Coleta. Enquanto Interface e sigla não estão preenchidas, um aviso em âmbar pede os dois; com o WebService ligado, a URL do WSDL aparece logo embaixo. É a URL que se entrega ao time do sistema produtor, sem precisar abrir o Como Enviar.

O editor do Payload de Entrada — os parâmetros e o Payload de Entrada Modelo, nas Entregas HTTP, SQL, MQTT e de arquivo — também mora aqui, junto do endereço para onde o produtor manda. Só mudou de lugar: os aliases continuam sendo resolvidos no envio ao destino, não no recebimento.

Transformador por Aplicação produtora

Uma Entrega costuma receber de mais de um sistema — o WMS e o SVAI mandando para o mesmo destino —, e nem sempre no mesmo formato. Em vez de um Transformador que tenta reconhecer cada dialeto, cada Aplicação produtora pode ter o seu: ele converte o que ela manda para o formato que a Entrega espera (o Payload de Entrada Modelo) e roda antes do Transformador da Entrega, que continua valendo para todas as mensagens.

Quando a Interface tem duas ou mais Aplicações produtoras liberadas — pelas API Keys e Credenciais de Entrada que valem para ela —, o campo Transformador do formulário vira o botão Configurar, com um resumo ao lado (1/3 produtoras · Entrega: nome). Ele abre o popup Transformador por Aplicação produtora:

Aplicar só leva a escolha para o formulário; quem grava é o Salvar da Entrega, e Cancelar descarta o que foi mexido no popup. Tirar o Transformador de uma produtora que já tinha um mostra, no popup e embaixo do campo, quem vai perdê-lo ao salvar — as mensagens dela passam a ser tratadas como se já viessem no formato da Entrega. Duplicar a Entrega leva a lista junto, e cada alteração dela entra no histórico de alterações da Entrega.

Quem é a produtora de uma mensagem decide-se por quem autenticou: a Aplicação usuária da API Key ou da Credencial de Entrada. Depois do Transformador dela, tudo o que lê o payload enxerga o formato da Entrega, e não o dialeto da produtora — o contrato de entrada, os {{alias}}, o :alias do SQL e do SAP e as tags de OPC UA, Modbus e PI. Produtora sem Transformador próprio segue exatamente o caminho de antes.

O campo continua como Configurar enquanto houver linha gravada, mesmo que só reste uma produtora — sumir com o popup esconderia uma configuração que continua valendo. Na grade de Entregas, o quadro Aplicações Externas (via HTTP) ganha a coluna Transformador próprio quando alguma produtora tem um.

O caminho, e o host que vem da Aplicação

Nas entregas HTTP e SOAP, o campo URI Post Message guarda só o caminho: o host sai da URL da Aplicação, cadastrada em Aplicações. O mesmo vale para o Caminho de Coleta (URL) de uma Coleta HTTP. Em execução, o CMS concatena os dois pedaços — e é por isso que colar a URL inteira no campo produzia https://host.com.brhttps://host.com.br/api/...: o salvamento passava, e o erro só aparecia na primeira execução, com cara de falha de rede.

Agora a URL da Aplicação aparece dentro da mesma caixa, travada e mais apagada, colada à esquerda do que você digita — porque em execução as duas partes são mesmo uma URL só. E se um valor absoluto entrar mesmo assim (colar não olha para o prefixo), um aviso mostra o problema com a correção a um clique: Usar só o caminho corta o host e mantém o resto.

Coletas — /collectors

O sentido inverso: o CMS busca o dado. Cada Coleta tem uma origem (com sua Conexão Externa) e um ou mais encaminhamentos — as interfaces/definições que recebem o resultado. A exceção é a Coleta só de consulta, cujo destino é quem a chamou.

Detalhes por protocolo estão em Integrações.

Pontos comuns a todas as coletas:

• Agendamento — coletas do tipo pull (HTTP, SQL, SAP RFC, Modbus poll) rodam por cron ou intervalo, gerenciados em Agendadores
• Coletas por evento — MQTT, SAP IDoc e OPC UA trigger reagem ao acontecimento, sem polling
• Transformador — aplicável ao payload coletado, antes do encaminhamento
• Condição por encaminhamento — o botão Regras em cada linha de Encaminhar Coleta: aquele destino só recebe a leitura que atende a regra. Ver Condições sobre o dado
• Resultado da última execução — sucesso/erro fica visível na listagem

Detalhes da conexão

As seções de origem (na Coleta) e de destino (na Entrega) diziam apenas “usa a Conexão Externa configurada em Aplicações: X”. O nome não conta em qual servidor a integração lê nem onde grava, e descobrir isso exigia abrir Conexões Externas — tela que boa parte dos operadores nem enxerga.

Agora uma barra mostra nome, tipo e endereço ali mesmo, e um clique abre um popup com os campos daquela conexão. Vale nos formulários de Coleta e de Entrega e no painel de detalhes das duas grades.

O popup traz também um badge ON/OFF, que é o status como esta Aplicação enxerga a conexão, e não o agregado da tela de Conexões Externas: se o Keep Alive dela está OFF, a Coleta e a Entrega dela não rodam, mesmo que outra Aplicação alcance o mesmo servidor. O valor vem do último ciclo já gravado, então abrir o popup não dispara logon no SAP nem abre pool no Oracle.

Abaixo dos campos vem a disponibilidade por dia: uma barra para cada um dos últimos 30 dias, verde no dia em que a conexão ficou de pé do começo ao fim e colorida no dia em que houve queda, pelos mesmos cortes do relatório de Disponibilidade — meta de 99%, atenção a partir de 95%. O badge responde “está de pé agora?”; a faixa responde “isso vive caindo?”, que é a pergunta que decide se vale investigar. Com o mouse sobre um dia aparecem o percentual, quanto tempo ele ficou offline e quantas paradas houve.

Barra cinza é dia sem monitoramento: antes de a Aplicação existir, e o pedaço de hoje que ainda não aconteceu. Ela nunca aparece verde — dia sem medição não é dia sem queda —, e o percentual do período também deixa esses dias de fora, senão uma Aplicação criada há três dias apareceria com 80% só por não existir antes.

Ao salvar uma Coleta ou uma Entrega

O aviso de resultado

Salvar uma Coleta ou uma Entrega — em Coletas, em Entregas ou em Definição de Mensagem — abre um aviso com o resultado, em vez de fechar o formulário em silêncio:

Antes, o formulário simplesmente sumia no sucesso, e o erro era uma faixa no pé do formulário, fácil de não ver num modal comprido.

Fechar sem salvar

O formulário de Coleta e de Entrega abre em tela cheia, e o fechar do cabeçalho é um botão Fechar, com texto — o X ficava logo abaixo do X da aba e da janela do navegador.

Com alteração não salva, fechar pergunta antes: Continuar editando ou Fechar sem salvar. Vale para o botão, para o clique fora do formulário e para o Fechar do aviso de erro. Fechar a aba ou a janela do navegador também faz o próprio navegador perguntar.

A sigla é única no sistema todo

A sigla de uma Coleta, e a de uma Entrega, não se repete em lugar nenhum do CMS — não só dentro da mesma Interface. Tentar gravar uma sigla que outra Definição já usa dá um erro que diz exatamente isso e pede para informar outra sigla. Antes, a mesma situação aparecia como “Erro interno do servidor”, porque só o banco barrava.

O mesmo vale, com uma mensagem genérica, para os demais cadastros com campo que não pode se repetir: o CMS responde que já existe outro registro com aquele valor, sem expor nome de coluna nem de restrição do banco.

Nenhuma lista aceita nome repetido

Nas listas em que cada linha tem um nome, dois itens com o mesmo nome não são aceitos. O segundo sumiria sem aviso — o nome vira chave de JSON, :alias num SQL ou {{alias}} num modelo —, e o defeito só apareceria em execução.

A linha repetida ganha borda vermelha e a dica Nome repetido, e o Salvar fica bloqueado até resolver. A comparação ignora espaço nas pontas e diferencia maiúscula de minúscula — Lote e lote são chaves diferentes num JSON. O servidor confere pela mesma regra, então uma gravação pela API também é recusada — com exceção dos Parâmetros Fixos, que já saem da tela convertidos em objeto JSON e por isso só a tela confere.

Definição de Mensagem — /message-management

A visão unificada: todas as Coletas e Entregas de uma Aplicação na mesma tela, agrupadas por Interface. É por aqui que se responde “o que esta aplicação troca com o CMS?” sem alternar entre duas telas.

Uma Interface criada e ainda não configurada aparece no fim da lista, atenuada e com contagem zero — antes ela simplesmente não existia nesta tela, justamente para quem precisava terminar de configurá-la. Ela some quando há filtro ou busca ativa, que é quando a procura é por algo específico. Dentro de cada Interface, as linhas vêm ordenadas por sigla.

A categoria Help Desk também aparece aqui, com a Entrega de cada ferramenta de chamado — e os filtros de Aplicação, Interface e Definição a incluem.

Cada linha traz o botão Configurações, que abre num popup tudo o que orbita aquela Definição, em abas: Erros de Negócio, Alertas, Transformer, Contrato, Regras de Criptografia, Agendador, Credencial, API Keys e Usuários com acesso. E o botão Relatório, que gera o consolidado dessa Definição — exportável em PDF, útil como documentação de entrega de projeto. No popup, o download do PDF é o ícone à direita das abas, na mesma linha delas.

Numa Definição exposta como ferramenta MCP, a aba API Keys traz também a linha Exposta como ferramenta MCP, com o nome da ferramenta e o endereço onde um agente de IA a chama — é a outra porta de entrada da mesma Definição, além das chaves listadas ali.

Contrato Observado

A aba Contrato mostra o formato real dos payloads daquela Definição, inferido das mensagens que já passaram por ela. Não é declarado à mão: é o que de fato trafegou.

Para cada campo, o contrato registra o tipo e em quantas das mensagens observadas ele apareceu. É essa segunda informação que faz diferença: saber que itens chega ora número, ora texto, e falta em uma de cada cinco mensagens, é o que separa um Transformador que funciona de um que quebra na terceira mensagem.

A origem do contrato fica registrada: observado do tráfego, vindo do assistente ou editado manualmente. Editar à mão zera o contador de amostras — ele descreve uma observação, e um schema digitado deixou de ser uma.

A sigla, depois que já está em uso

A sigla de uma Aplicação, de uma Interface, de uma Coleta ou de uma Entrega não é um rótulo: ela é endereço. A sigla da Interface e a da Coleta/Entrega formam a URL pública por onde os sistemas externos chamam o CMS, e a da Aplicação identifica a app em pack, coleção do Postman e automação. Alterar por engano quebra integração que já está no ar, e o estrago aparece do lado de fora — no sistema do cliente, não numa tela daqui.

Por isso, na edição, o campo abre travado, com um cadeado ao lado. Na criação e na duplicação não: ali ainda não existe nada apontando para ele.

Clicar no cadeado abre um aviso que diz o que aquela troca leva junto, e o texto muda conforme o que está sendo alterado:

Confirmado o aviso, o campo libera e passa a exibir um lembrete em âmbar até o salvamento. O cadeado volta a fechar a qualquer momento, descartando a alteração e devolvendo o valor atual.

Numa Coleta ou numa Entrega, o campo Interface trava junto com a sigla: trocar a Interface muda a URL tanto quanto trocar a sigla, porque ela é o primeiro trecho do caminho. Ele abre travado, com o cadeado no lugar da seta e uma dica apontando para a sigla, e só libera pelo cadeado dela — cujo aviso ganha uma linha dizendo que a Interface vem junto. Travar de novo devolve as duas ao valor do cadastro. A troca de Interface entra no histórico de alterações da Definição.

O mesmo cadeado protege o nome do Transformador, que não forma URL mas é a chave natural de importação e exportação: renomear faz um pack antigo criar um Transformador novo em vez de atualizar o existente. A ação de auditoria é ALTERAR_NOME_TRANSFORMADOR — ver Transformadores.

API dinâmica de Coleta

Uma Coleta com Parâmetros de Entrada pode ser acionada de fora, na hora, por quem informa esses parâmetros:

POST /api/collect/{sigla-da-interface}/{sigla-da-coleta}

É o equivalente, para Coleta, do endpoint de recebimento de Entrega: endpoint público (sem login de usuário) que recebe os Parâmetros de Entrada em JSON, faz a busca na origem com eles na mesma hora e enfileira o resultado — o encaminhamento aos destinos roda no próximo ciclo da fila. A autenticação usa o mesmo esquema do recebimento de mensagens: header x-api-token, Authorization: Bearer <token>, ou Authorization: Basic — com o token na posição da senha, ou com o login e a senha de uma Credencial de Entrada.

Uma Coleta assim deixa de rodar pelo agendador: quem a dispara é o sistema de fora, um Gatilho ou um agente de IA.

No formulário

A URL da API Dinâmica aparece no formulário assim que a Coleta ganha a primeira linha de Parâmetro de Entrada — em todos os tipos que usam esse editor (HTTP, SQL Server, Oracle, PostgreSQL, SQLite, MongoDB, InfluxDB) e no SAP, pelas Variáveis de Entrada. Enquanto a linha não tem nome, o lugar da URL pede para preenchê-lo: a URL só existe com ao menos um alias, que é a mesma regra do servidor. Antes, o bloco só surgia depois de digitar o alias, e a tela parecia não reagir ao clique em Adicionar parâmetro.

Na mesma linha da URL ficam Ativar WebService (WSDL) e Expor como ferramenta MCP. Logo abaixo, Devolver o resultado da coleta na resposta da API — ver a seção seguinte.

Como enviar

Na lista de Coletas, a expansão Detalhes da coluna Coleta tem o botão Como Enviar em toda Coleta com API dinâmica — a mesma que já existia nas Entregas. O popup traz:

• a URL e quais Parâmetros de Entrada são obrigatórios;
• o curl com API Token e com Basic Auth, com o corpo já montado dos parâmetros (cada alias com o valor padrão);
• o que a resposta traz — só o recibo, ou também collected_payload;
• com o WebService ligado, o WSDL e um envelope ExecutarColetaRequest pronto.

Download PDF, no cabeçalho, leva o mesmo conteúdo para entregar ao time do sistema que vai chamar. O corpo é o mesmo da coleção do Postman. No Como Enviar da Entrega, o exemplo segue a mesma regra: com Payload de Entrada, o corpo traz os aliases dele, e não mais um {"campo": "valor"} genérico.

O resultado na resposta

Por padrão, a resposta da API é só um recibo: a busca rodou e o resultado segue para os destinos. Ligando Devolver o resultado da coleta na resposta da API, a resposta traz também o que a busca trouxe, em collected_payload — e o encaminhamento aos destinos continua como antes.

{
  "id_message": "17d50724-94e3-4bc1-a7bd-3a6385cfe9dc",
  "message_type": "SYNC",
  "return_message": "Data collected successfully",
  "hasError": false,
  "collected_payload": [ { "vazao": [ { "timestamp": "2026-09-23T12:00:00Z", "valor": 128.4 } ] } ]
}

message_type é SYNC porque a busca roda dentro da chamada; sem Devolver o resultado, o return_message passa a ser Data collected; forwarding to destinations queued.

• Um item por mensagem, na mesma ordem de id_message: uma Coleta SQL que trouxe três linhas devolve três itens.
• Conteúdo JSON volta como JSON; XML e texto voltam como texto.
• Conteúdo gravado cifrado não sai. Se a Coleta cifra o que grava (Regras de Criptografia), a posição vem null e a resposta traz "collected_payload_omitted": "encrypted".
• Com a Aplicação de origem fora do ar, a busca fica para quando ela voltar, e a resposta não traz resultado.

Quem autoriza é a Coleta, não quem chama — por isso é uma chave no cadastro, e não um parâmetro da requisição. Ela só aparece quando há Parâmetro de Entrada, porque sem API não há resposta a quem devolver.

Coleta só de consulta

Com Devolver o resultado ligado, a Coleta pode ficar sem destino nenhum: quem chama a API é o destino. Ela salva e ativa normalmente sem encaminhamento — no lugar do aviso de “salva inativa”, a tela explica o modo consulta —, e cada mensagem continua registrada no histórico, já como Processada, sem esperar encaminhamento e sem depender do agendador da Interface.

É o jeito de oferecer uma consulta sob demanda — “leia estas tags do PI neste período e me devolva” — sem inventar um destino só para cumprir tabela. Sem a chave, a regra de antes vale: Coleta sem destino é salva inativa.

Valor padrão com Variável

O valor padrão de um Parâmetro de Entrada pode conter Variáveis — {{TURNO_INICIO}}, por exemplo —, e elas são resolvidas na execução. Só o valor padrão é resolvido: o que o sistema de fora envia chega como veio. Se não fosse assim, quem chama poderia mandar {{NOME_DE_UMA_VARIAVEL}} e ler o valor dela na resposta da origem.

A mesma API em SOAP

Ligando Ativar WebService (WSDL), a mesma API passa a responder também como Web Service SOAP — para o sistema do outro lado que só sabe importar um WSDL:

GET  /api/ws/collect/{sigla-da-interface}/{sigla-da-coleta}?wsdl
POST /api/ws/collect/{sigla-da-interface}/{sigla-da-coleta}

A operação é ExecutarColeta, e cada Parâmetro de Entrada vira um elemento dentro de <parametros>, em qualquer ordem. O WSDL só exige o parâmetro obrigatório sem valor padrão — o que tem valor padrão, o próprio CMS completa. Um alias que não pode ser nome de elemento XML (começa com número, tem espaço) fica fora do contrato, e o WSDL diz quais ficaram.

A resposta segue o contrato do REST: um id_message por mensagem gerada — uma Coleta SQL que trouxe cinco linhas devolve cinco —, mais return_message e hasError. Com Devolver o resultado ligado, vem também um <collected_payload> por mensagem, com o conteúdo em texto (o JSON serializado). Os valores chegam como texto: 000123 continua 000123, e não vira o número 123.

Sem Parâmetro de Entrada não há URL, e o endereço SOAP responde 404, como o REST. A URL do WSDL aparece no formulário, no painel de detalhes da grade, no PDF e no relatório da Definição, e a coleção do Postman passa a trazer o WSDL e um envelope de exemplo da Coleta.