API pública

Todas las rutas de abajo están bajo el prefijo /api.

Autenticación

Los endpoints públicos (recepción y recolección) aceptan el API Token de la aplicación en tres formatos equivalentes:

x-api-token: <token>
Authorization: Bearer <token>
Authorization: Basic <base64(cualquiera:token)>

En el Basic, el login y la contraseña de una Credencial de Entrada de la Aplicación también valen: el CMS prueba la contraseña como token y, si no lo es, verifica el par como Credencial.

Los endpoints administrativos usan JWT de usuario (Authorization: Bearer <jwt>), obtenido en POST /auth/login.

Recepción de mensaje (Entrega)

POST /api/{siglaFila}/{siglaMensagem}

Catch-all de dos segmentos. Por eso las rutas administrativas que podrían colisionar usan tres segmentos (/collectors/sap/..., /definitions/sap/...).

Recepción de recolección

POST /api/collect/{siglaFila}/{siglaColeta}

Endpoint público equivalente al de entrega, para que un productor externo accione una Recolección informando sus Parámetros de Entrada: la búsqueda en el origen corre al instante, y el reenvío a los destinos en el próximo ciclo de la cola. Tres segmentos, justamente para no colisionar con el catch-all anterior. Solo existe para una Recolección con al menos un Parámetro de Entrada — sin eso, 404.

La respuesta trae un id_message por mensaje generado: una Recolección SQL que trajo cinco filas devuelve un array con cinco. Si la Recolección tiene Devolver el resultado de la recolección en la respuesta de la API activado, la respuesta trae también collected_payload, con lo que devolvió la búsqueda — ver Registros.

La respuesta de una Recolección viene con message_type: "SYNC": la búsqueda en el origen ya corrió dentro de la llamada. El return_message dice lo que pasó — Data collected successfully, o Data collected; forwarding to destinations queued cuando el resultado solo sigue a los destinos. ASYNC queda para el caso de la Aplicación de origen fuera de línea, en que la búsqueda se posterga.

Documentar la integración para quien la va a consumir

Dos exportaciones describen, en un archivo, todo lo que una Aplicación recibe y envía. Sirven para entregar al equipo del otro lado sin escribir documentación a mano.

Los dos exigen JWT y la Herramienta /definitions — el archivo describe las Definiciones, y es quien las cuida el que lo entrega. La colección Postman también sale por el ícono naranja en la pantalla de Aplicaciones.

La URL base de ambos se resuelve a partir de la dirección por la que llegó la solicitud (respetando X-Forwarded-Host/X-Forwarded-Proto), así que el archivo ya sale apuntando a una dirección alcanzable desde afuera — el mismo tratamiento que recibe el WSDL.

SOAP

GET  /api/ws/{siglaFila}/{siglaMensagem}?wsdl
POST /api/ws/{siglaFila}/{siglaMensagem}

WSDL generado dinámicamente a partir de la Definición. Autenticación por header o WS-Security UsernameToken.

La API de Recolección tiene su equivalente SOAP, para la Recolección con Activar WebService (WSDL) activado:

GET  /api/ws/collect/{siglaFila}/{siglaColeta}?wsdl
POST /api/ws/collect/{siglaFila}/{siglaColeta}

La operación es ExecutarColeta, con un elemento por Parámetro de Entrada dentro de <parametros>. El token va en el elemento apiToken del cuerpo, o en el wsse:UsernameToken con WS-Security — que aquí acepta también el login y la contraseña de una Credencial de Entrada. Detalles en Registros.

Autenticación de usuario y 2FA

Los dos últimos están bajo /auth, y no bajo /users, a propósito: todo usuario conectado tiene que ver y ajustar lo que es suyo, incluso sin la Herramienta Usuarios en el perfil.

Endpoint de configuración por IA

POST /api/mcp es el servidor MCP del CMS: JSON-RPC 2.0 sobre HTTP, sin sesión — cada petición es completa en sí misma. Se autentica con un token propio, creado en /mcp-tokens:

Authorization: Bearer cms_mcp_...

Endpoint de integraciones por IA

POST /api/mcp/applications/{sigla} es el servidor MCP de integraciones de una Aplicación: también JSON-RPC 2.0 sobre HTTP, lista como tools las Entregas y Recolecciones de esa Aplicación marcadas con Exponer como tool MCP, y las ejecuta por el mismo camino de la recepción de mensajes. Se autentica con API Key, con Credencial de Entrada (Basic) o con token MCP de usuario con la Herramienta /mcp/integration-tools.

No confundas los tres canales:

Una API Key no autentica en /api/mcp, y un token MCP no envía mensajes por el endpoint de recepción — solo por las tools que alguien marcó, y con la Herramienta propia en el Perfil. La separación es deliberada: son niveles de riesgo distintos y se conceden por separado.

Endpoints internos

No son expuestos por el nginx — solo existen dentro de la red del compose: