Por que algumas integrações duram anos e outras quebram toda semana

Quase toda empresa que chega à MFactor Tecnologia tem pelo menos uma integração que "funciona, mas de vez em quando dá problema". O pedido que não chegou no ERP. A nota que saiu duplicada. O estoque que ficou negativo num sábado à noite e ninguém sabe explicar.

Na maior parte das vezes o código não está errado no sentido óbvio. Ele faz o que deveria quando tudo dá certo. Só que entre dois sistemas alguma coisa sempre dá errado em algum momento: a rede oscila, a API do outro lado fica lenta, um campo vem vazio. Integração boa é a que foi pensada para esses momentos.

Estes são os pontos que revisamos em qualquer integração, nova ou herdada.

Cada dado precisa ter um dono

Antes de escrever uma linha de código, cada informação precisa de uma fonte da verdade. O preço que vale é o do ERP ou o da loja? O cadastro do cliente nasce no CRM ou no financeiro?

Parece burocracia, mas é a origem de boa parte dos bugs. Quando os dois lados podem editar o mesmo campo, cedo ou tarde um sobrescreve o outro e ninguém percebe até o cliente reclamar. A regra que seguimos é simples: cada campo tem um único sistema que escreve. Os outros só leem.

A mesma mensagem vai chegar duas vezes

Webhooks e filas, na grande maioria das plataformas, entregam "pelo menos uma vez". Se o sistema de origem não recebe a confirmação a tempo, ele reenvia. Do lado de quem recebe, o mesmo pedido pode aparecer duas, três vezes.

Por isso toda operação que cria alguma coisa precisa ser idempotente. Na prática, guardamos um identificador único de cada evento (o número do pedido na loja, ou uma chave de idempotência gerada na origem) e, antes de processar, conferimos se ele já foi tratado. Se já foi, respondemos sucesso e nada acontece. É uma tabela e uma consulta, e evita nota duplicada, cobrança em dobro e estoque baixado duas vezes.

Tentar de novo, com critério

Quando a API do outro lado falha, tentar de novo na mesma hora costuma piorar as coisas. Se o serviço está sobrecarregado, mil integrações insistindo juntas garantem que ele continue fora.

O padrão que usamos é esperar cada vez mais entre as tentativas (1 segundo, depois 2, 4, 8) com um pouco de aleatoriedade no intervalo, para que elas não cheguem todas ao mesmo tempo. Também separamos os erros. Um 503 ou um timeout merece nova tentativa. Um 400 dizendo que o CPF é inválido não vai se resolver sozinho, e insistir só enche o log.

Passado o limite de tentativas, a mensagem vai para uma fila separada de falhas. Ela não some. Fica lá, com o erro registrado, esperando alguém olhar ou reprocessar.

A integração não pode travar quem está atendendo o cliente

Um erro comum é chamar o outro sistema dentro da mesma requisição do usuário. O cliente clica em finalizar compra, a loja chama o ERP, o ERP demora 20 segundos e o cliente desiste.

Quando o resultado não precisa ser imediato, a loja grava o pedido, coloca um evento numa fila e responde na hora. Um processo separado consome a fila e conversa com o ERP no tempo dele. Se o ERP cair, os pedidos esperam na fila e são processados quando ele voltar. A venda não se perde.

Webhook ou consulta periódica?

Webhook é mais rápido e mais barato, porque o outro sistema avisa quando algo acontece. O ponto fraco é que, se o seu endpoint estiver fora do ar na hora do aviso e a plataforma desistir de reenviar, o evento se perde.

Em integrações que mexem com dinheiro ou estoque, usamos os dois. O webhook cuida do tempo real, e uma rotina de conciliação roda de tempos em tempos (de hora em hora ou uma vez por noite, conforme o volume) comparando os dois lados e corrigindo o que ficou para trás. Quase nunca ela acha diferença. Quando acha, todo mundo agradece por ela existir.

Responder "o que aconteceu com o pedido 4512?"

Essa pergunta vai aparecer. Se a resposta depende de alguém entrar no servidor e procurar num arquivo de texto, a integração está incompleta.

Cada evento processado deveria registrar quando chegou, o que foi enviado, o que voltou e quanto tempo levou, com um identificador que permita seguir o pedido de ponta a ponta. Assim o atendimento consegue responder o cliente sem chamar o desenvolvedor.

O checklist que usamos

Quando recebemos uma integração para revisar, começamos por estas perguntas:

• Cada dado tem um único sistema dono?
• O processamento aguenta receber o mesmo evento duas vezes?
• As novas tentativas esperam cada vez mais e têm limite?
• Existe uma fila para as mensagens que falharam?
• Alguma rotina confere se os dois lados estão iguais?
• Dá para rastrear um pedido específico sem entrar no servidor?

Se mais de duas respostas forem não, a integração provavelmente só funciona hoje porque o volume ainda é pequeno. Melhor corrigir antes de crescer.