Warehouses
O warehouse é a unidade que tem estoque. Ele se liga a uma ou mais políticas de entrega, e é essa ligação que determina de qual estoque um pedido é atendido quando o cliente escolhe endereço e modalidade.
Criar
POST /v1/batch/Warehouses
[
{
"externalReference": "CD-CENTRO",
"name": "CD Centro",
"shippingPolicyIds": [
"b3f1a2c4-5d6e-4f70-8a91-2b3c4d5e6f70",
"c4e2b3d5-6e7f-4a81-9b02-3c4d5e6f7a81"
]
}
]| Campo | Obrigatório | Observação |
|---|---|---|
externalReference | sim | código do CD/loja no seu ERP; usado pela publicação de estoque e por DELETE |
name | sim | nome exibido nas telas internas — é a chave de idempotência, ver aviso |
shippingPolicyIds | sim | GUIDs das políticas de entrega atendidas por este estoque |
Os GUIDs precisam já existir. O processador conta quantas políticas encontrou e
compara com quantas você mandou; se alguma não existir, o warehouse não é criado —
a operação volta como Warehouse_CreationFailed no seu webhook, com conflito de
política não encontrada. Peça os shippingPolicyId ao time Grocers antes de rodar a
carga. Veja Ativar uma loja.
O campo é obrigatório no corpo, mas aceita lista vazia ("shippingPolicyIds": []). Um
warehouse assim é criado normalmente e nunca atende pedido: não existe caminho
entre a escolha do cliente e aquele estoque. É a causa mais comum de “tenho estoque no
ERP e a loja diz esgotado”.
Warehouse é a exceção à regra de idempotência por externalReference. O processador
procura o warehouse existente pelo name dentro do tenant, não pelo
externalReference. Dois warehouses com o mesmo name e externalReference
diferentes não coexistem — o segundo POST atualiza o primeiro. E mudar só o name de
um warehouse existente cria um novo registro, deixando o antigo com o estoque órfão.
Mantenha name único e estável por warehouse, como se fosse a chave.
A atualização substitui a lista de políticas, não soma: as associações anteriores
são apagadas antes de gravar as novas. Mande sempre a lista completa de
shippingPolicyIds, não só as que mudaram.
Uma ShippingPolicy só pode estar ligada a um warehouse. Se você ligar a política
P ao warehouse B quando ela já estava ligada ao warehouse A, a associação com A
é removida sem aviso e sem erro — A para de atender aquela modalidade na hora. É a
forma mais rápida de derrubar uma loja inteira com um lote de warehouses aparentemente
inofensivo.
A relação é: um warehouse, várias políticas; uma política, um warehouse.
Quantos warehouses criar
| Cenário | Modelagem |
|---|---|
| Uma loja, um estoque | um warehouse ligado a todas as políticas daquele seller |
| Loja + CD de e-commerce | dois warehouses; o CD atende a política de entrega agendada, a loja atende as de expressa e retirada — políticas distintas, uma para cada |
| Múltiplas lojas por região | um warehouse por loja, cada um ligado às políticas da sua praça |
Como uma política só pode apontar para um warehouse, dois estoques que atendem a mesma modalidade no mesmo seller exigem duas ShippingPolicies — peça-as ao time Grocers na ativação, não tente resolver ligando os dois warehouses à mesma política.
A regra prática: crie um warehouse por local físico que tem contagem de estoque própria. Se dois pontos compartilham a mesma contagem no ERP, eles são um warehouse só na plataforma.
Remover
curl -X DELETE $GROCERS_API/v1/batch/Warehouses \
-H "Authorization: Basic $BASIC" \
-H "x-contractAccountId: $TENANT" \
-H "Content-Type: application/json" \
-d '["CD-CENTRO"]'Remover um warehouse derruba junto todo o estoque publicado nele. Para desativar uma operação temporariamente, zere as quantidades em vez de excluir o warehouse — a volta é muito mais barata.