"Os dois sistemas têm API, então integrar deve ser rápido." É uma das frases que mais aparecem em primeira conversa, e é razoável — mas a existência de API responde apenas à pergunta mais fácil. O custo real de uma integração mora em outros quatro lugares.
1. Quem é a fonte da verdade?
Se um cliente existe nos dois sistemas e o telefone dele está diferente, qual dos dois está certo? A pergunta parece trivial e é a que mais atrasa projeto. Ela precisa de resposta por campo, não por entidade: é comum o CRM ser a verdade sobre contato e o ERP ser a verdade sobre crédito, dentro do mesmo cadastro.
Sem essa definição explícita, a integração vira um ping-pong em que cada sincronização sobrescreve a anterior. O sintoma clássico é o dado que "volta" sozinho depois de corrigido.
2. O que acontece quando falha no meio?
Integração que só funciona no caminho felizes não é integração, é demonstração. As perguntas que precisam de resposta antes de escrever código:
- Se o segundo sistema estiver fora do ar, o pedido fica em fila ou é rejeitado?
- Se a mesma mensagem chegar duas vezes, gera dois registros ou um? (idempotência)
- Se o registro falhar por dado inválido, quem é avisado e onde ele fica até ser corrigido?
- Depois de quantas tentativas o sistema desiste — e como alguém descobre?
Tratar isso custa mais que o caminho principal. É comum a lógica de erro ser maior que a de sucesso, e é ela que decide se a integração sobrevive ao primeiro mês em produção.
3. Os dois sistemas concordam sobre o significado dos campos?
Divergência de formato é fácil: data em dois padrões, valor com ponto ou vírgula. Isso se resolve com conversão. O caro é a divergência de significado.
Um exemplo real de categoria: um sistema chama de "pedido faturado" o momento em que a nota é emitida; o outro, o momento em que o pagamento é confirmado. Os dois usam a mesma palavra e nenhum está errado. A integração precisa escolher — e a escolha muda relatório, comissão e projeção de caixa. Nenhuma documentação de API avisa sobre isso; só aparece conversando com quem opera.
4. Quem mantém quando um dos lados mudar?
Integração é a única parte do sistema que quebra sem ninguém ter mexido nela. O fornecedor do outro lado publica uma versão nova, deprecia um campo, muda um limite de requisições — e o que funcionava há meses para de funcionar.
Isso significa que integração tem custo de manutenção, não só de construção. Projetos que ignoram isso entregam a integração e descobrem seis meses depois que ninguém é responsável por ela.
Como reduzir o custo de verdade
Três decisões técnicas que fazem diferença desproporcional:
- Sincronize por evento, não por varredura. Puxar tudo de tempos em tempos é simples de escrever e caro de operar. Reagir a mudanças reduz volume e latência ao mesmo tempo;
- Registre tudo que entra e sai. Sem log da mensagem original, investigar divergência é adivinhação. Com log, é consulta;
- Isole a integração atrás de uma camada própria. Quando o outro lado mudar, você altera um lugar em vez de caçar chamadas espalhadas pelo código.
Quando não integrar
Vale dizer: às vezes a resposta honesta é não integrar. Se o fluxo acontece três vezes por mês e leva dois minutos manual, automatizar custa mais do que economiza — e adiciona uma peça que pode quebrar. Integração se justifica por volume, por risco de erro humano ou por necessidade de tempo real. Quando nenhum dos três está presente, manual está certo.