Integrando ERP com NuvemShop via API: Estoque, Pedidos e Precificação em Tempo Real

O custo de operar sem integração ERP-NuvemShop

Lojas que crescem sem integração entre ERP e plataforma de e-commerce chegam a um ponto onde o custo operacional da ausência de integração supera qualquer economia inicial. Os sintomas são clássicos: estoque divergente entre loja e ERP com vendas de produtos sem estoque físico, pedidos copiados manualmente de uma tela para outra, preços desatualizados por dias ou semanas após reajuste no ERP.

Para a NuvemShop, a solução técnica é construir uma camada de integração que usa a API REST da plataforma em combinação com webhooks para manter as duas pontas sincronizadas em tempo real — ou quase isso.

A direção da sincronização determina qual sistema é a fonte da verdade para cada entidade:

• Estoque: ERP é fonte — atualiza NuvemShop quando posição de estoque muda
• Pedidos: NuvemShop é fonte — envia pedido para ERP ao confirmar compra
• Preços: ERP é fonte — atualiza NuvemShop quando tabela de preços é alterada
• Produtos: ERP é fonte — cria e atualiza cadastros na NuvemShop automaticamente

Sincronização de estoque: ERP para NuvemShop

O fluxo de atualização de estoque funciona da seguinte forma: quando o ERP registra uma movimentação de estoque (entrada, saída, ajuste), um evento é disparado para o serviço de integração, que então chama a API da NuvemShop para atualizar a quantidade disponível da variante correspondente.

O endpoint para atualizar estoque de uma variante na NuvemShop:

PUT /v1/{store_id}/products/{product_id}/variants/{variant_id}
Content-Type: application/json

{
  "stock": 42,
  "stock_management": true
}

O mapeamento entre SKU do ERP e variant_id da NuvemShop precisa ser mantido em uma tabela de referência cruzada no serviço de integração. A melhor abordagem é armazenar o SKU do ERP no campo sku da variante NuvemShop na criação do produto, e usar esse campo como chave de busca:

# Buscar variante por SKU
GET /v1/{store_id}/products?q=SKU-ERP-001

# Ou listar todas as variantes e filtrar por SKU
GET /v1/{store_id}/products/{product_id}/variants

Recepção de pedidos via webhook

Quando uma venda é confirmada na NuvemShop, o webhook order/created envia os dados completos do pedido para o endpoint configurado no serviço de integração. Este serviço então formata o pedido no padrão do ERP e realiza a inserção via API ou integração direta com o banco do ERP.

O payload do webhook order/created inclui:

• Dados do cliente (nome, CPF, endereço de entrega e cobrança)
• Itens do pedido com produto, variante, quantidade e preço unitário
• Forma de pagamento, parcelas e status de aprovação
• Código de rastreamento se aplicável
• Total do pedido com descontos e frete

O mapeamento de cliente entre NuvemShop e ERP geralmente usa CPF ou e-mail como chave primária. Se o cliente não existir no ERP, crie-o automaticamente a partir dos dados do webhook antes de inserir o pedido.

Atualização de preços e tabelas de preço

Para lojas com tabela de preços dinâmica no ERP — reajustes periódicos, promoções, variação cambial — a integração precisa propagar as mudanças de preço da NuvemShop de forma eficiente sem consumir todo o rate limit da API.

A estratégia mais eficiente é processar atualizações de preço em lote durante horários de baixo tráfego (madrugada ou início da manhã), usando a API em paralelo com controle de concorrência:

# Atualizar preço de uma variante
PUT /v1/{store_id}/products/{product_id}/variants/{variant_id}

{
  "price": "199.90",
  "promotional_price": "149.90"
}

# Para múltiplos produtos, itere e monitore rate limit
# Respeite 500 req/hora com um sleep entre chamadas
# Exemplo: 500 produtos = ~4 min com 1req/500ms

Monitoramento da integração e tratamento de erros

Uma integração ERP-NuvemShop em produção precisa de monitoramento ativo. Os erros mais comuns que precisam ser detectados e tratados automaticamente:

• 429 Too Many Requests: rate limit atingido — implemente retry com exponential backoff
• 404 Not Found: produto ou variante não existe mais na NuvemShop — marque o mapeamento como inválido e notifique o time
• 422 Unprocessable Entity: dado malformado — logar o payload completo para debugging
• Webhook não recebido: configure health check periódico disparando um pedido de teste e verificando se o webhook chegou

Mantenha um log de todas as sincronizações com status, payload enviado e resposta recebida. Logs estruturados em JSON facilitam análise e alertas em ferramentas como Elastic Stack ou Datadog. Uma integração silenciosa que falha sem aviso pode acumular divergências por horas antes de alguém perceber.