Preço e estoque do produto
Como o estoque de um produto é modelado na API legada, como ler o saldo com um token de app e o mapa da rota.
Além do cadastro básico (nome, preço, categoria), um produto tem um assunto comercial que esta seção cobre pela API legada, compatível com a Venddor 1.0: o estoque, isto é, quanto há para vender. O preço base e as regras de quantidade do produto são lidos e alterados no cadastro do produto (Consultar produto e Atualizar produto).
Como funciona
Um fluxo típico de um conector de ERP que acompanha o estoque da loja:
- Obter o token de app
O app é cadastrado no portal de desenvolvedores da loja e recebe um token com o escopo
read_inventory. Veja Produtos por token de app. - Ler o saldo
Chame a leitura de saldo com o id do produto. A resposta traz o
quantityem unidades inteiras. - Alterar o estoque, se preciso
O estoque é alterado no cadastro do produto, com Atualizar produto e o campo
amount.
Conceitos-chave
O modelo de estoque
Estes são os campos do produto que descrevem o estoque. Todos aparecem na resposta de Consultar produto:
| Campo | Tipo | O que é |
|---|---|---|
amount | inteiro | O saldo: quantas unidades há para vender. Se o saldo tiver fração (produto vendido por peso), a fração é descartada. |
tracking | Y ou N | Se a loja controla o estoque deste produto. |
min_qty | inteiro | Quantidade mínima por compra. 0 = sem mínimo. |
max_qty | inteiro | Quantidade máxima por compra. 0 = sem máximo. |
qty_step | inteiro | Múltiplo de compra. Padrão 1. |
tracking. Com Y, o saldo manda: o carrinho recusa uma quantidade maior que amount (erro de estoque insuficiente). Com N e amount igual a 0, o produto é ilimitado (típico de produto digital).
Quem muda o saldo. Além do cadastro do produto, o saldo cai quando um pedido é feito e volta quando o pedido é cancelado ou falha (veja Pedidos). Em lojas com depósitos, o produto também tem saldo por depósito; a leitura desta seção devolve o saldo do produto.
Variações. Um produto com variações (cor, tamanho) tem estoque próprio em cada variação (veja Variações e opções).
Privilégios
| Ação | Credencial |
|---|---|
| Ler o saldo por token de app | Token de app com o escopo read_inventory |
Sem o escopo a resposta é 403 e o corpo diz qual faltou.
Identificadores
O {id} é sempre o UUID do produto, nunca o código. Para o modelo do produto, veja Produtos.
Endpoints
Auth: App é o token de app (vat_...).
| Método | Rota | O que faz | Auth | Página |
|---|---|---|---|---|
| GET | /api/admin/products/{id}/inventory | Lê o saldo (token de app) | App | Estoque |
Erros comuns
- Usar um JWT de usuário na leitura de saldo. A rota só aceita token de app; um JWT responde 401
app_token_required. - Pedir um token sem o escopo
read_inventory. A resposta é403 missing_scope. - Esperar 404 para um produto que não existe. A leitura de um UUID inexistente volta
200comquantityzero. - Ler
amountcomo se fosse exato para produtos fracionados. O saldo é inteiro e arredonda para baixo.