Enrutadores — /routers

Una Entrega recibe en POST /api/{interface}/{entrega} y entrega a un destino. Casi siempre es lo que se quiere. Cuando el mismo dato tiene que ir a varios destinos — a veces a todos, a veces solo a algunos, según el contenido —, el camino es un Enrutador.

El Enrutador es una API genérica, que no pertenece a ninguna Aplicación:

POST /api/router/{sigla}

Recibe el payload, revisa el contrato de entrada, recorre un flujo de decisiones y crea un mensaje en cada Entrega que el flujo alcanzó. No entrega nada por sí solo: destino, credencial, Transformador, cifrado, reintentos y Error de Negocio siguen siendo de la Entrega, que recibe el mensaje como si viniera de un productor externo.

La lista

Cada fila muestra la sigla y el nombre, la URL, los destinos — cuántas Entregas y sus Aplicaciones, cada una con el ícono y el badge del tipo de conexión, que abre los detalles de la conexión — y el tráfico de las últimas 24 horas. El ícono de robot junto a la sigla indica que el enrutador está expuesto como tool MCP.

El filtro de arriba es por las Aplicaciones de destino, y la búsqueda mira sigla, nombre, descripción, nombre de la tool o Aplicación de destino. La columna Activo enciende y apaga directo desde la lista; apagar pide confirmación, porque el enrutador deja de aceptar llamadas de inmediato (quien llame recibe 503) y las Recolecciones que reenvían a él dejan de distribuir.

El flujo

El flujo es un árbol que parte del Inicio (llegó el payload), con dos tipos de paso:

• Decisión — una condición sobre el payload, con reglas y grupos Y/O. Tiene un lado Si SÍ y un lado Si NO, y cada lado puede llevar a varios pasos.
• Entrega — el final del camino: una Entrega ya registrada en Gestión de Mensajes, elegida en tres combos — Aplicación, Interfaz y Entrega. Cuando la Aplicación tiene una sola Interfaz, ya viene elegida. Las Aplicaciones de Help Desk no aparecen: un ticket se abre por alerta, no por enrutador. En el enlace que llega a la Entrega se puede elegir un Transformador, que convierte el payload del Enrutador en lo que esa Entrega espera (antes del Transformador de la propia Entrega). En la lista, el Transformador queda en la misma línea de la Entrega, después de ella.

Las dos formas clásicas de distribuir son solo formatos del mismo flujo:

La pestaña Flujo edita como lista con sangría; el botón Diagrama muestra el mismo flujo dibujado, de izquierda a derecha. Los errores (ciclo, decisión sin condición, paso suelto) aparecen mientras se arma e impiden guardar; los avisos (decisión sin salida, la misma Entrega por dos Transformadores distintos) solo alertan.

En el Diagrama, cada caja de Entrega muestra la Entrega, la Aplicación con su tipo de conexión, la Interfaz y, en violeta, el Transformador de la ruta cuando lo hay. La caja de Decisión muestra el nombre y cuántas reglas tiene.

El contrato de entrada

En la pestaña Contrato:

• Definir aquí — los campos de primer nivel del JSON recibido, con Obligatorio (un toggle) y valor por defecto. El botón Sugerir del tráfico muestra los campos que llegaron en las últimas 50 llamadas.
• Heredar de una Entrega — usa el Payload de Entrada de una Entrega existente, leído en cada llamada: cambiar su contrato cambia el del Enrutador. La Entrega se elige en los mismos tres combos del flujo.

Los campos del contrato también están disponibles en las decisiones como input.<campo>.

El valor por defecto vale cuando el campo no viene en el payload, y acepta Variables Globales con el botón {} — {{TURNO_DEFECTO}}, por ejemplo, resuelta en cada llamada. Solo las Globales: el enrutador no pertenece a ninguna Aplicación.

El Tamaño máximo en 0 (o vacío) usa el límite global de Configuración; un valor propio solo puede ser menor.

Qué hacer cuando el payload no cumple el contrato es una elección del Enrutador:

Quién puede llamar

El Enrutador acepta las mismas formas de autenticación que la Entrega — x-api-token, Authorization: Bearer o Basic —, pero con claves del grupo Enrutadores, creadas en API Keys y Credenciales. Una clave de Aplicación no autentica en un Enrutador, y una clave de Enrutador no autentica en una Interfaz. La pestaña Acceso lista quién puede llamar a ese Enrutador y, debajo, Cómo llamar a este Enrutador: la URL POST /api/router/{sigla}, un cURL con API Key (x-api-token) y uno con Credencial (Basic), los dos con el JSON del contrato en el cuerpo, y el formato de la respuesta, descrito a continuación. Cada bloque tiene el botón de copiar.

La respuesta es siempre inmediata: el Enrutador decide las rutas al llegar y crea los mensajes enseguida.

{
  "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"]
}

Es el mismo formato de la respuesta de una Entrega. id_message es el id de la ejecución del Enrutador — los mensajes de cada ruta se crean enseguida, uno por Entrega. Buscado en Ctrl+K o abierto en /messages/{id}, lleva a los mensajes que esa ejecución generó. routes lista las Entregas elegidas. return_message dice qué pasó:

Una Recolección también puede mandar lo que recolectó a un Enrutador: en el reenvío de la Recolección, elija el destino Enrutador en lugar de Entrega. La condición y el Transformador del reenvío siguen valiendo antes del Enrutador. Como no hay quien reciba un 400, “Rechazar” pasa a “Registrar” para este origen. Un Disparador también puede tener un Enrutador como destino, con agenda y valores fijos.

Simular y probar

La pestaña Simular muestra el camino que un payload haría ahora, con el flujo guardado: las decisiones con el valor leído en cada regla, las Entregas que recibirían y el diagrama con el camino resaltado. No se graba ni se envía nada.

Con contrato, la caja ya abre con el JSON de los campos para completar, y la línea de arriba lista los obligatorios. Un campo con valor por defecto fijo viene completo; uno con Variable Global viene vacío — vacío cuenta como ausente, y el servidor aplica el valor resuelto. Modelo del contrato vuelve la caja a ese JSON, y Usar la última llamada trae el payload real más reciente.

Ejecutar como prueba envía de verdad, por el mismo camino de una llamada externa, con los mensajes marcados como prueba — como en el Banco de Pruebas, y por eso exige esa herramienta.

Ejecuciones

Cada llamada se vuelve una ejecución, con el origen (API, Recolección, Disparador — con su nombre —, prueba o MCP), el camino recorrido, los mensajes generados y el payload — este solo para quien ve todas las Aplicaciones a las que fue.

Cada mensaje generado aparece con la Aplicación (ícono y badge de conexión), la Interfaz, la Entrega y la situación del mensaje. Al final de la fila, la flecha abre el mensaje completo en una ventana nueva, sin cerrar el enrutador, y el ícono de mensaje — en el color de la situación — abre el resumen, el mismo popup de Mensajes.

La situación de la ejecución es la del enrutamiento:

El desenlace de cada entrega es el del propio mensaje — ábralo para verlo. En la lista de Mensajes, el mensaje generado por un Enrutador lleva su marca, y Ver los mensajes generados abre la lista ya filtrada.

• Reprocesar las rutas con falla reintenta solo lo que falló; quien ya recibió no recibe de nuevo.
• Enrutar de nuevo pasa el mismo payload por el flujo actual, en una ejecución nueva que apunta a la original y registra quién la pidió. Las Entregas que ya recibieron pueden recibir de nuevo — por eso pide confirmación.

En el Panel y en Mensajes

En el Panel de Interfaces, la sección Interfaces de Enrutador muestra cada Enrutador con sus destinos, las llamadas de hoy y los mensajes generados; el clic en el Enrutador abre el monitor del Enrutador. En Mensajes, el combo Enrutador filtra los mensajes generados — es el que viene completo en Ver los mensajes generados.

Avisos

En la pestaña General, elija en qué situaciones avisar (sin destino, fuera del contrato, parcial, error) y quién recibe — solo usuarios que ven Enrutadores. El correo sale en la transición a la situación, no en cada llamada, y llega un aviso de normalización cuando una llamada vuelve a salir completa. Las llamadas de prueba no avisan.

Web Service, Postman y portabilidad

• SOAP — con Publicar también como Web Service, el Enrutador responde en /api/ws/router/{sigla} (WSDL con ?wsdl), operación EnviarAoRoteador. Con WS-Security, la clave va en el UsernameToken del encabezado — la contraseña como API Key, o login y contraseña de una Credencial del grupo Enrutadores.
• Postman — descarga una colección con un request por Enrutador, con el cuerpo armado a partir del contrato. La API Key va en blanco.
• Exportar / Importar — el Enrutador sale como un archivo JSON que no lleva ids: las Entregas van como INTERFAZ/ENTREGA y los Transformadores por nombre. Importado en otro ambiente, si falta alguna referencia no se crea nada y aparece la lista de lo que falta. Las API Keys y Credenciales no van juntas. En el Importar / Exportar de la instalación, Enrutadores es un grupo propio. En la importación, el archivo se puede arrastrar al popup; acepta .json de hasta 1 MB (y hasta 500 nodos), y solo se envía al hacer clic en Importar.

Por el Servidor MCP de configuración, cms_list_routers, cms_get_router, cms_simulate_router y cms_list_router_executions leen; cms_create_router crea a partir del mismo documento de la exportación, y el Enrutador nace desactivado.

Como tool MCP

Un enrutador también puede ser llamado por un agente de IA. Marque Exponer como tool MCP en la pestaña General: se abre la pestaña Tool MCP, con el nombre de la tool, las llamadas por minuto y la descripción que el modelo lee para decidir cuándo llamarla — las tres obligatorias.

Todos los enrutadores expuestos quedan en un solo servidor:

POST /api/mcp/routers/server

El agente se conecta con una API Key o Credencial del grupo Enrutadores y solo ve las tools de los enrutadores que esa clave puede llamar; cada llamada de tool vuelve a verificar la clave contra ese enrutador. Con contrato, cada campo se vuelve un argumento de la tool; sin contrato, la tool recibe el payload entero en payload. La respuesta trae idExecucao y las rutas — la entrega en sí es asíncrona, y la tool fija cms_router_execution_status muestra la situación de las ejecuciones que la propia clave disparó. La ejecución queda registrada con origen MCP y la credencial que llamó.

El nombre de la tool es único entre los enrutadores, y la exportación lleva nombre, descripción y límite, pero nunca el “encendido”: un enrutador importado nace con la tool apagada. El servidor aparece en Servidores MCP como un bloque más, y obedece la misma llave de Configuración › IA que el servidor de Aplicación.

Reglas que valen para todo Enrutador

• La sigla forma parte de la URL. Después de la primera llamada se bloquea, para no romper a quien ya la usa.
• Armar una ruta hacia la Entrega de una Aplicación exige ver esa Aplicación. Las rutas hacia Aplicaciones que usted no ve aparecen enmascaradas y no puede eliminarlas.
• Una Entrega con ruta de Enrutador muestra Recibe de en su registro, y no se puede eliminar mientras el Enrutador la use — tampoco el Transformador de una ruta. Un Enrutador usado por una Recolección tampoco se puede eliminar.
• En el Recibe de de la Entrega, el clic en el Enrutador muestra ahí mismo su contrato de entrada (el propio, o el heredado de otra Entrega), el Content-Type y el Transformador de la ruta que llega a la Entrega — sin abrir el Enrutador. El ícono JSON copia un cuerpo de ejemplo con los campos del contrato, y Abrir Enrutadores abre el Enrutador en una nueva pestaña, sin cerrar la Entrega.

Permiso

La herramienta es /routers, en Config. de Integración, justo debajo de Disparadores. También habilita el grupo Enrutadores en las pantallas de API Keys y Credenciales.