API pública

Todos os caminhos abaixo ficam sob o prefixo /api.

Autenticação

Endpoints públicos (recebimento e coleta) aceitam o API Token da aplicação em três formatos equivalentes:

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

No Basic, o login e a senha de uma Credencial de Entrada da Aplicação também valem: o CMS tenta a senha como token e, se não for, confere o par como Credencial.

Endpoints administrativos usam JWT de usuário (Authorization: Bearer <jwt>), obtido em POST /auth/login.

Recebimento de mensagem (Entrega)

POST /api/{siglaFila}/{siglaMensagem}

Catch-all de dois segmentos. Por isso rotas administrativas que poderiam colidir usam três segmentos (/collectors/sap/..., /definitions/sap/...).

Recebimento de coleta

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

Endpoint público equivalente ao de entrega, para um produtor externo acionar uma Coleta informando os Parâmetros de Entrada dela: a busca na origem roda na hora, e o encaminhamento aos destinos no próximo ciclo da fila. Três segmentos justamente para não colidir com o catch-all acima. Só existe para Coleta com ao menos um Parâmetro de Entrada — sem isso, 404.

A resposta traz um id_message por mensagem gerada: uma Coleta SQL que trouxe cinco linhas devolve um array com cinco. Se a Coleta tiver Devolver o resultado da coleta na resposta da API ligado, a resposta traz também collected_payload, com o que a busca trouxe — ver Cadastros.

A resposta de uma Coleta vem com message_type: "SYNC": a busca na origem já rodou dentro da chamada. O return_message diz o que aconteceu — Data collected successfully, ou Data collected; forwarding to destinations queued quando o resultado segue só para os destinos. ASYNC fica para o caso da Aplicação de origem fora do ar, em que a busca é adiada.

Documentar a integração para quem vai consumir

Duas exportações descrevem, num arquivo, tudo que uma Aplicação recebe e envia. Servem para entregar ao time do outro lado sem escrever documentação à mão.

Os dois exigem JWT e a Ferramenta /definitions — o arquivo descreve as Definições, e é quem cuida delas que o entrega. A coleção Postman também sai pelo ícone laranja na tela de Aplicações.

A URL base de ambos é resolvida a partir do endereço por onde a requisição chegou (respeitando X-Forwarded-Host/X-Forwarded-Proto), então o arquivo já sai apontando para um endereço alcançável de fora — mesmo tratamento que o WSDL recebe.

SOAP

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

WSDL gerado dinamicamente a partir da Definição. Autenticação por header ou WS-Security UsernameToken.

A API de Coleta tem o seu equivalente SOAP, para a Coleta com Ativar WebService (WSDL) ligado:

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

A operação é ExecutarColeta, com um elemento por Parâmetro de Entrada dentro de <parametros>. O token vai no elemento apiToken do corpo, ou no wsse:UsernameToken com WS-Security — que aqui aceita também o login e a senha de uma Credencial de Entrada. Detalhes em Cadastros.

Autenticação de usuário e 2FA

Os dois últimos ficam sob /auth, e não sob /users, de propósito: todo usuário logado tem que enxergar e ajustar o que é dele, mesmo sem a Ferramenta Usuários no perfil.

Endpoint de configuração por IA

POST /api/mcp é o servidor MCP do CMS: JSON-RPC 2.0 sobre HTTP, sem sessão — cada requisição é completa em si. Ele autentica por um token próprio, criado em /mcp-tokens:

Authorization: Bearer cms_mcp_...

Endpoint de integrações por IA

POST /api/mcp/applications/{sigla} é o servidor MCP de integrações de uma Aplicação: também JSON-RPC 2.0 sobre HTTP, ele lista como ferramentas as Entregas e Coletas daquela Aplicação marcadas com Expor como ferramenta MCP, e as executa pelo mesmo caminho do recebimento de mensagem. Autentica por API Key, por Credencial de Entrada (Basic) ou por token MCP de usuário com a Ferramenta /mcp/integration-tools.

Não confunda os três canais:

Uma API Key não autentica no /api/mcp, e um token MCP não envia mensagem pelo endpoint de recebimento — só pelas ferramentas que alguém marcou, e com a Ferramenta própria no Perfil. A separação é proposital: são níveis de risco diferentes e ficam concedidos separadamente.

Endpoints internos

Não são expostos pelo nginx — só existem dentro da rede do compose: