Os erros em integração de sistemas nem sempre começam no código. Falhas de levantamento, contratos mal definidos, arquitetura inadequada, testes incompletos, retries sem controle, segurança insuficiente e ausência de monitoramento podem transformar uma conexão aparentemente simples em um problema operacional recorrente.
Uma integração confiável precisa prever não apenas o caminho de sucesso, mas também o que acontece quando um sistema fica indisponível, uma API muda, um payload chega inválido, uma operação é repetida ou o fluxo para no meio do processamento.
Resumo
- Planejamento insuficiente é uma das principais origens de problemas em integração.
- A tecnologia deve ser escolhida depois dos requisitos, não antes.
- Contratos de dados e APIs precisam definir campos, formatos, versões e erros.
- Retry sem backoff, limite e idempotência pode amplificar uma falha.
- Testar apenas o caminho de sucesso deixa problemas para produção.
- Segurança precisa considerar autenticação, autorização e exposição dos dados.
- Sem logs, métricas, traces, alertas e responsáveis, uma falha pode permanecer invisível.
Quais são os principais erros em integração de sistemas?
Os problemas mais recorrentes podem ser agrupados em sete categorias. Elas aparecem em momentos diferentes do ciclo de vida, desde o levantamento inicial até a sustentação depois do go-live.
1. Começar sem um levantamento adequado
Desenvolver antes de compreender o processo é um dos erros mais caros.
Antes de escolher protocolo ou escrever código, é necessário descobrir:
- quais sistemas participam;
- qual resultado de negócio é esperado;
- quais dados serão trocados;
- qual sistema é responsável por cada informação;
- qual volume e frequência existem;
- quais regras de negócio precisam ser respeitadas;
- quais ambientes, acessos e credenciais estão disponíveis;
- como serão definidos sucesso e aceite.
Eu aprendi isso de uma maneira particularmente difícil. Em uma publicação no LinkedIn, contei sobre uma integração que desenvolvi em 2014 e que derrubou o sistema de faturamento de um cliente em uma sexta-feira. Foram cerca de seis horas para reverter o incidente.
Quando documentei o que havia acontecido, o problema apontava para uma etapa anterior ao desenvolvimento: o levantamento não tinha sido feito adequadamente. Essa experiência influenciou a forma como passei a estruturar discovery e requisitos em projetos de integração.
2. Escolher a tecnologia antes de entender o problema
Outro erro é decidir previamente que a integração precisa ser REST, mensageria, ESB ou iPaaS e depois tentar encaixar o processo naquela escolha.
Uma consulta que precisa de resposta imediata pode funcionar bem de forma síncrona. Um processo sujeito a indisponibilidade pode exigir fila. Um alto volume periódico pode ser melhor atendido por lote. Um sistema legado pode oferecer somente arquivos ou WebServices SOAP.
O requisito deve orientar a arquitetura.
Isso vale também para iPaaS. Uma plataforma pode centralizar transformações, execução e monitoramento, mas não corrige automaticamente um processo mal definido nem aumenta a capacidade de um sistema de origem limitado.
3. Não definir contratos de dados e interfaces
Dois sistemas podem utilizar a palavra “cliente” e representar entidades completamente diferentes.
Por isso, integração exige um contrato explícito sobre:
- campos;
- tipos e formatos;
- valores obrigatórios;
- enumerações;
- identificadores;
- transformações;
- regras de validação;
- versionamento;
- comportamento de erro.
Quando APIs participam da arquitetura, uma boa documentação de API ajuda a transformar expectativas informais em contratos mais verificáveis.
Também é importante definir quem é a fonte de verdade de cada informação. Se CRM e ERP puderem alterar o mesmo campo sem uma regra de ownership, a própria integração pode criar divergências.
4. Fazer retry sem classificar a falha
Retry não significa “tentar até funcionar”.
Falhas transitórias, como timeout ou indisponibilidade momentânea, podem justificar nova tentativa. Já schema inválido, campo obrigatório ausente ou regra de negócio recusada provavelmente continuarão falhando até que alguma condição seja corrigida.
O padrão Retry da Microsoft recomenda considerar tipo de falha, intervalo e idempotência antes de repetir uma operação.
A AWS Builders’ Library também chama atenção para backoff e jitter. Se todos os consumidores repetirem chamadas simultaneamente quando um serviço começa a se recuperar, eles podem criar outra sobrecarga.
Por isso, uma política de retry deve definir pelo menos:
- quais erros podem ser repetidos;
- quantas tentativas ocorrerão;
- qual intervalo será usado;
- se haverá backoff e jitter;
- como garantir idempotência;
- o que acontece depois do limite.
5. Testar apenas o caminho de sucesso
Enviar um payload válido em homologação e receber HTTP 200 comprova muito pouco sobre o comportamento da integração em produção.
Os testes também precisam cobrir:
- campo obrigatório ausente;
- formato inválido;
- credencial expirada;
- timeout;
- rate limit;
- indisponibilidade do destino;
- mensagem duplicada;
- alto volume;
- falha parcial;
- retomada depois de interrupção.
Para integrações críticas, vale testar também os procedimentos de rollback, reprocessamento e contingência — e não apenas documentá-los.
6. Tratar segurança apenas como autenticação
Ter uma API key ou Bearer token não significa que a integração esteja segura.
É necessário avaliar:
- autenticação;
- autorização;
- menor privilégio;
- armazenamento e rotação de credenciais;
- criptografia;
- segregação de ambientes;
- controle de acesso por recurso;
- auditoria;
- dados sensíveis em logs e payloads.
O OWASP API Security Top 10 destaca riscos como Broken Object Level Authorization, Broken Authentication, consumo irrestrito de recursos, Security Misconfiguration e inventário inadequado de APIs.
7. Colocar em produção sem observabilidade e ownership
Uma integração não termina no go-live.
Se ninguém sabe quem é responsável pelo fluxo ou se a primeira indicação de problema chega por meio de um cliente reclamando, existe uma falha operacional mesmo que o código esteja correto.
Logs isolados ajudam, mas não são suficientes em arquiteturas distribuídas.
O OpenTelemetry trabalha com sinais como traces, métricas e logs. Com propagação de contexto, um trace pode acompanhar uma operação ao longo de vários componentes.
Isso facilita responder perguntas como: onde a transação parou, quanto tempo permaneceu em cada etapa e qual dependência devolveu o erro?
Confira também estes conteúdos relacionados:
- Veja como estruturar requisitos, dados, regras e testes antes que o desenvolvimento transforme incertezas em retrabalho.
- Saiba quando uma mensagem deve receber retry, seguir para uma Dead Letter Queue ou aguardar correção antes do reprocessamento.
- Descubra quais sinais revelam que uma integração está degradando antes que usuários e clientes percebam a falha.
Retry, Circuit Breaker e Dead Letter Queue são a mesma coisa?
Não. Os três mecanismos resolvem problemas diferentes.
| Mecanismo | Função | Exemplo |
|---|---|---|
| Retry | Tentar novamente uma operação potencialmente recuperável | Timeout temporário |
| Backoff | Aumentar ou controlar o intervalo entre tentativas | Serviço momentaneamente sobrecarregado |
| Circuit Breaker | Interromper chamadas para uma dependência que continua falhando | API externa indisponível por período prolongado |
| DLQ | Isolar mensagens que não puderam seguir pelo fluxo | Payload inválido depois das tentativas previstas |
| Redrive | Reintroduzir uma mensagem depois que a causa foi corrigida | Reprocessar pedido após correção de cadastro |
O Circuit Breaker tem propósito diferente de Retry: em vez de insistir, ele impede temporariamente novas chamadas para uma dependência que provavelmente continuará falhando.
Esses padrões podem ser combinados, mas precisam compartilhar uma política coerente. Caso contrário, múltiplas camadas realizando retries independentes podem multiplicar a quantidade de chamadas durante um incidente.
Quais impactos os erros de integração podem causar?
O impacto depende do processo sustentado pela integração.
| Falha | Impacto possível |
|---|---|
| Pedido não chega ao ERP | Atraso de faturamento e expedição |
| Estoque não atualiza | Venda de produto indisponível ou ruptura aparente |
| Cliente duplicado | Dados fragmentados e processos comerciais inconsistentes |
| Pagamento repetido | Impacto financeiro e retrabalho |
| Integração fiscal indisponível | Bloqueio ou atraso de processos críticos |
| Falha silenciosa | Backlog crescente sem percepção da operação |
| Credencial comprometida | Acesso indevido ou exposição de dados |
O custo do incidente não é apenas o período de indisponibilidade. Também entram investigação, correção emergencial, reconciliação dos dados, atendimento aos usuários e efeitos acumulados nas etapas posteriores do processo.
Quais métricas ajudam a detectar falhas?
O Google SRE Book propõe quatro sinais fundamentais para sistemas distribuídos: latência, tráfego, erros e saturação.
Em integrações, eles podem ser complementados por indicadores específicos do fluxo:
- taxa de sucesso;
- latência ponta a ponta;
- volume processado;
- quantidade de retries;
- mensagens pendentes;
- volume na DLQ;
- idade da mensagem mais antiga;
- erros por categoria;
- tempo até detecção;
- tempo até recuperação;
- divergências encontradas em reconciliação.
O mais importante é relacionar a métrica ao processo. Dez mensagens paradas podem ser irrelevantes em um fluxo de baixa prioridade ou representar a interrupção completa do faturamento de uma operação.
Como evitar erros em integração de sistemas?
- Faça discovery antes do desenvolvimento: mapeie sistemas, processo, dados, regras, volume, responsáveis e resultado esperado.
- Defina contratos: documente schemas, transformações, erros, identificadores e versionamento.
- Modele as falhas: diferencie erro transitório, permanente e funcional antes de configurar retries.
- Projete para idempotência: impeça efeitos duplicados em novas tentativas e reprocessamentos.
- Teste exceções: valide indisponibilidade, timeout, dados inválidos, volume e recuperação.
- Inclua segurança no desenho: autenticação, autorização, menor privilégio e proteção das credenciais.
- Instrumente antes do go-live: logs, métricas, traces e alertas precisam existir quando a integração entra em produção.
- Defina ownership e runbook: deixe explícito quem recebe o alerta, como diagnosticar e quais ações podem ser executadas.
Como agir quando uma integração falha em produção?
- Identifique o impacto: quais processos, clientes ou transações foram afetados?
- Interrompa o efeito em cascata: suspenda retries ou fluxos quando eles estiverem ampliando o problema.
- Localize a etapa: use correlation ID, logs, traces e métricas.
- Classifique a falha: aplicação, infraestrutura, contrato, dado, autenticação ou regra de negócio.
- Recupere a operação: aplique correção, contingência, reprocessamento ou rollback conforme o caso.
- Reconcilie os dados: confirme que nenhuma transação foi perdida ou duplicada.
- Registre o aprendizado: documente causa raiz e altere processo, teste, monitoramento ou arquitetura para reduzir recorrência.
Integração confiável é projetada para falhar com controle
Nenhuma arquitetura elimina completamente indisponibilidade, mudança de API, timeout, dado inválido ou erro humano.
A diferença entre uma integração frágil e uma integração madura está na forma como a falha é prevista, detectada, isolada e recuperada.
Planejamento, contratos claros, idempotência, testes, segurança e observabilidade tornam o comportamento da integração mais previsível quando algo sai do caminho esperado.
A SysMiddle atua desde o levantamento e desenho até desenvolvimento, monitoramento e sustentação das integrações, conectando APIs, ERPs, plataformas digitais, bancos e sistemas legados com governança operacional.
Se sua equipe passa mais tempo apagando incêndios do que evoluindo as integrações, fale com um especialista da SysMiddle.
Perguntas frequentes sobre erros em integração de sistemas
Entre os mais comuns estão levantamento insuficiente, tecnologia inadequada, contratos mal definidos, retries incorretos, testes incompletos, falhas de segurança e ausência de observabilidade e responsáveis.
Retry é mais indicado para falhas potencialmente transitórias, como timeout ou indisponibilidade temporária. A política deve definir limite, intervalo, backoff e condições de idempotência.
Retry repete uma operação esperando que uma falha transitória desapareça. Circuit Breaker interrompe temporariamente chamadas quando uma dependência apresenta falha persistente.
Ela ajuda a impedir que novas tentativas ou reprocessamentos produzam efeitos duplicados, como criar duas vezes o mesmo pedido ou cobrança.
Além do caminho de sucesso, teste dados inválidos, timeout, indisponibilidade, credenciais, rate limit, duplicidades, alto volume, falhas parciais, retomada e reprocessamento.
Taxa de sucesso, latência, volume, erros, retries, backlog, mensagens em DLQ, idade das mensagens, divergências e tempos de detecção e recuperação ajudam a identificar degradações.
