Preço e estoque

O preço que aparece na página de um produto não é um número fixo. Ele depende da quantidade, de quem está comprando (visitante, cliente logado, cliente de um grupo B2B), do estado de entrega e das opções escolhidas. Esta seção reúne as rotas públicas da loja que respondem a essas perguntas, mais os dois recursos de retenção ligados ao preço e ao estoque: o alerta de preço e o aviso de volta ao estoque.

Como funciona

O fluxo típico de uma página de produto, em ordem:

1. Ler o produto

   A listagem e o detalhe do produto (seção de catálogo) já trazem price em centavos e as faixas de preço do produto.

2. Mostrar a tabela de faixas

   Escada de preços devolve "a partir de N unidades, R$ X cada". É a tabela de "compre mais, pague menos".

3. Recalcular a cada mudança de quantidade

   Quando o comprador altera a quantidade, chame Preço por quantidade. Ele já aplica faixas e regras B2B e devolve o total e a economia.

4. Preço por estado e opções

   Com o CEP resolvido para um estado, consulte Preço por estado. Ao escolher opções (cor, tamanho), Regras de opção diz o que está disponível.

5. Reter o comprador

   Se o preço está alto, Alerta de preço. Se o produto acabou, Aviso de volta ao estoque.

Conceitos-chave

Dinheiro

Todos os campos de preço desta seção são inteiros em centavos (unit_price, total_price, savings, base_price, price_centavos, target_price_cents). O produto também pode trazer price_str ("52.90"), mas só para exibição. Veja Ids, dinheiro e datas.

Quem pode ver o preço

Cada loja decide se o visitante (sem token) vê preços. Quando não vê, as rotas price, price-tiers, state-price e apply-exceptions devolvem os valores zerados e, onde existe o campo, price_redacted: true. A decisão não depende da rota, e sim da loja. Quem envia um token válido (qualquer cliente logado) sempre vê o preço. Se a loja exige login até para navegar, as rotas respondem 401 com {"error":"shopping_requires_login"}.

Escada de preços (faixas de quantidade)

Uma faixa é "a partir de lower_limit unidades, o preço unitário vale price". As faixas podem valer para todos, só para visitantes, só para logados ou só para um grupo de clientes. A rota mostra apenas as faixas que se aplicam a quem chama. A regra para escolher a faixa (a mais barata que se qualifica, ou a do maior patamar atingido) é uma configuração da loja; a tabela devolvida já respeita essa regra.

Preço B2B e preço por estado

Lojas B2B podem ter regras de preço por cliente ou grupo, listas de preços e preço negociado. Preço B2B mostra a origem do preço (source). O preço por estado é uma tabela de regras por UF; sem regra, vale o preço padrão.

Disponibilidade

O estoque do produto aparece no detalhe do produto (quantity, out_of_stock_action). Quando o lojista escolhe a ação S ("avisar quando voltar"), o comprador pode se inscrever com Aviso de volta ao estoque.

Endpoints

Erros comuns

• Mandar o slug no lugar do UUID. Estas rotas pedem o UUID de 36 caracteres. Com abc, a plataforma responde 500 com detail explicando que o valor não é um UUID (em português).
• Guardar price em cache no seu app. Ele muda com a quantidade e com o cliente. Recalcule ao mudar a quantidade ou ao logar.
• Tratar price_redacted como preço zero. Valores 0 com price_redacted: true significam "peça login", não "grátis".
• Esperar que o alerta de preço aceite qualquer valor. O alvo precisa ser maior que zero e menor que o preço atual.
• Pedir aviso de volta ao estoque de produto que ainda tem saldo. Responde 409 already_in_stock.
• Enviar o aviso de estoque sem e-mail. Visitante precisa informar email no corpo.

Próximos passos