Publicar estoque

Publicar a quantidade

POST /v1/batch/Warehouses/sku


[
  {
    "warehouseExternalReference": "CD-CENTRO",
    "items": [
      {
        "skuExternalReference": "114970",
        "quantityAvailable": 240,
        "quantityReserved": 12
      },
      {
        "skuExternalReference": "114970-CS",
        "quantityAvailable": 18,
        "quantityReserved": 0
      }
    ]
  }
]

Campo	Significado
`warehouseExternalReference`	em qual warehouse essa quantidade está
`skuExternalReference`	o SKU (mesma referência enviada no catálogo)
`quantityAvailable`	quantidade vendável — é o que a vitrine considera
`quantityReserved`	quantidade separada para pedidos em andamento

quantityAvailable é um valor decimal. Itens pesáveis podem ter quantidade fracionada (12.480 kg), e a plataforma respeita a casa decimal na hora de bloquear a venda.

O aceite volta como WarehouseSKU_Created, com o lote inteiro no data — uma notificação por grupo de até 100 blocos, não uma por SKU. E ele confirma que a chamada foi aceita, não que cada item entrou: o core devolve 200 mesmo com falha parcial e a lista de erros não é repassada. Confira os números com a consulta de estoque mais abaixo nesta página.

Substituição, não incremento

Cada envio substitui a quantidade daquele par warehouse + SKU. A API não soma nem subtrai: você publica o número absoluto que o ERP tem naquele instante.

Isso torna a ordem de chegada relevante. Se dois processos publicam o mesmo SKU em paralelo, vence o último a ser processado — que pode não ser o mais recente. Serialize a publicação por SKU, ou publique sempre a partir de uma única fonte.

Frequência de sincronização

Estratégia	Quando usar	Custo
Delta a cada movimento	operação com giro alto e ERP que emite evento de estoque	baixo por chamada, exige fila confiável
Delta agendado (5–15 min)	maioria das operações	equilíbrio recomendado
Carga total diária	catálogo pequeno ou operação com pouca variação	simples, mas deixa a loja desatualizada durante o dia

O padrão que funciona bem na prática é delta a cada 10 minutos + carga total de madrugada — o delta mantém a loja viva e a carga total corrige qualquer divergência acumulada.

Zerar um item

Para tirar um item de venda por falta, publique quantityAvailable: 0. O que acontece na vitrine depende de displayInSoldOut no produto:

`displayInSoldOut: true`

O item continua visível, marcado como esgotado. Bom para não perder SEO e para o cliente saber que você trabalha com aquele produto.

`displayInSoldOut: false`

O item some da vitrine enquanto estiver zerado.

Remover a quantidade publicada


curl -X DELETE $GROCERS_API/v1/batch/Warehouses/sku \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT" \
  -H "Content-Type: application/json" \
  -d '[{"warehouseExternalReference":"CD-CENTRO","skuExternalReferences":["114970","114970-CS"]}]'

O campo é skuExternalReferences — plural, e uma lista. É o único lugar da API em que a referência do SKU aparece no plural. Enviar skuExternalReference com uma string não dá erro: o campo não existe no contrato, chega null no serviço e nada é removido.

Remover é diferente de zerar: o registro deixa de existir naquele warehouse. Use para descontinuar um item em uma unidade específica; para falta temporária, use 0.

Consultar o que está publicado

curl


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

A resposta não usa os mesmos nomes do payload de publicação. Você publica skuExternalReference e quantityAvailable; a consulta devolve skuReference e totalQuantityAvailable. E quantityReserved não vem nessa resposta — não existe no contrato de retorno.

Consequência prática: um script de reconciliação que monta o mapa por skuExternalReference recebe undefined em todas as chaves e classifica o catálogo inteiro como divergente.

Campo da resposta	O que é
`skuReference`	o campo `reference` do SKU (referência interna), não o `externalReference`
`skuName`	o `name` do SKU
`warehouseName`	nome do warehouse
`warehouseExternalReference`	a referência que você enviou na publicação
`totalQuantityAvailable`	soma de `quantityAvailable` dos registros ativos daquele SKU no warehouse

Se você precisa casar o retorno com o externalReference que enviou, mantenha reference e externalReference iguais no cadastro do SKU, ou guarde o de-para do seu lado.

Esta rota é anônima: não exige Authorization, só x-contractAccountId. É por isso que o curl acima não tem o header Authorization.

Esse é o retrato do que a plataforma tem — sempre a primeira coisa a conferir quando o ERP e a loja discordam. Veja Conferir e diagnosticar.