Por que vendo produto que não tenho em estoque?

Porque o saldo publicado na loja é uma cópia com atraso do saldo do ERP, e você vende no mesmo minuto em mais de um canal. A mitigação é reduzir a latência da sincronização, trabalhar com estoque virtual menor que o real e reservar saldo no momento do pedido.

Webhook ou consulta periódica, qual é melhor?

Webhook para eventos que precisam ser rápidos, como pedido novo e pagamento aprovado. Consulta periódica para volumes grandes e para reconciliação. Na prática se usa os dois, porque webhook se perde e a varredura periódica é a rede de segurança.

Quanto tempo leva uma integração dessas?

Depende quase inteiramente da qualidade do cadastro e da API do ERP, não da loja. Cadastro limpo com SKU único dos dois lados e ERP em nuvem com API documentada é um projeto curto; de-para bagunçado e ERP sem API viram a maior parte do esforço.

Como integrar o ERP com o e-commerce sem quebrar o estoque

A integração entre ERP e e-commerce se resume a quatro objetos que atravessam a fronteira: produto/SKU, estoque, pedido e nota fiscal. Cada um tem uma direção de fluxo, uma frequência e um modo de falha próprio, e a maioria dos projetos que "quebram o estoque" na verdade errou no primeiro deles.

O SKU é a chave, e o de-para é o inferno

Nada funciona antes de existir um identificador único que os dois sistemas reconheçam. O ERP chama de código do produto, a loja chama de SKU, o marketplace cria um código próprio, e o comprador cadastrou o mesmo item três vezes com grafias diferentes.

Os problemas concretos:

Códigos diferentes dos dois lados. Vira uma tabela de de-para que alguém precisa manter. Toda linha errada nessa tabela é um item que baixa o estoque do produto errado.
Grade de variações. Camiseta azul tamanho M é um SKU no e-commerce e pode ser um produto com característica no ERP. Se o mapeamento for feito no nível do produto pai, o estoque some.
Kit e combo. Vendido como um item na loja, composto por três itens no ERP. A baixa precisa explodir a composição, e a disponibilidade do kit é o menor saldo entre os componentes.
Unidade de medida. Loja vende por unidade, ERP controla por caixa com 12. Fator de conversão errado gera divergência silenciosa que só aparece no inventário.
Item inativo com pedido em aberto. Produto descontinuado no ERP mas ainda publicado na loja.

A regra que evita metade dos incidentes: eleja o ERP como dono do cadastro e trate a loja como destino. Cadastro criado na loja e replicado para o ERP quase sempre vira duplicidade.

Estoque: reservado não é disponível

O saldo que a loja publica nunca é o saldo do ERP em tempo real. É uma cópia com atraso. Quanto maior o atraso e quanto mais canais vendem do mesmo pote, maior a chance de vender o que não existe.

Três conceitos precisam estar separados no modelo de dados:

Físico: o que está no depósito.
Reservado: alocado para pedidos já feitos e ainda não faturados.
Disponível para venda: físico menos reservado, menos o buffer de segurança.

O caso clássico de ruptura: o mesmo item publicado na loja própria, no Mercado Livre e em mais um marketplace. Três canais leem 2 unidades disponíveis. Três canais vendem. Você deve 3 e tem 2.

As mitigações que funcionam, em ordem de custo:

Buffer por canal. Publicar menos do que se tem. Item com 10 unidades vai como 8. Perde-se venda de cauda longa, evita-se cancelamento.
Estoque virtual por canal. Dividir explicitamente o saldo entre canais. Simples de entender, ruim para giro.
Reserva no ato do pedido. O pedido reserva no ERP antes de confirmar, e o saldo é recalculado e publicado imediatamente.
Sincronização por evento. Toda movimentação no ERP (venda, entrada, ajuste, transferência) publica atualização nos canais em segundos, não a cada hora.
Prioridade de canal. Quando falta, quem tem prioridade fica com a unidade e o outro pedido entra em tratamento manual.

Reduzir a janela de sincronização de 60 minutos para 2 minutos costuma resolver mais do que qualquer regra sofisticada de rateio.

Pedido: o objeto que duplica

O pedido nasce na loja e precisa chegar ao ERP com status, itens, valores, frete, forma de pagamento e dados do cliente. Aqui o problema não é o formato, é a entrega repetida.

Plataformas de e-commerce e gateways reenviam webhook quando não recebem confirmação rápida. Sem defesa, o mesmo pedido entra duas ou três vezes no ERP, com estoque baixado em dobro e duas notas emitidas.

A defesa é idempotência: guardar o identificador do pedido na origem, com restrição de unicidade no banco, e tratar uma segunda chegada como atualização e não como criação. A mesma lógica vale para eventos de mudança de status, que costumam chegar fora de ordem (o evento de "faturado" pode chegar antes do evento de "pago" numa retentativa).

Um detalhe frequentemente esquecido: status não é sinônimo entre os sistemas. "Aguardando pagamento" na loja, "orçamento" no ERP, "separação" no WMS. Escreva a tabela de tradução de status antes de escrever a primeira linha de código, e defina o que acontece com status que não tem correspondente.

Nota fiscal e o caminho de volta

Emitir a nota é responsabilidade do ERP. O que quase sempre falta no projeto é o retorno: número, série, chave de acesso, link do DANFE e código de rastreio precisam voltar para a loja, para o e-mail do cliente e para o marketplace, que muitas vezes exige a chave para liberar o repasse.

Também precisam existir os caminhos reversos:

Cancelamento de pedido: devolve reserva e saldo, cancela a nota dentro do prazo legal.
Devolução: gera nota de entrada, devolve estoque físico e reabre a disponibilidade.
Troca: é devolução mais nova saída, não uma edição do pedido original.

Devolução mal tratada é a segunda maior fonte de divergência de saldo, atrás só de venda simultânea multicanal.

Tabela dos quatro objetos

Objeto	Direção do fluxo	Frequência	Falha típica	Mitigação
Produto/SKU	ERP para loja	Sob demanda ou diária	De-para errado, variação sem mapeamento	ERP como dono do cadastro, validação do de-para
Estoque	ERP para todos os canais	Contínua, alguns minutos	Venda sem saldo em multicanal	Buffer, reserva no pedido, sincronização por evento
Pedido	Loja para ERP	Por evento	Webhook duplicado gera pedido duplicado	Chave de idempotência com unicidade no banco
Status do pedido	Nos dois sentidos	Por evento	Eventos fora de ordem	Máquina de estados com transições válidas
Nota fiscal	ERP para loja e marketplace	Por evento	Chave não volta e o repasse trava	Retorno obrigatório de número, chave e DANFE
Devolução	Loja para ERP	Sob demanda	Estoque não retorna	Fluxo reverso explícito com nota de entrada

Plataformas como VTEX, Shopify, WooCommerce, Nuvemshop e Mercado Livre mudam o formato dessas trocas, mas não mudam a lista de objetos nem os modos de falha.

Arquitetura: fila, retry e reconciliação

O desenho que aguenta produção tem quatro peças:

Fila com retry e dead letter. Nenhuma integração deve chamar o ERP direto do webhook. O evento entra numa fila, é processado com tentativas espaçadas e, se falhar todas, vai para uma fila de erro visível. Sem dead letter, mensagem perdida vira pedido que ninguém viu.

Polling como rede de segurança. Webhook se perde: instabilidade, deploy, certificado vencido. Uma varredura periódica que busca pedidos criados nas últimas horas e compara com o que entrou no ERP pega o que escapou.

Reconciliação noturna. Um job que compara, item a item, o saldo do ERP com o saldo publicado em cada canal e reporta divergências acima de um limite. Esse relatório é o que mostra o problema antes do cliente mostrar.

Log de auditoria. Cada mensagem trocada, com carga, horário, resultado e tentativa. Quando o lojista diz "esse pedido não chegou", o log responde em minutos, não em meio dia de investigação.

Vale dizer o que uma integração não conserta: cadastro ruim. Se o mesmo produto existe em duplicidade no ERP, com unidades trocadas e saldo negativo, a integração vai replicar isso mais rápido e em mais canais. Limpeza de cadastro antes do projeto costuma ser o item de maior retorno.

Em orçamentos desse tipo, o custo raramente está no número de endpoints. Está na quantidade de exceções do negócio: kit, backorder, venda por encomenda, filiais com estoques separados, marketplace com regra própria de faturamento. Vale listar essas exceções antes de pedir preço a qualquer fornecedor.