Erro de integração é quando dois sistemas que deveriam trocar informações não conseguem: o dado não chega, chega errado ou chega duas vezes. No dia a dia, isso aparece como um pedido da loja virtual que não entra no ERP, uma nota fiscal que não emite, um estoque que não bate ou um pagamento aprovado que o sistema não reconhece. Quase sempre a causa é uma destas: credencial ou certificado vencido, sistema do outro lado fora do ar ou lento, mudança no formato dos dados, cadastros diferentes entre os sistemas ou falta de reprocessamento quando algo dá errado.
Neste guia, explico o que a mensagem de erro costuma significar, as causas mais comuns em uma tabela (causa, sintoma e como resolver), os sinais de falta de integração na empresa e o que pedir ao seu time ou fornecedor para o problema não voltar toda semana.
O que significa "erro de integração"?
Integração é a ponte entre dois sistemas. A loja virtual avisa o ERP que houve uma venda. O ERP envia a nota para a SEFAZ. O gateway de pagamento avisa que o Pix caiu. Cada uma dessas conversas acontece por uma API, um webhook (um aviso automático que um sistema manda para o outro), um arquivo ou uma rotina agendada.
Quando aparece "erro de integração" na tela, a mensagem quer dizer só isso: a conversa entre os dois lados falhou. Ela quase nunca diz o motivo. O detalhe fica no log técnico, que normalmente traz um código (401, 422, 500, timeout) e o texto que o outro sistema devolveu.
Exemplos reais de erro de integração
- Pedido não chega no ERP: o cliente pagou na loja, mas o pedido não aparece para faturar. Em geral, o envio falhou uma vez e ninguém tentou de novo.
- Nota fiscal não emite: a SEFAZ rejeita por certificado digital vencido, dado fiscal incorreto (NCM, CFOP, CST) ou instabilidade no serviço autorizador do estado.
- Estoque divergente: o site mostra disponível um produto que já acabou, porque a sincronização roda de tempos em tempos ou parou sem avisar ninguém.
- Webhook que falha: o gateway avisa "pagamento aprovado", mas seu sistema estava fora do ar naquele momento. O aviso se perde e o pedido fica parado como "aguardando pagamento".
- Token expirado: a integração funcionava até ontem; hoje toda chamada volta "não autorizado", porque a chave de acesso venceu e não foi renovada.
- Timeout: o outro sistema demorou demais para responder e a chamada foi cancelada. Fica a dúvida: a operação foi feita ou não?
Por que a integração falha? Causas, sintomas e soluções
Em integrações com ERPs, lojas virtuais, gateways de pagamento, transportadoras e SEFAZ, as falhas se repetem. A tabela resume o que mais encontramos e o caminho de solução de cada caso.
| Causa | Sintoma | Como resolver |
|---|---|---|
| Token, senha de API ou certificado digital vencido | Tudo para de uma vez; erro 401 ou 403; nota rejeitada por certificado | Renovação automática do token e alerta de vencimento do certificado com antecedência |
| Sistema do outro lado fora do ar ou lento | Erros 500, 502, 503 ou timeout, principalmente em horário de pico | Fila com nova tentativa automática, espaçando cada tentativa |
| Mudança na API do parceiro | Erro 400 ou 422, campos vazios, dados chegando incompletos | Acompanhar versões e avisos do fornecedor; testes automáticos do formato esperado |
| Cadastros diferentes entre sistemas | Produto "não encontrado", cliente duplicado, unidade de medida errada | Tabela de-para com um responsável e validação dos dados antes de enviar |
| Regra fiscal ou de negócio diferente | Rejeição da SEFAZ, imposto ou total divergente entre loja e ERP | Validar dados fiscais na origem e testar em ambiente de homologação |
| Webhook perdido | Pagamento aprovado que não baixa; status parado há horas | Registrar todo aviso recebido e conciliar periodicamente com o parceiro |
| Envio duplicado | Pedido em dobro, cobrança em dobro, estoque baixado duas vezes | Idempotência: cada operação com um identificador único |
| Limite de requisições do parceiro | Erro 429 ao enviar lotes grandes | Enviar em lotes menores, respeitando o limite informado pela API |
| Integração improvisada (script, planilha, rotina sem dono) | Para sem ninguém perceber; só se descobre pela reclamação do cliente | Monitoramento com alerta e um responsável definido |
Como ler o código do erro
Se o seu sistema mostra um número junto da mensagem, ele já aponta o caminho:
- 400 ou 422: o dado enviado está errado ou incompleto. O problema está em quem enviou.
- 401 ou 403: acesso negado. Credencial vencida, errada ou sem permissão.
- 404: o endereço ou o registro não existe do outro lado.
- 429: chamadas demais em pouco tempo. É preciso desacelerar.
- 500, 502 ou 503: falha no sistema de destino. Geralmente basta tentar de novo mais tarde.
- Timeout: não houve resposta a tempo. Antes de reenviar, confira se a operação foi feita, para não duplicar.
Sinais de falta de integração na empresa
Nem todo problema aparece como mensagem de erro. Muitas vezes a falha é estrutural: os sistemas simplesmente não conversam, e as pessoas fazem o papel da integração. Fique atento a estes sinais:
- A equipe digita a mesma informação em dois ou três sistemas.
- Existe uma planilha "de conferência" para checar se um sistema bate com o outro.
- Relatórios de vendas, financeiro e estoque mostram números diferentes para o mesmo período.
- Alguém pergunta no WhatsApp se o pedido "já caiu" no outro sistema.
- O fechamento do mês depende de exportar, colar e corrigir dados à mão.
- O cliente descobre o problema antes da empresa: cobrança errada, pedido parado, produto sem estoque.
Falta de integração e integração com falha geram o mesmo prejuízo: retrabalho, erro humano e decisão tomada com número errado. Se você reconheceu três ou mais sinais, vale entender como funciona um projeto de integração de sistemas pensado para a sua operação.
Como resolver um erro de integração agora
Quando a falha já aconteceu, siga esta ordem antes de sair mexendo:
- Descubra qual ponte falhou e desde quando. Loja para ERP? ERP para SEFAZ? Gateway para loja?
- Leia o log e o código de erro. Ele separa problema de acesso, de dado ou do outro sistema.
- Confira credenciais e certificado digital. É a causa mais comum de "parou tudo de uma vez".
- Verifique se o parceiro está instável. Gateways, marketplaces e a SEFAZ costumam publicar o status dos seus serviços.
- Corrija o dado na origem, não no destino. Arrumar só no ERP faz o erro voltar no próximo envio.
- Reprocesse o que ficou para trás e confira se nada foi duplicado.
- Registre a causa, para não investigar do zero na próxima vez.
Como prevenir falhas de integração
Integração que nunca falha não existe: o outro sistema vai cair e o token vai vencer. A diferença está em como ela se comporta quando isso acontece. Cobre estes pontos do seu time ou fornecedor.
Filas: nada se perde quando o outro lado cai
Em vez de enviar direto e torcer, a informação entra numa fila, como a caixa de saída do e-mail. Se o destino estiver fora do ar, ela espera e é enviada depois. No e-commerce da Flash Universo, por exemplo, tarefas em segundo plano rodam em filas, e há um painel de exceções para tratar entregas com problema.
Reprocessamento automático e manual
Falhou? O sistema tenta de novo sozinho, com intervalos cada vez maiores. Se ainda assim não der certo, o item vai para uma lista de pendências que alguém da operação consegue reenviar com um clique, sem chamar o programador.
Idempotência: enviar duas vezes não cria duas vezes
O nome é técnico, mas a ideia é simples. Cada pedido, cobrança ou nota leva um identificador único. Se o mesmo envio chegar duas vezes, o sistema reconhece e ignora a repetição. É o que permite reprocessar sem medo de cobrança em dobro.
Monitoramento e alertas
A empresa precisa saber do problema antes do cliente. Alertas quando a fila começa a acumular, quando os erros sobem ou quando um certificado está perto de vencer evitam que a falha seja descoberta dias depois, no fechamento.
Logs que contam a história
Cada troca de dados deve ficar registrada: quando aconteceu, o que foi enviado e o que voltou. Atenção à LGPD: registre o necessário para investigar e evite guardar dados pessoais sem necessidade.
Isolamento: a falha de um parceiro não derruba o resto
Uma parte instável não pode parar a operação inteira. No PRIS ERP, o módulo fiscal roda em um backend separado: se a SEFAZ oscilar, o caixa e o restante do sistema seguem funcionando.
Boa parte disso depende de uma API bem desenhada, com versionamento, mensagens de erro claras e autenticação que se renova sozinha. Explicamos esse cuidado na página de desenvolvimento de APIs.
Quando corrigir e quando refazer a integração
Corrigir faz sentido quando a falha é pontual, a causa é conhecida e o problema não se repete. Refazer passa a valer a pena quando:
- a integração falha toda semana e cada correção abre um problema novo;
- ninguém sabe exatamente como ela funciona, ou só uma pessoa sabe;
- não há fila, reprocessamento nem log, e cada falha exige investigação manual;
- o conector usa uma versão de API que o parceiro já anunciou que vai desligar;
- um dos sistemas é antigo e não tem API, então a integração lê o banco de dados direto ou troca arquivos.
No último caso, o problema não é só a ponte, é um dos lados dela. A saída costuma passar pela modernização de sistemas, muitas vezes começando por criar uma API em volta do sistema legado, sem precisar reescrevê-lo de uma vez.
Perguntas frequentes
O que significa erro de integração?
Significa que a troca de dados entre dois sistemas falhou: a informação não chegou, chegou incompleta ou foi recusada pelo destino. O motivo exato fica no log técnico, normalmente com um código de erro.
Falha no sistema e erro de integração são a mesma coisa?
Não. Falha no sistema é um problema dentro de um único software. Erro de integração acontece na comunicação entre dois sistemas, e os dois podem estar funcionando bem isoladamente.
De quem é a culpa: do meu sistema ou do outro?
O código de erro dá a primeira pista. Erros 400, 401 e 422 costumam indicar problema no envio ou na credencial. Erros 500, 502, 503 e timeout apontam para o sistema de destino. Na dúvida, os logs dos dois lados resolvem a discussão.
Dá para integrar um sistema antigo que não tem API?
Na maioria dos casos, sim. É possível criar uma API intermediária que lê e grava no sistema legado de forma controlada, com log e validação. É mais seguro do que acessar o banco de dados direto.
Sofrendo com integrações que falham?
