Preço e estoque do produto

Além do cadastro básico (nome, preço, categoria), um produto tem quatro assuntos comerciais que esta seção cobre: as faixas de preço por quantidade (preço de atacado), o estoque (quanto há para vender e o que a loja faz quando acaba), a recorrência (assinatura e compra programada) e a embalagem de envio (a caixa externa usada no cálculo do frete).

Todas as rotas daqui ficam em /api/v1/admin. O preço base e as regras de quantidade do produto são alterados no cadastro do produto (Atualizar produto).

Como funciona

Um fluxo típico de um ERP ou de um sistema de preços que alimenta a loja:

1. Definir o preço base

   O preço do produto (centavos) é gravado no cadastro dele. Veja Criar produto e Atualizar produto.

2. Publicar a tabela de atacado

   Envie as faixas de preço por quantidade de uma vez com PUT, ou uma a uma com POST.

3. Manter o estoque em dia

   A cada contagem ou movimentação, ajuste o estoque: set_to para um inventário, delta para entradas e saídas.

4. Opcionais

   Se a loja vende por assinatura, configure a recorrência. Se usa o cálculo de frete por caixa, grave a embalagem de envio.

Conceitos-chave

O modelo de estoque

Estes são os campos do produto que descrevem o estoque. Todos aparecem na resposta de Consultar produto:

track_inventory. Com true, o saldo manda: o carrinho recusa uma quantidade maior que quantity (erro de estoque insuficiente), a menos que out_of_stock_action seja B. Com false e quantity igual a 0, o produto é ilimitado (típico de produto digital). Com false e quantity maior que 0, a loja ainda limita a compra a esse saldo.

out_of_stock_action. O que acontece quando o saldo é zero:

low_stock_alert. Um produto é considerado de estoque baixo quando controla estoque, tem saldo maior que 0 e menor ou igual a esse limite. Na lista de produtos da administração, o filtro low_stock=true mostra esses produtos.

Frações. Produtos vendidos por peso ou volume (kg, l) podem ter saldo fracionado. As rotas de estoque desta seção trabalham em unidades inteiras.

Quem muda o saldo. Fora as rotas desta seção, 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; as rotas desta seção mexem no saldo do produto.

Variações. Um produto com variações (cor, tamanho) tem estoque próprio em cada variação. Essas variações não são tratadas nesta seção.

Faixas de preço por quantidade

Preço de atacado: "a partir de N unidades, o preço é X". Pode valer para todos, só para visitantes, só para clientes logados ou só para um grupo. O preço da faixa vale para todas as unidades do pedido, e uma faixa nunca cobra mais que o preço do produto. Os detalhes estão em Faixas de preço por quantidade.

Privilégios

Sem o privilégio a resposta é 403 e o corpo diz qual faltou. Com o recurso desligado, a resposta é 403 {"error":"module_disabled","module":"..."}.

Identificadores

O {id} é sempre o UUID do produto, nunca o SKU. Para o produto mestre e o produto de seller, veja Produtos.

Endpoints

Auth: Admin é o administrador (Bearer).

Erros comuns

• Enviar quantity sozinho para mudar o estoque. A API recusa com 400 stock_intent_required. Use set_to (total) ou delta (variação).
• Esperar que o ajuste de estoque use manage_catalog. A rota exige manage_features. Um usuário só de catálogo recebe 403.
• Mandar reais em vez de centavos numa faixa. O price da faixa é um inteiro em centavos: 49.90 é recusado, envie 4990.
• Achar que o PUT das faixas é parcial. Ele apaga todas as faixas e grava só as que você mandou. Para acrescentar uma, use POST.
• Esperar que o POST de uma faixa com lower_limit 1 mude o preço do produto. Só o PUT faz isso.
• Usar o updated_at antigo na embalagem de envio. A gravação volta 409. Releia e grave de novo.
• Esquecer que recorrência e embalagem dependem de recursos da loja. O 403 module_disabled não é problema de permissão do usuário.

Próximos passos