/v1. Toda rota de negócio exige um bearer token.
Superfície da API
Endpoints de operador ficam fora de
/v1.
Autenticação e tenancy
Toda rota
/v1 recebe um bearer token OAuth2 do Lerian Access Manager. Defina PLUGIN_AUTH_ENABLED=true e PLUGIN_AUTH_HOST para ativar o gate. A produção exige ambos.
Cada instituição mantém seu próprio schema de banco de dados. O serviço lê a identidade da instituição a partir do token validado, nunca de um corpo de requisição, de um header ou de um parâmetro de rota.
Idempotência
O Lerian CCS aceita um header
Idempotency-Key. O header é obrigatório em POST /v1/batches e opcional na rota de cancelamento. Um middleware armazena em cache a primeira resposta e a repete para uma repetição da mesma chave. As chaves pertencem a uma instituição, e a retenção padrão é de 7 dias.
Erros
Todo corpo de erro é um documento de problema RFC 9457, com o tipo de mídia
application/problem+json. Cada corpo carrega um código de produto. Os valores de código são um contrato congelado, então um cliente compara pelo código, não pelo texto da mensagem.
Uma rota cujos colaboradores falharam ao ser conectados responde 501.
Eventos
O Lerian CCS publica um evento de negócio em seu próprio tópico, com um tópico dead-letter correspondente. O tópico e o tipo de evento seguem a regra de nomenclatura do Streaming Hub, com a fonte CloudEvents deste serviço como namespace.
Ele carrega a postura de entrega crítica. O serviço o grava no outbox transacional, na mesma transação da mudança de estado. O streaming vem desativado por padrão. Enquanto estiver desativado, o serviço conecta um emissor no-operation e não publica nada. O Lerian Streaming Hub é a camada de entrega.
O Lerian CCS também publica notificações no exchange definido por
RABBITMQ_EXCHANGE.
Os documentos nesses payloads são mascarados.
Convenções de integração
- Headers.
CORS_ALLOWED_HEADERSnão tem valor padrão. Enquanto permanecer sem definição, uma resposta de preflight ecoa os headers que o navegador pediu. Um valor que você define substitui esse comportamento por uma lista fixa, então informe cada header que seu cliente de navegador envia. - Paginação. Cada rota de listagem limita seu próprio tamanho de página. Um
limitde 100 ou menos fica dentro do limite de cada rota. - Rate limits. O limitador cobre apenas
/v1. Rotas de exportação e de dispatch têm níveis mais restritos. - Referências de arquivo. O XML regulatório permanece no armazenamento de objetos. Apenas referências de arquivo trafegam pela rede.