Integração entre ERP e e-commerce: como evitar estoque divergente, pedidos duplicados e processos manuais

Conectar um ERP a uma loja virtual parece simples quando o projeto é resumido a duas frases: enviar produtos para o e-commerce e devolver os pedidos ao sistema de gestão. Na operação real, porém, a dificuldade não está apenas em chamar uma API. Ela está em definir qual sistema controla cada informação, como os dados serão identificados, o que acontece quando uma etapa falha e como a equipe comprovará que tudo foi processado corretamente.

Uma integração mal planejada pode funcionar durante semanas e ainda assim acumular problemas silenciosos: estoque disponível diferente do saldo físico, preço promocional sobrescrito, pedido criado duas vezes, pagamento aprovado sem faturamento, rastreamento que não chega ao cliente ou uma fila parada sem qualquer alerta.

Este guia apresenta as decisões técnicas e operacionais que devem ser tomadas antes de integrar ERP e e-commerce. A proposta não é indicar uma tecnologia única, mas mostrar como construir um fluxo rastreável, recuperável e preparado para evoluir.

1. Comece pela operação, não pelos endpoints

Antes de abrir a documentação de qualquer API, descreva o fluxo comercial de ponta a ponta:

Onde o produto é cadastrado?
Quem define preço, promoção e tabela comercial?
Qual sistema calcula o estoque disponível para venda?
Em que momento o e-commerce reserva uma unidade?
Quando um pedido deve ser enviado ao ERP?
Qual evento libera faturamento, separação e expedição?
Como cancelamentos, recusas e expirações devolvem o estoque?
De onde vêm nota fiscal, rastreamento e status pós-venda?

Sem essas respostas, a integração tende a apenas reproduzir inconsistências já existentes. Automatizar um processo mal definido não o torna confiável; apenas permite que o erro circule com mais velocidade.

Sinais de que a operação já ultrapassou a integração atual

a equipe mantém planilhas paralelas para corrigir estoque ou preço;
pedidos precisam ser digitados novamente no ERP;
o atendimento consulta vários sistemas para descobrir o status real;
reprocessar uma integração pode duplicar cadastros ou pedidos;
ninguém consegue dizer qual foi o último registro processado;
falhas são descobertas pelo cliente, e não por monitoramento;
mudanças simples exigem ajustes manuais em vários canais.

Esses sintomas indicam que o problema deixou de ser apenas operacional. A arquitetura passou a limitar o crescimento.

2. Defina uma fonte de verdade para cada entidade

“O ERP é a fonte de verdade” pode ser uma regra útil, mas ainda é ampla demais. Um ERP pode controlar estoque e faturamento enquanto o e-commerce controla descrições comerciais, imagens e conteúdo de SEO. A decisão precisa ser tomada por entidade — e, em alguns casos, por campo.

Uma vez definida a autoridade, bloqueie ou trate com cuidado alterações vindas de sistemas consumidores. Se o preço nasce no ERP, uma edição manual no e-commerce não pode permanecer indefinidamente sem que exista uma regra explícita para isso.

Registre também a direção e a frequência

Para cada fluxo, documente:

origem e destino;
evento que dispara a sincronização;
frequência esperada;
atraso máximo aceitável;
campos obrigatórios;
regra para registros inválidos;
responsável pela correção;
forma de reprocessamento.

Esse mapa se torna o contrato operacional da integração.

3. Resolva identidade antes de sincronizar dados

Dois sistemas raramente usam o mesmo identificador interno. O produto 1842 no ERP pode ser 9631 no e-commerce e ter outro código em cada marketplace. A integração precisa manter um vínculo estável entre esses registros.

Produtos e variações

Use o SKU como identificador comercial sempre que ele for único e estável. Para variações, cada combinação vendável deve possuir seu próprio identificador. GTIN pode ajudar na equivalência entre canais, mas não substitui necessariamente o SKU interno.

Não dependa de nome, descrição ou posição na lista de atributos. Esses valores mudam e produzem associações frágeis.

Uma tabela de mapeamento normalmente precisa armazenar:

tenant ou operação;
sistema de origem;
identificador de origem;
sistema de destino;
identificador de destino;
SKU e, quando aplicável, GTIN;
versão ou data da última sincronização;
situação do vínculo.

Clientes e pedidos

E-mail, CPF ou CNPJ podem ajudar a localizar cadastros, mas exigem regras de privacidade e qualidade. Um cliente pode alterar e-mail, usar documentos diferentes em compras B2B e B2C ou comprar como visitante. Preserve sempre os identificadores externos recebidos de cada sistema.

Para pedidos, mantenha ao menos:

identificador interno da integração;
número do pedido no canal;
identificador do ERP;
identificador da transação de pagamento;
chave de idempotência;
correlação de logs e eventos.

4. Estoque não é apenas um número

O saldo físico não é necessariamente o saldo que pode ser anunciado. Uma regra comum é:

estoque disponível = saldo físico − reservas − margem de segurança

Dependendo da operação, ainda podem existir estoque em trânsito, lotes bloqueados, múltiplos depósitos, kits, componentes, produtos sob encomenda e limites específicos por canal.

Perguntas que precisam de resposta

A reserva ocorre ao adicionar ao carrinho, criar o pedido ou aprovar o pagamento?
Quanto tempo dura uma reserva de Pix ou boleto?
Um pagamento recusado libera o saldo imediatamente?
Qual depósito atende cada região ou canal?
Kits baixam o produto final ou seus componentes?
O que acontece quando duas vendas disputam a última unidade?
O e-commerce pode aceitar venda sem estoque?
Existe margem de segurança diferente por canal?

Evite o ciclo de retroalimentação

Um erro comum ocorre quando ERP e e-commerce reenviam a mesma alteração um ao outro. O ERP atualiza o estoque; o e-commerce recebe e publica; um webhook trata a publicação como nova alteração e devolve o mesmo número ao ERP.

Para evitar isso, registre a origem da mudança, use versões ou timestamps confiáveis e ignore eventos que apenas confirmam o estado já aplicado.

5. Modele o ciclo de vida do pedido

Não tente encaixar todos os sistemas em uma lista única de status. Cada plataforma representa o processo de uma forma diferente. Crie um modelo canônico interno e mapeie os estados externos para ele.

Um fluxo possível:

pedido recebido;
aguardando pagamento;
pagamento aprovado;
enviado ao ERP;
aceito pelo ERP;
faturado;
em separação;
enviado;
entregue;
cancelado ou devolvido.

O ponto crítico é distinguir evento recebido de processamento concluído. Receber um webhook de pagamento não prova que o pedido foi criado no ERP. Enviar uma requisição ao ERP não prova que ele aceitou e persistiu o pedido.

Preserve o histórico, não apenas o estado atual

Registre transições com data, origem, payload relevante e resultado. Esse histórico permite responder:

quando o pagamento foi aprovado;
quanto tempo o pedido permaneceu na fila;
qual tentativa criou o registro no ERP;
quem cancelou o pedido;
por que o estoque foi devolvido;
qual status foi comunicado ao cliente.

6. Use idempotência para impedir duplicidades

Redes falham. Um sistema pode enviar uma requisição, não receber a resposta e tentar novamente. Sem idempotência, a segunda tentativa pode criar outro pedido, cobrar novamente ou reduzir o estoque duas vezes.

Uma operação idempotente produz o mesmo efeito quando é repetida com a mesma identidade. Na prática:

gere ou receba uma chave única por operação;
armazene a chave antes ou junto da alteração de estado;
rejeite ou devolva o resultado anterior em tentativas repetidas;
imponha restrição única no banco quando possível;
não use apenas horário ou conteúdo completo do payload como identidade.

Para criar um pedido no ERP, uma boa chave pode combinar operação, canal e identificador original do pedido. O mesmo princípio vale para pagamentos, cancelamentos e movimentos de estoque.

Idempotência não elimina a necessidade de transações. Ela protege a fronteira entre sistemas; a consistência das mudanças locais ainda deve ser garantida no banco de dados.

7. Trate a integração como assíncrona quando a operação permitir

Nem toda ação precisa bloquear a experiência do cliente. Depois que a loja confirma um pedido, o envio ao ERP pode ser processado por uma fila, desde que o status seja transparente e exista monitoramento.

Filas ajudam a:

absorver picos;
limitar a pressão sobre APIs externas;
executar retentativas;
separar indisponibilidade externa do checkout;
escalar consumidores de forma independente;
manter evidências de processamento.

Retentativas precisam de critério

Erros transitórios — timeout, indisponibilidade temporária ou limite de requisições — podem ser repetidos com atraso progressivo. Erros definitivos — SKU inválido, campo obrigatório ausente ou regra fiscal rejeitada — devem falhar rapidamente e ir para análise.

Use:

número máximo de tentativas;
backoff exponencial com variação aleatória;
fila de mensagens não processadas;
alerta para acúmulo ou idade excessiva;
reprocessamento controlado e idempotente.

Repetir indefinidamente um dado inválido apenas ocupa recursos e esconde o problema.

8. Valide contratos e normalize formatos

APIs podem aceitar JSON e ainda discordar sobre o significado do dado. Defina contratos explícitos para:

moeda e arredondamento;
casas decimais de preço e quantidade;
timezone e formato de data;
endereço e códigos de país/estado;
identificadores fiscais;
descontos por item e por pedido;
frete, impostos e total final;
produtos simples, variações, kits e serviços;
campos nulos, opcionais e valores padrão.

No Brasil, inclua cenários de CPF/CNPJ, inscrição estadual, Pix, boleto e documentos fiscais quando fizerem parte do fluxo. Em uma operação internacional, adapte o contrato a moedas, impostos e identificadores locais sem misturar essas regras no núcleo da integração.

Versione contratos e mudanças. Adicionar um campo opcional costuma ser compatível; renomear um status, mudar a unidade de medida ou alterar o significado de um total pode quebrar consumidores silenciosamente.

9. Construa observabilidade para localizar o pedido

Uma integração não está pronta se o suporte precisa acessar diretamente o banco para descobrir o que aconteceu.

Logs estruturados

Cada evento deve incluir campos pesquisáveis:

operação ou tenant;
sistema de origem e destino;
tipo de entidade;
identificadores externos;
chave de idempotência;
trace_id ou identificador de correlação;
tentativa atual;
duração;
resultado e código de erro.

Não registre tokens, senhas, dados completos de cartão ou informações pessoais desnecessárias.

Métricas úteis

eventos recebidos e concluídos por período;
taxa de erro por integração;
tempo médio e percentis de processamento;
idade da mensagem mais antiga;
quantidade de retentativas;
mensagens na fila de falha;
divergências encontradas pela conciliação;
pedidos pagos ainda não aceitos pelo ERP.

Rastreamento distribuído

Quando a arquitetura envolve API, fila, worker e ERP, um identificador de correlação permite seguir a mesma operação entre componentes. A correlação entre logs e traces reduz o tempo necessário para descobrir onde o fluxo parou.

10. Faça conciliação: integração entregue não é integração conferida

Webhooks podem se perder, APIs podem ficar indisponíveis e operadores podem alterar dados manualmente. Por isso, além do fluxo em tempo real, execute rotinas periódicas de conciliação.

Exemplos:

pedidos pagos na loja que não existem no ERP;
pedidos faturados sem rastreamento no e-commerce;
produtos com preço ou estoque divergente;
cancelamentos aplicados em apenas um sistema;
pedidos duplicados por identificador externo;
eventos presos além do prazo aceitável.

A conciliação pode corrigir automaticamente casos seguros e abrir uma ocorrência para casos ambíguos. O relatório precisa mostrar quantidade, impacto, registros envolvidos e ação tomada.

11. Homologue cenários de sucesso e de falha

Um pedido perfeito não valida a integração. Monte uma matriz com cenários como:

Valide também volume, concorrência, permissões, expiração de credenciais e recuperação após reinício de workers.

12. Implante em etapas e mantenha um plano de retorno

Uma migração segura pode começar com leitura e comparação, sem alterar o sistema de destino. Depois, habilite uma entidade ou um grupo pequeno de produtos, acompanhe métricas e só então amplie o fluxo.

Uma sequência possível:

mapear e limpar identificadores;
executar sincronização inicial;
comparar resultados sem escrita automática;
habilitar catálogo e estoque para um recorte;
ativar pedidos de teste;
acompanhar conciliação e alertas;
ampliar gradualmente;
desativar o processo antigo apenas após estabilidade.

O plano de retorno deve dizer como interromper consumidores, preservar eventos ainda não processados, restaurar configurações e evitar que os dois fluxos trabalhem simultaneamente.

Checklist antes de contratar ou desenvolver uma integração

Existe uma fonte de verdade definida para cada entidade?
Produtos e variações possuem identificadores estáveis?
O conceito de estoque disponível está documentado?
Os status de pedido estão mapeados nos dois sentidos?
Criações e alterações críticas são idempotentes?
Retentativas diferenciam erro transitório de erro permanente?
Há fila de falha e reprocessamento controlado?
Logs permitem localizar um pedido sem acessar o banco?
Existem métricas e alertas para atraso e divergência?
Uma rotina de conciliação compara os sistemas?
O ambiente de homologação representa a operação real?
Credenciais, dados pessoais e permissões estão protegidos?
O plano de implantação possui etapas e retorno?

Integração confiável é parte da operação, não um conector isolado

Uma boa integração não é aquela que apenas transfere dados quando tudo funciona. Ela precisa impedir duplicidades, sobreviver a indisponibilidades, tornar falhas visíveis e permitir recuperação sem improviso.

A AGTI desenvolve e evolui plataformas de vendas, integrações com ERP e automações para operações B2C e B2B. Se estoque, pedidos ou processos manuais estão limitando o crescimento da sua loja, podemos mapear o fluxo atual e transformar as necessidades da operação em uma arquitetura executável.

CTA: Converse com a AGTI sobre sua integração

Fontes técnicas

AWS — Retry with backoff pattern: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/retry-backoff.html
Stripe — Idempotency in API requests: https://docs.stripe.com/api-v2-overview
OpenTelemetry — Log correlation: https://opentelemetry.io/docs/specs/otel/logs/
Google Analytics — Ecommerce measurement: https://developers.google.com/analytics/devguides/collection/ga4/ecommerce