Estoque compartilhado entre marketplaces parece coisa simples: vendeu em ML, sistema atualiza Shopee e Magalu. Mas no detalhe, é um dos sistemas mais complexos de qualquer ERP de e-commerce — porque envolve race condition, timeout de API, webhook duplicado e idempotência fiscal.

Esse texto abre os 5 erros que travam a maioria das integrações multi-marketplace, e como uma integração robusta resolve.

O cenário ideal (que ninguém entrega de primeira)

Você tem 100 unidades de um SKU. Está publicado em ML, Shopee e Magalu, todos mostrando 100 disponíveis. Cliente compra em ML às 14:00:00. Em milissegundos:

  1. ML processa pagamento
  2. ML envia webhook pro seu sistema
  3. Sistema decrementa estoque interno (100 → 99)
  4. Sistema envia update pra Shopee API (99)
  5. Sistema envia update pra Magalu API (99)
  6. Cliente em Shopee tenta comprar às 14:00:01 → vê 99, compra ok

Em 1 segundo, tudo sincronizado. Funciona em condição ideal. Mas em produção, raramente é ideal.

Erro 1: Race condition em vendas simultâneas

Cenário: cliente A compra em ML às 14:00:00. Cliente B compra em Shopee às 14:00:00. Os dois webhooks chegam ao seu sistema ao mesmo tempo, processam em paralelo, ambos veem estoque=100 e decrementam pra 99. Você vendeu 2 unidades, debitou só 1. Em alguns dias, vai vender mais que tem.

Solução: lock pessimista no SKU durante update. Em PostgreSQL: SELECT ... FOR UPDATE na linha do produto. Em Redis: lock distribuído com expire de 5s.

0,3%
é a taxa de race condition em sellers acima de 50 vendas/dia sem lock pessimista

Erro 2: Webhook duplicado processado 2x

Marketplaces re-enviam webhook se não recebem 200 em <5s. Se seu sistema demora 6s pra processar, ML re-envia, e você processa 2 vezes — debitando estoque 2x da mesma venda.

Solução: idempotência via dedupe key. Salva o ID da venda numa tabela e ignora se já processado. Aumenta chance de race? Não, se você usa transação atômica:

BEGIN;
INSERT INTO processed_webhooks (id) VALUES ('venda_xxx')
  ON CONFLICT (id) DO NOTHING;
-- se conflito, pula. Se não, processa normal.

Erro 3: API timeout durante update

Você manda update pra Shopee. API demora. Timeout em 30s. Você não sabe se a API processou ou não. Manda de novo. Se processou, agora debitou 2x.

Solução: idempotency key no header (Shopee suporta). Mesmo update enviado 2x conta 1x.

Em 2026 todas as 3 APIs (ML, Shopee, Magalu) suportam idempotency key. Quem não usa fica refém de timeout — em pico de venda, 5-10% das tentativas dão timeout.

Erro 4: Update vence webhook (ordem trocada)

Você vende em ML às 14:00:00 (decrementa 100 → 99). Estoque chegou em 99. Mas antes do webhook ML chegar no seu sistema, vem um webhook do Magalu com "última info do estoque: 100" (info defasada do Magalu). Seu sistema atualiza pra 100. Webhook do ML chega depois e cai no esquecimento.

Solução: timestamp na atualização. Toda update vem com timestamp; só aplica se o timestamp é mais recente que o último visto. Se for mais antigo, descarta.

Erro 5: Falha silenciosa em 1 marketplace

Sistema vende em ML. Atualiza ML ok. Atualiza Shopee ok. Atualiza Magalu — falhou (API caiu). Você não sabe. Magalu fica com estoque desatualizado.

Solução: circuit breaker + dead letter queue. Falhou 3x → marca SKU como "dessincronizado" → envia pra fila de retry → operador é notificado.

A arquitetura que aguenta

Webhook ML → Cola de Eventos (Upstash QStash)
              ↓
         Worker idempotente (lock + dedupe)
              ↓
         Estoque interno
              ↓
         Update paralelo: Shopee API + Magalu API
              ↓
         Sucesso? Audit log. Falha? DLQ.

Componentes-chave:

  • Cola assíncrona: webhook responde 200 em <100ms, processa no worker
  • Lock pessimista: por SKU, expira em 5s
  • Idempotency key: dedupe + retry seguro
  • DLQ (dead letter queue): falhas vão pra revisão manual

Estoque consistente em multi-marketplace é problema de engenharia, não de planilha.

Como o EVA Pro implementa

A arquitetura do EVA Pro pra estoque compartilhado:

  • Webhook receiver em /api/webhooks/{marketplace} responde 200 em <50ms
  • Cola Upstash QStash processa em segundo plano
  • Lock distribuído Redis por SKU
  • Update paralelo pros outros 2 marketplaces (Promise.all com timeout)
  • DLQ + Sentry capturam falhas pra revisão
  • Reconciliação noturna confere consistência (cron diário audita estoque real vs esperado)

Resultado: 99,7% de consistência em sellers acima de 1k vendas/dia. Sem isso, fica em ~92-94%.

Próximos passos: sua integração já tem lock pessimista e idempotency key? Testa o EVA Pro grátis — conecta os 3 marketplaces e roda auditoria de consistência no primeiro acesso.