Mapa de dependências entre APIs: checklist técnico para integrar sistemas sem quebrar a produção

Um mapa de dependências entre APIs mostra como dados, autenticação e chamadas transitam entre sistemas. Ele registra quem consome cada serviço, qual endpoint é utilizado, que resposta é esperada e o que acontece quando uma etapa falha. Sem essa visão, uma integração pode parecer simples no diagrama e esconder riscos significativos em produção.

Considere um fluxo de e-commerce que recebe um pedido, consulta estoque, calcula frete, autoriza o pagamento e envia dados para o sistema de gestão. Uma indisponibilidade de poucos segundos no serviço de estoque pode gerar pedidos duplicados, carrinhos abandonados ou divergências entre o pedido pago e o pedido separado.

O primeiro ganho do mapa é transformar dependências implícitas em decisões verificáveis. Em vez de depender da memória de uma pessoa desenvolvedora, a equipe passa a consultar uma relação documentada de sistemas, endpoints, versões, responsáveis, limites e procedimentos de recuperação.

Esse trabalho complementa um checklist de preparação de APIs, mas tem uma finalidade mais ampla. O guia sobre como preparar APIs e sistemas para integrações automatizadas ajuda a verificar a condição de cada sistema; o mapa conecta essas condições em uma visão operacional única.

Para começar, não desenhe apenas caixas com nomes de aplicações. Registre também as relações entre elas, a direção do fluxo, a frequência das chamadas, o tipo de dado transportado, a criticidade do processo e o impacto de uma resposta lenta ou incompleta. Essa granularidade é o que permite testar a integração antes de expor clientes e operações ao risco.

A Trait utiliza um Score de Prontidão de Integração para transformar a análise do mapa em uma decisão objetiva. O método não substitui avaliação técnica, mas ajuda a separar uma integração pronta para um teste controlado de outra que ainda depende de informações básicas ou de correções estruturais.

A fórmula é simples: atribua de 0 a 2 pontos para cada dimensão e calcule o total dividido por 10, multiplicado por 100. As cinco dimensões são contrato, autenticação, níveis de serviço, testes e rollback. Zero significa ausência ou desconhecimento; um indica condição parcial; dois representa evidência documentada e validada.

Um contrato com exemplos de sucesso, erro e campos obrigatórios recebe dois pontos. Se existe apenas uma descrição informal, recebe um. Se a equipe não sabe qual formato a API espera, recebe zero. O mesmo raciocínio vale para autenticação: uma credencial segura, com escopo mínimo e rotação testada, é diferente de uma chave compartilhada em uma planilha.

A leitura sugerida é: de 0 a 49%, não avance para produção; de 50 a 79%, faça uma prova controlada e feche as lacunas; de 80 a 100%, a integração pode seguir para uma liberação gradual, desde que os riscos críticos tenham responsáveis. Uma única dimensão com zero em autenticação ou rollback deve bloquear a mudança, mesmo que a média seja alta.

O score também cria uma conversa útil entre TI, operação e negócio. Se o fluxo é financeiramente crítico, talvez seja necessário exigir pontuação máxima em testes e rollback. Para um fluxo interno de baixa consequência, o time pode aceitar uma condição parcial, desde que registre a decisão e o prazo para melhorar a cobertura.

A compatibilidade de uma API não depende apenas de o endpoint continuar respondendo com HTTP 200. Uma alteração pode manter o código de sucesso e, ainda assim, mudar o significado de um campo, retirar uma propriedade opcional ou alterar arredondamentos que afetam faturamento.

Monte uma matriz com consumidor, provedor, versão atual, versão pretendida, campos utilizados e risco de mudança. Para cada combinação, mantenha uma coleção de requisições no Postman ou ferramenta equivalente, com variáveis de ambiente separadas e dados de teste que não contenham informações pessoais ou financeiras reais.

Os testes devem cobrir o caminho feliz, autenticação inválida, limite excedido, resposta lenta, campo ausente, paginação, duplicidade e indisponibilidade. Também teste o comportamento da aplicação consumidora, não apenas se o provedor devolve a resposta esperada.

Uma prática eficiente é usar uma especificação OpenAPI como contrato compartilhado e executar testes de contrato no processo de entrega. A especificação oficial OpenAPI descreve uma forma padronizada de documentar endpoints, parâmetros, respostas e autenticação, facilitando a detecção de mudanças incompatíveis.

Para fluxos orquestrados, crie mocks no n8n ou em um serviço de simulação com respostas controladas. Um mock de pagamento pode devolver aprovação, recusa, atraso e erro de limite; um mock de estoque pode simular produto indisponível ou resposta incompleta. Assim, a equipe testa as decisões da automação sem pressionar o ambiente do fornecedor.

Antes da publicação, faça uma execução paralela ou canário com uma pequena parcela das transações. Compare quantidade de chamadas, taxa de erro, tempo de resposta, registros criados e divergências de dados. Só amplie o tráfego quando os critérios de sucesso estiverem definidos e alguém tiver autoridade para interromper a mudança.

Em um projeto acompanhado pela Trait, uma operação de e-commerce precisava conectar loja virtual, estoque, pagamento, transportadora e sistema de gestão antes de uma campanha de alto volume. O fluxo já funcionava em condições normais, mas não havia clareza sobre limites, retentativas ou o que ocorreria quando o provedor de estoque demorasse a responder.

O mapa revelou duas dependências críticas. A primeira era uma chamada síncrona que mantinha o pedido aberto enquanto aguardava o estoque; a segunda era uma retentativa sem chave de idempotência, capaz de repetir a criação de uma solicitação quando a resposta se perdesse no caminho.

A equipe separou a confirmação do pedido do envio de eventos não críticos, colocou timeout explícito, criou uma fila para reconciliação e simulou respostas lentas com mocks. Também definiu um painel com taxa de erro por provedor, idade da fila, pedidos pendentes e divergências entre pagamento e gestão.

Durante o pico, uma API externa apresentou lentidão. O circuito interrompeu chamadas além do limite configurado, a fila preservou os eventos e o procedimento de reprocessamento foi executado após a normalização. O resultado prático foi evitar uma interrupção ampla e dar à operação visibilidade sobre o que estava pendente, em vez de obrigar a equipe a conferir pedidos manualmente.

O caso mostra por que o mapa não é apenas documentação de arquitetura. Ele orienta escolhas de desenho, cria testes reproduzíveis e dá à operação um caminho seguro para agir quando o comportamento real se afasta do cenário ideal. Para avaliar também alarmes e sinais técnicos, consulte o checklist de observabilidade antes de automatizar.