Estoque do produto
Ajusta o saldo de estoque de um produto (definir o total ou somar uma variação), com as regras do modelo de estoque.
O estoque de um produto é a quantidade disponível para venda. Esta página mostra como alterar o saldo (PUT). Antes de usá-la, leia o modelo de estoque em Preço e estoque do produto.
Ajustar o estoque
/api/v1/admin/products/{id}/stockAdminDefine ou ajusta o estoque de um produto
Muda o saldo de um produto e devolve o produto inteiro já atualizado. Use para refletir uma contagem de inventário (set_to) ou uma entrada ou saída de mercadoria (delta). A conta de delta é feita pelo banco, em uma só operação, então duas chamadas ao mesmo tempo somam as duas.
Efeitos colaterais: o evento de estoque alterado é emitido, a vitrine e a busca são atualizadas, o razão de estoque da loja (quando já existe para o produto) acompanha o novo saldo, e a mudança fica no registro de atividades (com o reason, se enviado).
Path parameters
iduuidobrigatórioCorpo da requisição
set_tointeger{"set_to": 25} deixa o estoque em 25. Negativo vira 0.deltainteger5 para uma entrada, -3 para uma saída. O resultado nunca fica abaixo de 0.adjustmentintegerdelta. Se os dois vierem, precisam ter o mesmo valor.quantityintegerabsolute. Sozinho, é recusado.absolutebooleanquantity, true significa total e false significa variação.reasonstringquebra ou contagem), gravado no registro de atividades.Envie uma destas formas: set_to, delta (ou adjustment), ou quantity com absolute. Qualquer outra combinação é recusada com 400 stock_intent_required.
Exemplo de requisição
curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/stock" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"set_to": 25,
"reason": "contagem"
}'Para somar ou subtrair em vez de definir o total:
curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/stock" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"delta": -3,
"reason": "quebra"
}'Resposta
{
"id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
"sku": "MOCH-001",
"name": "Mochila Urbana",
"price": 4990,
"price_str": "49.90",
"status": "A",
"track_inventory": true,
"quantity": 22,
"amount": 22,
"low_stock_alert": 5,
"out_of_stock_action": "S",
"min_quantity": 0,
"max_quantity": 0,
"quantity_step": 1,
"sale_unit": "un",
"updated_at": "2026-10-11T20:56:23.894112Z"
}Response fields
quantityintegeramountintegerquantity, com outro nome.track_inventorybooleanlow_stock_alertintegerout_of_stock_actionstringNBSpriceintegerA resposta é o produto completo, com os mesmos campos de Consultar produto; acima estão só os que interessam ao estoque.
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo sem a intenção ({}, ou só campos desconhecidos). | {"error":"stock_intent_required","detail":"o corpo não trouxe número de estoque nenhum. Use {\"set_to\": N} ..."} |
| 400 | Só quantity, sem absolute. | {"error":"stock_intent_required","detail":"\"quantity\" sozinho não diz se é o TOTAL NOVO ..."} |
| 400 | Intenções misturadas (set_to com delta, quantity com delta, delta diferente de adjustment). | {"error":"stock_intent_required","detail":"..."} |
| 400 | Número decimal ou texto onde se espera inteiro. | {"error":"invalid request body","detail":"json: cannot unmarshal number 10.5 into ..."} |
| 400 | O {id} não é um UUID (por exemplo, um SKU). | {"error":"invalid product id","detail":"..."} |
| 404 | Nenhum produto ativo com esse id. | {"error":"product not found","detail":"..."} |
| 401 / 403 | Sem token / sem manage_features. | {"error":"insufficient privileges","required":"manage_features"} |
As mensagens de detail dos 400 e 404 vêm em português, como o servidor as devolve.
Veja também
- Preço e estoque do produto: o modelo de estoque explicado do zero.
- Faixas de preço por quantidade
- Atualizar produto:
low_stock_alert,out_of_stock_actione as regras de quantidade.