API atual/Referência completa/Preço e estoque

GETPreço por quantidade

Calcula o preço unitário e o total de um produto para uma quantidade, aplicando faixas e regras B2B.

Use esta rota na página do produto, toda vez que o comprador muda a quantidade. Ela devolve o preço unitário que vale para essa quantidade, o total e quanto o comprador economiza em relação ao preço base. O cálculo considera as faixas de preço do produto e as regras de preço B2B do cliente; vence o menor preço. Nada é gravado: é só uma consulta.

A resposta nunca é guardada em cache (Cache-Control: no-store), porque depende de quem chama.

GET/api/v1/storefront/products/{id}/pricePública

Calcula o preço de um produto para uma quantidade

O token é opcional. Sem token o comprador é tratado como visitante; com token, valem as faixas do grupo dele e as regras B2B.

Parâmetros de caminho

iduuidobrigatório

Id do produto (UUID completo).

Parâmetros de consulta

quantityintegerpadrão: 1

Quantidade desejada. Valor ausente, não numérico, zero ou negativo é ignorado e vale 1.

Cabeçalhos

Authorizationstring

Bearer $TOKEN de um cliente logado. Opcional.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/price?quantity=3"

Resposta

200Preço calculado

json

{"unit_price":5290,"total_price":15870,"quantity":3,"tier_applied":false,"savings":0}

Com uma faixa aplicada (compra de 5 unidades, faixa de R$ 45,00):

200Faixa aplicada

json

{"unit_price":4500,"total_price":22500,"quantity":5,"tier_applied":true,"tier_id":"7c1e5b52-1f0b-4f88-8d9e-2d6a0a7e1a10","savings":3950}

Visitante em loja que esconde preços:

200Preço escondido

json

{"unit_price":0,"total_price":0,"quantity":3,"tier_applied":false,"savings":0,"price_redacted":true}

Campos da resposta

unit_priceinteger

Preço de uma unidade, em centavos, para a quantidade pedida.

total_priceinteger

unit_price vezes quantity, em centavos.

quantityinteger

Quantidade usada no cálculo (já corrigida para 1 se o valor enviado era inválido).

tier_appliedboolean

true quando uma faixa de quantidade ou regra B2B baixou o preço.

tier_idstring

Id da faixa aplicada. Ausente quando não há faixa ou quando o preço veio de uma regra B2B.

savingsinteger

Economia total em centavos contra o preço base. Nunca negativa.

price_redactedboolean

Só aparece (true) quando a loja esconde preço de visitante. Os valores vêm zerados.

Erros

Status	Quando	Corpo de exemplo
404	O produto não existe.	`{"error":"product not found"}`
401	A loja exige login para navegar.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
500	O id não é um UUID válido.	`{"error":"failed to calculate price","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`

Veja também

GETPreço por quantidade

Calcula o preço unitário e o total de um produto para uma quantidade, aplicando faixas e regras B2B.

A resposta nunca é guardada em cache (Cache-Control: no-store), porque depende de quem chama.

GET/api/v1/storefront/products/{id}/pricePública

Calcula o preço de um produto para uma quantidade

O token é opcional. Sem token o comprador é tratado como visitante; com token, valem as faixas do grupo dele e as regras B2B.

Parâmetros de caminho

iduuidobrigatório

Id do produto (UUID completo).

Parâmetros de consulta

quantityintegerpadrão: 1

Quantidade desejada. Valor ausente, não numérico, zero ou negativo é ignorado e vale 1.

Cabeçalhos

Authorizationstring

Bearer $TOKEN de um cliente logado. Opcional.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/price?quantity=3"

Resposta

200Preço calculado

json

{"unit_price":5290,"total_price":15870,"quantity":3,"tier_applied":false,"savings":0}

Com uma faixa aplicada (compra de 5 unidades, faixa de R$ 45,00):

200Faixa aplicada

json

{"unit_price":4500,"total_price":22500,"quantity":5,"tier_applied":true,"tier_id":"7c1e5b52-1f0b-4f88-8d9e-2d6a0a7e1a10","savings":3950}

Visitante em loja que esconde preços:

200Preço escondido

json

{"unit_price":0,"total_price":0,"quantity":3,"tier_applied":false,"savings":0,"price_redacted":true}

Campos da resposta

unit_priceinteger

Preço de uma unidade, em centavos, para a quantidade pedida.

total_priceinteger

unit_price vezes quantity, em centavos.

quantityinteger

Quantidade usada no cálculo (já corrigida para 1 se o valor enviado era inválido).

tier_appliedboolean

true quando uma faixa de quantidade ou regra B2B baixou o preço.

tier_idstring

Id da faixa aplicada. Ausente quando não há faixa ou quando o preço veio de uma regra B2B.

savingsinteger

Economia total em centavos contra o preço base. Nunca negativa.

price_redactedboolean

Só aparece (true) quando a loja esconde preço de visitante. Os valores vêm zerados.

Erros

Status	Quando	Corpo de exemplo
404	O produto não existe.	`{"error":"product not found"}`
401	A loja exige login para navegar.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
500	O id não é um UUID válido.	`{"error":"failed to calculate price","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`