Adapter Pattern: como impedir que uma API externa domine seu negócio.

Use um adapter quando o sistema depende de um contrato que não controla e precisa impedir que formatos, nomes e estados externos vazem para o núcleo do produto. O valor aumenta quando existem múltiplos provedores, mudanças frequentes ou testes que não podem depender da rede.

Em uma integração simples e estável, uma camada dedicada ainda pode ser útil, mas não precisa nascer como uma hierarquia genérica. A abstração deve acompanhar uma variação real.

Se a interface repete exatamente os campos de uma API externa, o acoplamento apenas ganhou outro arquivo. Defina entradas, saídas e erros na linguagem usada pela aplicação.

O adapter recebe esse contrato interno, constrói a requisição externa, interpreta a resposta e devolve um resultado que o domínio compreende. Detalhes como headers, serialização e códigos proprietários permanecem na borda.

A integração não termina na resposta síncrona. Eventos recebidos precisam validar assinatura, identificar duplicidade e traduzir estados externos antes de acionar casos de uso internos.

Erros também exigem uma taxonomia útil. Timeout, rejeição definitiva e indisponibilidade temporária pedem decisões diferentes; devolver apenas “falhou” empurra complexidade para quem consome o adapter.

Testes do domínio usam uma implementação controlada da interface e verificam regras sem acessar o provedor. Testes do adapter usam contratos representativos para comprovar payload, resposta, erro e webhook.

Para integrações críticas, testes de contrato e um ambiente de homologação ajudam a detectar divergências. Observabilidade deve identificar provedor, operação e categoria de falha sem registrar segredo ou dado sensível.

Revise a fronteira quando estes comportamentos aparecerem.