Integrações externas sem vazar provider para o centro do sistema

O problema

Toda integração externa começa parecendo simples.

Você recebe:

• um SDK
• um endpoint
• uma documentação mais ou menos

e liga isso no fluxo principal.

Meses depois, o centro do sistema já sabe:

• nome de campo do provider
• código de erro do provider
• jeito específico de paginação do provider
• semântica estranha do callback do provider

Nesse momento, a integração deixou de ser detalhe.

Ela virou linguagem interna do sistema.

Modelo mental

O provider é uma borda.

Seu sistema precisa conversar com ele, mas não precisa pensar como ele.

Uma boa integração normalmente tem três partes:

• contrato interno: o que o sistema realmente quer fazer
• adapter/gateway: como isso conversa com o provider
• mapeamento de erro e resposta: como traduzir a semântica externa para a interna

Essa tradução perto da borda é o que protege o centro do sistema.

O que costuma vazar sem perceber

O vazamento mais comum não é só import de SDK.

É semântica.

Por exemplo:

• regra central tratando provider_status = pending_review
• use case conhecendo retryable_error_code = 391
• domínio inteiro falando em checkout_session_id quando isso só existe em um fornecedor

Isso torna o sistema refém não só da implementação.

Torna o sistema refém do vocabulário externo.

Exemplo simples

Imagine uma cobrança por cartão.

O sistema quer saber algo simples:

• cobrança aprovada
• cobrança recusada
• cobrança pendente

O provider, porém, pode ter:

• authorized
• captured
• requires_action
• pending_review
• manual_hold

Se essa taxonomia vaza inteira para a regra central, o seu fluxo começa a responder ao provider em vez de responder ao negócio.

Mais saudável é mapear perto da borda:

• authorized e captured viram estados internos claros
• requires_action vira uma semântica interna de pendência
• manual_hold vira decisão de risco ou espera, conforme a regra local

O centro do sistema continua falando a própria língua.

Isolar não é fingir abstração genial

Também existe exagero.

Tem time que cria:

• interface
• adapter
• facade
• proxy
• wrapper
• service

para uma integração minúscula que nunca vai trocar.

Isso pode ser ruído.

O ponto não é “abstrair porque sim”.

O ponto é concentrar dependência onde a mudança futura machuca menos.

Como decidir a profundidade certa

Vale isolar mais quando:

• o provider é crítico
• o contrato externo muda bastante
• existe chance real de trocar fornecedor
• múltiplos fluxos dependem da mesma integração
• erro e retry exigem cuidado

Vale simplificar quando:

• o uso é pequeno
• o acoplamento está local
• o custo de abstração superaria o risco real

Pragmatismo aqui é bom.

Mas pragmatismo não é deixar o provider contaminar tudo.

Onde a tradução costuma morar

Em geral, faz sentido que fiquem perto da borda:

• formatação de request
• parsing de response
• mapeamento de erro
• adaptação de webhook
• detalhes de autenticação e paginação

O use case deveria enxergar uma intenção mais limpa:

• cobrar
• cancelar
• consultar status
• sincronizar

Não o mapa inteiro de idiossincrasias do fornecedor.

Como um senior pensa

Quem decide melhor costuma perguntar:

• o que o sistema realmente quer fazer?
• qual parte é semântica de negócio e qual parte é semântica do provider?
• se amanhã esse fornecedor mudar, a dor está concentrada ou espalhada?
• estou isolando dependência real ou só desenhando arquitetura para parecer madura?

Essa é a diferença entre abstração útil e teatro.

Ângulo de entrevista

Esse tema aparece em system design, integração com terceiros e backend architecture.

O entrevistador quer ver se você sabe:

• proteger o núcleo do sistema
• traduzir erro e contrato com clareza
• evitar acoplamento cedo demais
• falar de adapter/gateway com critério, não por buzzword

Resposta forte parece algo como:

“Eu deixaria o contrato do provider perto da borda e mapearia isso para uma semântica interna menor e mais estável. Assim o núcleo do sistema decide negócio sem conhecer payload, código de erro ou vocabulário específico do fornecedor.”

Takeaway direto

Integração externa saudável não é a que desaparece.

É a que fica contida onde deveria ficar.