Skip to Content
Documentação de integração da plataforma — em evolução contínua.
EstoqueConferir e diagnosticar

Conferir e diagnosticar

“O item não aparece na loja”

Siga na ordem — cada passo elimina uma causa e a maioria dos casos morre no passo 3 ou 4.

O produto existe?

curl $GROCERS_API/v1/batch/Products/PROD-114970 \
  -H "Authorization: Basic $BASIC" -H "x-contractAccountId: $TENANT"

Se voltar vazio, o lote falhou no processamento assíncrono. Confira o webhook de ProductWithSKUs_CreationFailed ou reenvie o lote.

O produto está ativo e visível?

active: true e displayInSite: true. Um item inativo responde na consulta acima normalmente — ele existe, só não é exibido.

Tem estoque publicado?

curl "$GROCERS_API/v1/batch/Warehouses/stock?warehouseExternalReference=CD-CENTRO" \
  -H "x-contractAccountId: $TENANT" | grep MAC-ESP-500

Essa rota não exige Authorization — só o x-contractAccountId. E a resposta traz skuReference (o reference do SKU), não o externalReference: filtre pelo campo certo. Veja Publicar estoque.

Sem retorno aqui, o problema é estoque, não catálogo.

O warehouse está ligado a uma política de entrega?

Warehouse sem shippingPolicyIds tem estoque que ninguém alcança. Essa é a causa mais frequente de “está tudo certo no ERP e a loja diz esgotado”.

Tem preço vigente?

Item sem preço vigente não é vendável, mesmo com estoque. Confira também as datas: um preço com startDateTime no futuro ainda não vale, e um com endDateTime no passado já saiu. Veja Tipos de preço.

Não perca tempo investigando “a política comercial certa”: a resolução do preço filtra por SKU e vigência, não por política. Se existe preço vigente para o SKU em qualquer política, ele vale.

“O estoque da loja está diferente do ERP”

Lembre que quantityAvailable é substituído a cada publicação. Divergência quase sempre significa que uma publicação não chegou ou chegou fora de ordem.

Verifique nesta ordem:

  1. A última publicação retornou 200? Um operationId na resposta confirma só que o lote foi aceito. O processamento em si pode ter falhado depois.
  2. Chegou webhook de falha? WarehouseSKU_CreationFailed indica que a chamada inteira foi recusada. Mas o inverso não vale: WarehouseSKU_Created confirma que o lote foi aceito, não que cada item entrou — o core aceita o lote com 200 mesmo com SKU inexistente ou warehouse errado no meio, e a lista de erros não é repassada. Só a consulta de stock prova o que foi aplicado.
  3. O SKU do payload existe mesmo? Publicar estoque para um skuExternalReference que não está no catálogo falha silenciosamente do ponto de vista do ERP — o lote é aceito e o item nunca aparece.
  4. Há mais de um processo publicando? Job agendado e evento em tempo real competindo pelo mesmo SKU produzem exatamente esse sintoma, de forma intermitente.

Reserva versus disponível

Um mal-entendido comum: quantityReserved não é descontado de quantityAvailable pela plataforma. Os dois números vêm do seu ERP e são exibidos como você os enviou.

Se o seu ERP já desconta a reserva do disponível, mande a reserva como 0 para não contar duas vezes. Se ele mantém os dois separados, envie quantityAvailable já líquido — o valor que pode ser vendido agora.

Enviar quantityAvailable bruto (incluindo o que está reservado) é a receita para vender o que não existe e cancelar pedido na separação.

Carga total de reconciliação

Recomendado uma vez por dia, em horário de baixo movimento:

Publicar só os divergentes reduz o volume e deixa o log de reconciliação com o valor real: a lista de itens que estavam errados.

Publicar estoqueTipos de preço