Promoções, cupons automáticos e alertas
O que são promoções, cupons automáticos e alertas de preço na vitrine, quando usar cada rota e o mapa das 5 rotas públicas desta seção.
Uma promoção é uma regra de desconto da loja: percentual, valor fixo, frete grátis, "leve X pague Y" ou brinde. Ela pode valer no catálogo (preço da vitrine) ou no carrinho, pode exigir um código (cupom) ou ser aplicada sozinha quando as condições são atendidas. Esta seção dá ao front-end três coisas: mostrar as promoções públicas, simular o desconto de um carrinho e listar os cupons automáticos que o próprio cliente ganhou. Também cobre o cancelamento de um alerta de preço (aviso por e-mail quando um produto baixa de preço).
Quem aplica o desconto de verdade é o carrinho e o checkout. Estas rotas são de apoio: ajudam a montar banners, "falta X para frete grátis", telas de cupom e a conta do cliente.
Como funciona
- Mostre as ofertas
Listar promoções devolve as promoções ativas e públicas, com nome, descrição, tipo e validade.
- Simule o desconto de um carrinho
Simular promoções calcula o que a regra daria para um conjunto de itens, útil para avisos como "falta R$ 20 para ganhar frete grátis".
- Deixe o carrinho aplicar
O desconto real é calculado em Calcular o carrinho e confirmado no checkout.
- Mostre os cupons do cliente
Meus cupons automáticos lista os códigos que o cliente ganhou. O cliente digita o código no carrinho como qualquer cupom.
Conceitos-chave
Zona da promoção
Cada promoção tem uma zona: catalog (muda o preço mostrado na vitrine) ou cart (só entra no cálculo do carrinho). Na simulação, zone escolhe quais promoções avaliar, com cart como padrão.
Tipos de desconto
type | O que faz | Unidade de discount |
|---|---|---|
percentage | Percentual sobre o valor elegível. | Basis points (1000 = 10%). |
fixed | Valor fixo. | Centavos. |
free_shipping | Zera o frete (todo ou de um método). | Não se aplica (0). |
buy_x_get_y | Leve X, o item Y recebe desconto. | Não se aplica. |
Cupom automático
É um código único gerado para um cliente quando um evento de pedido bate com uma regra da loja: order_completed (toda compra concluída), first_order, nth_order ou min_order_amount. Cada código tem desconto (percentage em basis points ou fixed em centavos), valor mínimo de pedido, quantidade de usos e validade.
Alerta de preço
O cliente (ou visitante) pede ao lojista um aviso quando um produto chegar a um preço-alvo. O alerta é criado na página do produto e cancelado pelo link do e-mail ou por Cancelar alerta de preço.
Rotas
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/storefront/promotions | Listar promoções públicas ativas | Pública |
| POST | /api/v1/storefront/promotions/evaluate | Simular promoções para um carrinho | Pública (cliente opcional) |
| GET | /api/v1/storefront/auto-coupons/mine | Listar os cupons automáticos do cliente | Cliente |
| POST | /api/v1/storefront/auto-coupons/validate | Validar um cupom automático | Cliente |
| DELETE | /api/v1/storefront/price-alerts/{id} | Cancelar um alerta de preço | Pública (id + e-mail) |
Erros comuns
- Esperar paginação cheia em
GET /promotions. O filtro de promoções segmentadas é aplicado depois da paginação. Uma página pode vir com menos itens queper_page, ou vazia, mesmo comtotal_pagesmaior que a página. Continue pedindo páginas atépagepassar detotal_pages. - Usar o resultado de
evaluatecomo preço final. A simulação não conhece frete real, cupom gravado no carrinho nem estoque, e confia nos valores enviados. Mostre o total oficial de Calcular o carrinho. - Mandar preços em reais.
unit_price,cart_subtotalecart_totalsão centavos inteiros. - Chamar as rotas de cupom automático sem login. Respondem
401 missing authorization header. - Achar que
GET /auto-coupons/mine?status=filtra qualquer texto. Sóactive,usedeexpiredfiltram. Outro valor é ignorado e a lista vem sem filtro. - Confiar no
{"cancelled": true}do alerta. A rota responde sucesso mesmo que o id ou o e-mail não casem com nenhum alerta ativo.