Roteadores — /routers

Uma Entrega recebe em POST /api/{interface}/{entrega} e entrega para um destino. Quase sempre é isso que se quer. Quando o mesmo dado precisa ir para vários destinos — às vezes para todos, às vezes só para alguns, conforme o conteúdo —, o caminho é um Roteador.

O Roteador é uma API genérica, que não pertence a nenhuma Aplicação:

POST /api/router/{sigla}

Ele recebe o payload, confere o contrato de entrada, percorre um fluxo de decisões e cria uma mensagem em cada Entrega que o fluxo alcançou. Ele não entrega nada sozinho: destino, credencial, Transformador, cifra, retentativa e Erro de Negócio continuam sendo da Entrega, que recebe a mensagem como se fosse de um produtor externo.

A lista

Cada linha mostra a sigla e o nome, a URL, os destinos — quantas Entregas e as Aplicações delas, cada uma com o ícone e o badge do tipo de conexão, que abre os detalhes da conexão — e o tráfego das últimas 24 horas. O ícone de robô ao lado da sigla indica que o Roteador está exposto como tool MCP.

O filtro do topo é pelas Aplicações de destino, e a busca procura por sigla, nome, descrição, nome da tool ou Aplicação de destino. A coluna Ativo liga e desliga direto da lista; desligar pede confirmação, porque o Roteador para de aceitar chamadas na hora (quem chamar recebe 503) e as Coletas que encaminham para ele deixam de distribuir.

O fluxo

O fluxo é uma árvore a partir do Início (o payload chegou), com dois tipos de passo:

• Decisão — uma condição sobre o payload, com regras e grupos E/OU. Tem um lado Se SIM e um lado Se NÃO, e cada lado pode levar a vários passos.
• Entrega — o fim do caminho: uma Entrega já cadastrada em Gerenciamento de Mensagens, escolhida em três combos — Aplicação, Interface e Entrega. Quando a Aplicação tem uma Interface só, ela já vem escolhida. As Aplicações de Help Desk não aparecem: chamado se abre por alerta, não por Roteador. Na ligação que chega à Entrega dá para escolher um Transformador, que converte o payload do Roteador para o que aquela Entrega espera (antes do Transformador da própria Entrega). Na lista, o Transformador fica na mesma linha da Entrega, depois dela.

Os dois jeitos clássicos de distribuir são só formatos do mesmo fluxo:

A aba Fluxo edita em lista indentada; o botão Diagrama mostra o mesmo fluxo desenhado, da esquerda para a direita. Erros (ciclo, decisão sem condição, passo solto) aparecem enquanto você monta e impedem salvar; avisos (decisão sem saída, a mesma Entrega por dois Transformadores diferentes) só alertam.

No Diagrama, cada caixa de Entrega traz a Entrega, a Aplicação com o tipo de conexão, a Interface e, em roxo, o Transformador da rota, quando houver. A caixa de Decisão mostra o nome e quantas regras ela tem.

O contrato de entrada

Na aba Contrato:

• Definir aqui — os campos de primeiro nível do JSON recebido, com Obrigatório (um toggle) e valor padrão. O botão Sugerir do tráfego mostra os campos que chegaram nas últimas 50 chamadas.
• Herdar de uma Entrega — usa o Payload de Entrada de uma Entrega existente, lido a cada chamada: mudar o contrato dela muda o do Roteador. A Entrega é escolhida nos mesmos três combos do fluxo.

Os campos do contrato também ficam disponíveis nas decisões como input.<campo>.

O valor padrão vale quando o campo não vem no payload, e aceita Variáveis Globais pelo botão {} — {{TURNO_PADRAO}}, por exemplo, resolvida a cada chamada. Só as Globais: o Roteador não pertence a nenhuma Aplicação.

O Tamanho máximo do payload em 0 (ou vazio) usa o limite global de Configurações; um valor próprio só pode ser menor que ele.

O que fazer quando o payload não cumpre o contrato é uma escolha do Roteador:

Quem pode chamar

O Roteador aceita as mesmas formas de autenticação da Entrega — x-api-token, Authorization: Bearer ou Basic —, mas com chaves do grupo Roteadores, criadas em API Keys e Credenciais. Uma chave de Aplicação não autentica num Roteador, e uma chave de Roteador não autentica numa Interface. A aba Acesso lista quem pode chamar aquele Roteador e, abaixo, Como chamar este Roteador: a URL POST /api/router/{sigla}, um cURL com API Key (x-api-token) e um com Credencial (Basic), os dois com o JSON do contrato no corpo, e o formato da resposta, descrito a seguir. Cada bloco tem o botão de copiar.

A resposta é sempre imediata: o Roteador decide as rotas na chegada e cria as mensagens logo em seguida.

{
  "id_message": "b81c090a-…",
  "message_type": "ASYNC",
  "return_message": "Message received and routed to 2 destination(s)",
  "hasError": false,
  "routes": ["SAP/CONFIRMA_ORDEM", "QMS/NAO_CONFORMIDADE"]
}

É o mesmo formato da resposta de uma Entrega. id_message é o id da execução do Roteador — as mensagens de cada rota nascem logo depois, uma por Entrega. Procurado no Ctrl+K ou aberto em /messages/{id}, ele leva às mensagens que aquela execução gerou. routes lista as Entregas escolhidas. return_message diz o que aconteceu:

Uma Coleta também pode mandar o que coletou para um Roteador: no encaminhamento da Coleta, escolha o destino Roteador em vez de Entrega. A condição e o Transformador do encaminhamento continuam valendo antes do Roteador. Como não há quem receba um 400, “Recusar” vira “Registrar” para essa origem. Um Gatilho também pode ter um Roteador como alvo, com agenda e valores fixos.

Simular e testar

A aba Simular mostra o caminho que um payload faria agora, com o fluxo salvo: as decisões com o valor lido em cada regra, as Entregas que receberiam e o diagrama com o caminho aceso. Nada é gravado nem enviado.

Com contrato, a caixa já abre com o JSON dos campos para preencher, e a linha de cima lista os obrigatórios. Campo com valor padrão fixo vem preenchido; o que tem Variável Global vem vazio — vazio conta como ausente, e o servidor aplica o padrão resolvido. Modelo do contrato volta a caixa para esse JSON, e Usar a última chamada traz o payload real mais recente.

Executar como teste manda de verdade, pelo mesmo caminho de uma chamada externa, com as mensagens marcadas como teste — como no Banco de Testes, e por isso exige essa Ferramenta.

Execuções

Cada chamada vira uma execução, com a origem (API, Coleta, Gatilho — com o nome dele —, teste ou MCP), o caminho percorrido, as mensagens geradas e o payload — este só para quem enxerga todas as Aplicações para onde ele foi.

Cada mensagem gerada aparece com a Aplicação (ícone e badge de conexão), a Interface, a Entrega e a situação da mensagem. No fim da linha, a seta abre a mensagem completa numa janela nova, sem fechar o Roteador, e o ícone de mensagem — na cor da situação — abre o resumo, o mesmo popup de Mensagens.

A situação da execução é a do roteamento:

O desfecho de cada entrega é o da própria mensagem — abra-a para ver. Na lista de Mensagens, a mensagem gerada por um Roteador leva a marca dele, e Ver as mensagens geradas abre a lista já filtrada.

• Reprocessar as rotas com falha tenta de novo só o que falhou; quem já recebeu não recebe de novo.
• Rotear novamente passa o mesmo payload pelo fluxo atual, numa execução nova que aponta para a original e registra quem pediu. Entregas que já receberam podem receber de novo — por isso pede confirmação.

No Painel e em Mensagens

No Painel de Interfaces, a seção Interfaces de Roteador mostra cada Roteador com os destinos, as chamadas de hoje e as mensagens geradas; o clique no Roteador abre o monitor do Roteador. Em Mensagens, o combo Roteador filtra as mensagens geradas — é ele que vem preenchido em Ver as mensagens geradas.

Avisos

Na aba Geral, escolha em quais situações avisar (sem destino, fora do contrato, parcial, erro) e quem recebe — só usuários que enxergam Roteadores. O e-mail sai na passagem para a situação, não a cada chamada, e um aviso de normalização chega quando uma chamada volta a sair inteira. Chamadas de teste não avisam.

Web Service, Postman e portabilidade

• SOAP — com Publicar também como Web Service, o Roteador responde em /api/ws/router/{sigla} (WSDL com ?wsdl), operação EnviarAoRoteador. Com WS-Security, a chave vai no UsernameToken do header — a senha como API Key, ou login e senha de uma Credencial do grupo Roteadores.
• Postman — baixa uma collection com um request por Roteador, com o corpo montado do contrato. A API Key vai em branco.
• Exportar / Importar — o Roteador sai como um arquivo JSON que não carrega ids: as Entregas vão como INTERFACE/ENTREGA e os Transformadores pelo nome. Importado noutro ambiente, se faltar alguma referência nada é criado e a lista do que falta aparece. API Keys e Credenciais não vão junto. No Importar / Exportar da instalação, Roteadores é um grupo próprio. Na importação, o arquivo pode ser arrastado para o popup; aceita .json de até 1 MB (e até 500 nós), e só é enviado ao clicar em Importar.

Pelo Servidor MCP de configuração, cms_list_routers, cms_get_router, cms_simulate_router e cms_list_router_executions leem; cms_create_router cria a partir do mesmo documento da exportação, e o Roteador nasce desativado.

Como tool MCP

Um Roteador também pode ser chamado por um agente de IA. Marque Expor como tool MCP na aba Geral: a aba Tool MCP abre, com o nome da tool, as chamadas por minuto e a descrição que o modelo lê para decidir quando chamá-la — os três obrigatórios.

Todos os Roteadores expostos ficam num servidor só:

POST /api/mcp/routers/server

O agente se conecta com uma API Key ou Credencial do grupo Roteadores e vê só as tools dos Roteadores que essa chave pode chamar; a chamada de cada tool confere a chave de novo contra aquele Roteador. Com contrato, cada campo vira um argumento da tool; sem contrato, a tool recebe o payload inteiro em payload. A resposta traz o idExecucao e as rotas — a entrega em si é assíncrona, e a tool fixa cms_router_execution_status mostra a situação das execuções que a própria chave disparou. A execução fica registrada com a origem MCP e a credencial que chamou.

O nome da tool é único entre os Roteadores, e a exportação leva nome, descrição e limite, mas nunca o “ligado”: um Roteador importado nasce com a tool desligada. O servidor aparece em Servidores MCP como mais um bloco, e obedece à mesma chave de Configurações › IA do servidor de Aplicação.

Regras que valem para todo Roteador

• A sigla faz parte da URL. Depois da primeira chamada ela trava, para não quebrar quem já usa.
• Montar uma rota para a Entrega de uma Aplicação exige enxergar essa Aplicação. Rotas para Aplicações que você não enxerga aparecem mascaradas e não podem ser removidas por você.
• Uma Entrega com rota de Roteador mostra Recebe de no cadastro dela, e não pode ser excluída enquanto o Roteador a usar — nem o Transformador de uma rota. Um Roteador usado por Coleta também não pode ser excluído.
• No Recebe de da Entrega, o clique no Roteador mostra ali mesmo o contrato de entrada dele (o próprio, ou o herdado de outra Entrega), o Content-Type e o Transformador da rota que chega à Entrega — sem precisar abrir o Roteador. O ícone JSON copia um corpo de exemplo com os campos do contrato, e Abrir Roteadores abre o Roteador numa nova aba, sem fechar a Entrega.

Permissão

A Ferramenta é /routers, em Config. de Integração, logo abaixo de Gatilhos. Ela também libera o grupo Roteadores nas telas de API Keys e Credenciais.