Erros que cometi ao implementar uma integração 😐
Em 2024 eu tive que encarar um baita desafio como desenvolvedor júnior, que foi a implementação de uma integração de um serviço externo de um parceiro, com o sistema que atualmente dou manutenção. Foi beem complicado, o prazo parecia curto, a API do parceiro usava uma tecnologia que eu não conhecia, e tudo isso me gerou muito estresse, mas muito aprendizado também. No final, consegui entregar a integração, mas com muito trabalho e estresse envolvido.
Não acredito que tenha acertado em todos os pontos durante a minha implementação, então não me sinto tão seguro para falar dos acertos ao implementar uma integração, mas me sinto bem seguro para apontar os erros que cometi neste processo ao implementar uma integração com um serviço externo, foi por isso que escrevi esse post.
Demorar muito para estudar, desenhar e documentar a solução técnica
Assim que recebi a tarefa, pensei: "Não vou perder tempo, preciso descobrir logo como integrar o serviço à aplicação." Sem muita cerimônia, abri a documentação do parceiro (mas não li muita coisa) e fui direto para os endpoints. Foi então que descobri que se tratava de um Web Service SOAP — o que me deixou em choque. Passei um bom tempo tentando entender como utilizar o tal WSDL na aplicação.
Enquanto fazia isso, não me preocupei com as regras do serviço, nem com as regras da aplicação na qual estava trabalhando, tampouco com a forma como essas aplicações interagiriam. Não refleti sobre onde essa integração deveria ser implementada e foquei apenas em como implementá-la.
Depois de muita dor de cabeça tentando me comunicar com o serviço externo, finalmente consegui. Mas foi aí que percebi que havia implementado no local errado.
Nesse momento, decidi parar e estudar as duas soluções. Com a ajuda de colegas, comecei a desenhar como essa integração deveria ser feita. Depois desse passo, tudo ficou mais claro e, em vez de apenas sair codando sem direção, finalmente tive um caminho estruturado a seguir.
Não pensar em partes (Não dividir as coisas em problemas menores)
Uma coisa que me apavora é não saber o que fazer e me sentir perdido. Durante o desenvolvimento dessa integração, percebi que parte desse problema ocorre justamente por não pensar em estratégias para abordar um desafio de forma estruturada — ou seja, por não planejar passos menores para alcançar o resultado final.
Depois que finalizei o desenho da solução e montei um plano, bateu o desespero: "Ferrou! Tem muita coisa para fazer... por onde eu começo?" Foi então que me lembrei de uma frase muito boa: "Basta a cada dia o seu mal."
Decidi, então, encarar uma parte de cada vez. E dentro de cada grande parte, fui quebrando o problema em partes ainda menores. Em vez de focar na implementação da solução inteira de uma vez, concentrei-me em desenvolver um service, depois uma função dentro desse service, e dentro de cada função, a sua lógica específica.
Aos poucos, aqueles problemas enormes foram se tornando mais gerenciáveis. Um passo de cada vez, e tudo foi se resolvendo.
Fazer poucas perguntas (tanto pra mim, quanto para o serviço externo)
Durante a implementação, várias dúvidas surgiram sobre o serviço externo com o qual estávamos integrando. Como funciona o fluxo X? Como recuperar o dado Y? Para que serve a credencial Z? Esse tipo de coisa.
Em vez de esclarecer essas dúvidas, simplesmente fui empurrando tudo para debaixo do tapete. E se posso te dar um conselho, é: nunca faça isso! De verdade.
Quando se trabalha com uma integração, quem mais entende dela não é você — e, às vezes, nem mesmo a documentação reflete 100% da realidade. As pessoas que realmente conhecem o serviço são os desenvolvedores responsáveis por ele e os próprios donos do negócio. Por isso, esteja preparado para enviar e-mails, marcar reuniões e, acima de tudo, ter humildade para perguntar o que não sabe.
Por não ter perguntado para que servia a credencial Z, acabei descobrindo sua real função apenas no dia da publicação. Resultado? Tive que fazer uma implementação de última hora para corrigir isso.
Não ler a documentação direito
Esse é um erro meio óbvio, né? Não ler a documentação direito. Mas aprendi, da pior forma possível, o preço disso no final do projeto.
Por não ter lido com atenção o significado de um determinado status de um item, só no fim da implementação percebi que ele servia para outra coisa — e meu código estava preparado para um cenário completamente diferente. O resultado? Mais retrabalho e uma correção feita às pressas.
Ao ler a documentação com atenção, dúvidas inevitavelmente surgirão, e isso é ótimo! Isso te ajudará a mapear quais informações precisam ser enviadas e quais precisam ser recuperadas. Além disso, você terá uma visão mais clara dos recursos disponíveis no serviço externo e de como eles funcionam, evitando retrabalho por causa de um comportamento que já estava bem descrito na documentação.
O que faria hoje se fosse realizar uma integração:
Hoje em dia seguiria esses passos:
- Entender a demanda
- Estudar onde precisa ser implementada a integração
- Estudar a documentação do parceiro
- Levantar dúvidas e tentar solucioná-las
- Planejar e desenhar a solução e pedir o feedback para alguns colegas
- Implementar a solução (E testar bastante, bastante mesmo)
É isso pessoal, não domino o assunto, mas essas foram as coisas que aprendi ao sofrer na implementação de uma integração.
Gostaria de saber quais passos vocês seguiriam caso precisem implementar uma integração, caso queiram compartilhar, coloquem aí nos comentários.
Se cuidem, bebam água e arrumem a postura da coluna.
Abraços 😁