Como desenhar integração com serviço terceiro

O problema

Serviço terceiro costuma entrar no sistema com uma promessa simples:

• cobrar pagamento
• validar documento
• mandar email
• enriquecer dado

No início parece só mais uma chamada HTTP.

Meses depois, o time descobre que metade do próprio fluxo agora fala a língua do fornecedor.

Quando isso acontece, qualquer mudança externa vira problema interno:

• campo mudou
• limite apertou
• latência piorou
• webhook atrasou
• status veio diferente

Refem não e só quem depende.

E quem depende sem fronteira clara.

Modelo mental

Integração com serviço terceiro deveria responder a esta pergunta:

como eu uso essa capacidade externa sem deixar meu sistema assumir a forma dela?

Isso leva para quatro ideias:

1. o contrato do fornecedor deve ficar contido
2. falha do fornecedor não pode contaminar tudo
3. seu dominio precisa continuar falando sua própria linguagem
4. troca ou mudança de fornecedor não deveria exigir reescrita geral

Quebrando o problema

Não espalhe o contrato do fornecedor

Erro clássico:

• response do terceiro entra
• nomes deles viram nomes seus
• status deles viram status de negócio seu
• payload deles atravessa várias camadas

Quando isso acontece, o sistema deixa de integrar e passa a incorporar o fornecedor.

Melhor desenho:

• uma camada interna conversa com o terceiro
• ela traduz o contrato externo para um modelo seu
• o resto do sistema depende do modelo interno

Isso parece burocracia só até a primeira mudança externa.

Trate o fornecedor como dependência instável

Mesmo fornecedor bom pode:

• ficar lento
• devolver erro parcial
• responder fora de ordem
• impor rate limit
• mudar comportamento

Entao integração madura costuma ter:

• timeout
• retry com critério
• circuit breaker
• idempotencia quando a operação e sensivel
• observabilidade de falha e latência

Não porque o fornecedor e ruim.

Porque dependência externa e, por natureza, menos controlavel.

Seu dominio precisa continuar seu

Se o fornecedor chama estados de pagamento de um jeito e seu negócio de outro, não copie sem pensar.

Exemplo:

• fornecedor: authorized, captured, voided
• seu negócio: aguardando_confirmacao, pago, cancelado

Essas coisas podem se relacionar, mas não precisam ser a mesma tabela mental.

Se você cola uma na outra cedo demais, a regra de negócio passa a obedecer sem querer a semântica de fora.

Fallback precisa ser honesto

Quando o terceiro falha, as opcoes comuns sao:

• degradar funcionalidade
• enfileirar para tentar depois
• mostrar erro claro
• usar cache onde fizer sentido

O importante e não inventar sucesso falso.

Exemplo ruim:

• fornecedor de pagamento caiu
• sistema marca como pago “para não travar UX”

Isso não e resiliencia.

E criação de problema adiado.

Exemplo simples

Imagine uma integração com provedor de frete.

Fluxo ruim:

1. frontend chama seu backend
2. backend chama o provedor
3. a resposta do provedor volta quase crua para dentro do seu dominio
4. vários módulos passam a depender dos nomes, erros e status dele

Se o provedor troca um campo ou atrasa forte, tudo sente.

Fluxo melhor:

1. seu backend chama um adaptador interno de frete
2. o adaptador conversa com o provedor
3. ele traduz response e erro para um modelo interno
4. seu sistema entende cotacao_disponivel, cotacao_indisponivel, reprocessar_depois

Agora o fornecedor continua importante.

Mas não dita a forma de todo o seu sistema.

Erros comuns

• Espalhar payload externo pelo sistema inteiro.
• Confiar em fornecedor como se fosse módulo interno seu.
• Não ter timeout e deixar request pendurada.
• Mapear estado de negócio diretamente para status do vendor.
• Tratar troca de fornecedor como impossivel porque o acoplamento já foi total.

Como um senior pensa

Quem tem mais experiência olha para serviço terceiro e pensa:

“Eu quero usar a capacidade dele, não terceirizar o desenho do meu dominio.”

Essa frase resume bem o objetivo.

Integração boa aceita dependência sem entregar a chave da casa.

O que o entrevistador quer ver

Em entrevista, esse tema costuma aparecer quando pedem desenho de integração externa.

O avaliador quer ver se você pensa em fronteira, risco e evolução.

Sinais bons:

• você fala de camada adaptadora
• menciona timeout, retry e circuit breaker
• separa semântica do fornecedor da semântica do negócio
• fala de observabilidade e fallback

Uma resposta forte costuma soar assim:

“Eu isolaria o contrato do terceiro atras de uma camada minha, com timeout, retry e tradução para modelo interno. Assim eu reduzo acoplamento e consigo lidar melhor com falha ou mudança do fornecedor.”

Integração saudavel usa terceiro como dependência. Integração ruim promove o terceiro a coautor do seu sistema.