Múltiplos consumidores, rastreabilidade e observabilidade¶
Hoje a mesma API atende vários canais e integrações, mas a gente ainda não consegue acompanhar uma jornada completa de ponta a ponta com confiança. Isso vira retrabalho, risco operacional e risco de segurança, principalmente agora que queremos abrir mais frentes como parceiros, BPO e agentes de IA.
Contexto em uma frase¶
A API atual nasceu como um braço do sistema em Windows Forms, não como um produto de integração. Com o tempo, ela foi sendo usada por mais públicos e agora ficou difícil responder perguntas simples do dia a dia, como quem chamou, de onde veio, o que foi executado e por que falhou.
Quem são os consumidores hoje¶
Hoje já temos, no mínimo:
- Portal do corretor
- Portal do cliente
- Superapp
- Agentes de IA
- Integração com a Madalozzo
- Processos de BPO planejados
O problema é que, no legado, esses públicos acabam caindo no mesmo conjunto de rotas e muitas vezes usam credenciais e padrões diferentes, sem “muros” claros entre eles.
O que esse problema é, em linguagem simples¶
Quando algo dá errado, ou quando precisamos provar o que aconteceu, a gente deveria conseguir olhar para uma única trilha e entender:
- qual canal iniciou a operação
- qual usuário ou conta estava por trás
- quais etapas aconteceram dentro do sistema
- onde demorou ou falhou
- quais dados foram afetados
Hoje isso não é confiável e nem rápido.
Como isso acontece hoje, com exemplos práticos¶
1) Não existe segregação real por público¶
A API atende vários públicos, não existe segregação real por público e um acesso de um contexto pode encostar em recursos de outro.
Isso faz com que uma chamada que deveria ser “do app” ou “do WhatsApp” acabe convivendo com rotas do portal, e isso aumenta a chance de erro de permissão e exposição indevida.
2) O Superapp usa um usuário global¶
Hoje o Superapp tem um usuário global de parceiro, ou seja, um acesso genérico que não representa a pessoa real do outro lado.
Na prática isso quebra rastreabilidade e também deixa o sistema mais frágil. Se todo mundo entra com a mesma “chave”, fica mais difícil provar quem fez o quê, e fica mais fácil um erro de permissão virar incidente.
3) Existem pontos em que a identidade chega por parâmetro e não por validação real¶
Em alguns trechos do legado, decisões importantes são direcionadas por parâmetros enviados na chamada, como COD_CORRETOR constantemente sendo utilizado para registrar a ação do corretor, o que é um risco.
4) Superfície pública e credenciais em URL aumentam o risco e bagunçam a operação¶
Temos muitos pontos críticos: emissão de acesso com fragilidades, HTTP permitido, e muitos endpoints sensíveis expostos de forma pública. Também há exemplos de credenciais ou tokens em query string, que podem parar em logs e históricos, aumentando risco e confundindo investigação.
5) Falta um fio condutor único para acompanhar uma operação¶
Na prática, hoje é comum olhar para logs e ver pedaços. Logging relacionado ao token está comentado,existem catch genéricos ou silenciosos em trechos relevantes. Isso dificulta fechar a história completa de um incidente.
Impactos no negócio¶
Tempo e retrabalho¶
Sem trilha consistente, qualquer erro vira investigação artesanal. Isso consome tempo de desenvolvimento, suporte e operações, e normalmente exige tentativas de reprodução no ambiente.
Risco operacional¶
Quando não dá para identificar com clareza o canal e o autor real, decisões acabam sendo tomadas com base em suposição. Isso aumenta chance de correção errada e reincidência do problema.
Risco de segurança¶
Quando a superfície exposta é grande e a autenticação é frágil, o risco deixa de ser teórico. O projeto já mapeou a necessidade de reduzir superfície pública e corrigir fragilidades de autenticação.
Experiência do corretor e do cliente¶
Para quem usa o sistema, o problema aparece como instabilidade, demora para resolver, falhas intermitentes e respostas inconsistentes entre canais. Em reunião, isso é o tipo de coisa que vira “o sistema está ruim”, mesmo quando o problema real é governança e trilha.
O que a API Nova muda para resolver ou reduzir isso, e por quê¶
1) Colocar um gateway como porta de entrada única¶
A ideia é transformar a entrada da API em um produto com regras claras, por público e por rota.
Além de roteamento, o gateway assume responsabilidades de borda, como gerar e propagar o identificador de correlação e registrar log mínimo de acesso.
2) Separar rotas por público, com políticas próprias¶
A matriz lista a segmentação por rotas como padrão, incluindo faixas específicas para cliente, corretor, superapp, WhatsApp, IA, parceiros e webhooks. Isso cria muros claros e reduz o risco de um público “encostar” em rotas de outro.
3) Tornar rastreabilidade obrigatória, não opcional¶
X-Correlation-Id deve ser obrigatório, com geração na borda quando estiver ausente. A ideia é que esse identificador apareça em logs, auditoria e também em respostas de erro.
Também podemos ter logs e auditoria em SQL Server com retenção de 60 dias, com tabelas dedicadas para auditoria de negócio e para erros.
4) Contrato e autorização por vínculo, para não confiar em parâmetro solto¶
Autenticação não é autorização e que antes de operar é obrigatório validar escopo e vínculo do recurso. Isso é essencial quando existem múltiplos consumidores, incluindo integrações externas.
5) Governança por consumidor para crescer com parceiros, BPO e integrações¶
Governança e auditoria por consumidor, com capacidade de bloquear rapidamente rotas e padrões de ataque sem depender de deploy do backend.
Também já foi mapeado que, com vários consumidores fortes, faz sentido criar muros claros agora, seja por rotas ou até por APIs por público.