Como integrar uma loja virtual a um ERP sem perder (nem duplicar) pedidos

Quase toda integração entre loja virtual e ERP começa igual: um webhook recebe o pedido, um script o envia ao ERP, e funciona nos testes. Em produção, aparecem os problemas de verdade: o ERP fica fora do ar por dez minutos, o webhook chega duas vezes, dois eventos do mesmo pedido chegam fora de ordem, e na Black Friday o estoque diverge. Este texto reúne os princípios que mais evitam dor de cabeça, em ordem de importância.

Nada aqui depende de uma plataforma específica. Vale para qualquer loja, ERP ou marketplace que ofereça API e webhooks.

1. Parta do princípio de que tudo chega pelo menos uma vez

Webhooks e filas costumam garantir entrega "pelo menos uma vez", não "exatamente uma vez". Então o mesmo evento pode chegar duplicado, e a sua integração precisa aguentar isso. A técnica é a idempotência: processar o mesmo pedido duas vezes deve ter o mesmo efeito que processar uma.

Na prática, defina uma chave única para cada pedido (por exemplo, canal + ID do pedido na origem) e use-a para criar ou atualizar, nunca só para criar:

// Pseudocódigo: grava o pedido no ERP de forma idempotente
async function sincronizarPedido(pedido: PedidoLoja) {
  const chave = `${pedido.canal}:${pedido.id}`;

  const existente = await erp.buscarPorChaveExterna(chave);
  if (existente) {
    // Já foi enviado: só atualiza o que mudou (status, rastreio...)
    return erp.atualizar(existente.id, mapearAtualizacao(pedido));
  }
  return erp.criar({ ...mapearCriacao(pedido), chaveExterna: chave });
}

Se o ERP não tiver um campo para a chave externa, guarde o vínculo em uma tabela sua (chave → id no ERP) e consulte antes de criar. Esse vínculo também ajuda a depurar: dá para perguntar "o que aconteceu com o pedido X?".

2. Use uma fila e reprocesse com critério

Enviar o pedido ao ERP direto no webhook é frágil: se o ERP demorar ou cair, o pedido se perde. O caminho mais seguro é gravar o evento primeiro, processar depois:

1. O webhook só valida e grava o evento em uma fila (ou tabela) e responde rápido.
2. Um processo separado consome a fila e fala com o ERP.
3. Se falhar, tenta de novo com espera crescente (1 min, 5 min, 30 min...), com um limite de tentativas.
4. Depois do limite, o evento vai para uma fila de erros que gera alerta para uma pessoa.

Dois cuidados: nunca tente novamente em loop apertado (você pode derrubar o ERP que já está lento), e nunca descarte em silêncio um evento que falhou.

3. Não confie só no webhook: reconcilie

Webhooks podem falhar, atrasar ou nunca ser disparados. Por isso, além de ouvir eventos, tenha uma rotina de reconciliação: a cada poucos minutos, consulte a loja pelos pedidos das últimas horas e compare com o que existe no ERP. O que estiver faltando entra na fila. Isso transforma "perdemos um pedido sem saber" em "a rotina achou e corrigiu".

4. Estoque: envie movimentos, não o saldo

O erro clássico é a loja enviar "o saldo agora é 7" e o ERP gravar 7. Se duas vendas acontecem quase juntas, uma sobrescreve a outra e o estoque fica errado. Duas abordagens mais seguras:

• Defina uma fonte da verdade. Em geral é o ERP. A loja só lê o saldo, e as baixas viram pedidos que o ERP processa.
• Se precisar enviar alterações, envie o movimento ("saiu 1 unidade, motivo: pedido 123"), não o valor final. Assim, duas baixas simultâneas se somam, em vez de uma apagar a outra.

Em qualquer caso, publique para a loja um saldo disponível (físico menos reservado), não o saldo contábil.

5. Cuidado com ordem e concorrência

Dois eventos do mesmo pedido ("pago" e depois "enviado") podem chegar na ordem inversa. Se você processa na ordem de chegada, o status final pode ficar errado. Guarde a data ou a versão do evento e ignore o que for mais antigo do que o já aplicado. Evite também dois processos atualizando o mesmo pedido ao mesmo tempo sem algum tipo de trava ou versionamento.

6. Observe o que importa

Uma integração sem monitoramento só é descoberta quando o cliente reclama. Acompanhe, no mínimo:

• Idade do pedido mais antigo parado em cada etapa (recebido, enviado ao ERP, com nota).
• Tamanho da fila de erros e quanto tempo os itens ficam lá.
• Divergência de estoque entre os dois lados, em um relatório periódico.
• Falhas de emissão de nota, que travam a expedição.

Coloque um ID de correlação em cada pedido e registre-o em todos os logs. Quando algo falhar, você acompanha o caminho do pedido de ponta a ponta.

7. Teste o que dá errado, não só o que dá certo

Antes de ligar em produção, teste:

• o mesmo evento enviado duas vezes (não pode duplicar);
• o ERP indisponível durante o processamento (o pedido deve entrar depois);
• eventos fora de ordem;
• um pico de pedidos, simulado antes de datas como a Black Friday;
• um pedido com dados "estranhos" (CEP incompleto, produto sem SKU, caracteres especiais).

Reaproveite payloads reais (sem dados pessoais) para os testes. Eles costumam revelar campos que a documentação não cita.

Checklist rápido

• Cada pedido tem uma chave única e o processamento é idempotente.
• O webhook grava e responde, e o processamento é assíncrono.
• Há tentativas com espera crescente e uma fila de erros com alerta.
• Existe uma rotina de reconciliação.
• O estoque tem uma fonte da verdade e usa movimentos, não saldo.
• Eventos antigos não sobrescrevem os novos.
• Há métricas e um ID de correlação nos logs.
• Os cenários de falha foram testados.

Tem alguma situação que não está aqui, como pedidos com kits ou vários depósitos? Conte nos comentários que eu respondo.

Sou Rodrigo Goulart, da LDX Labs (ldxlabs.com.br), onde desenvolvemos sistemas sob medida e integrações para pequenas empresas.