Cupons no carrinho
Valida e grava um cupom (ou voucher) no carrinho, e remove um ou todos os cupons gravados.
Um cupom é um código que o comprador digita para ganhar desconto (percentual, valor fixo, frete grátis ou "leve X pague Y"). Um voucher é um código avulso emitido pelo seller ou pela loja. Estas duas rotas tratam os dois do mesmo jeito: o comprador digita o código, a API confere se ele vale para este carrinho e o grava no carrinho.
Gravar o cupom não muda os totais do carrinho. O desconto aparece quando você chama Calcular o carrinho, que lê os cupons gravados. No checkout o cupom segue para a sessão de compra; veja Cupom, vale-presente e pontos.
Aplicar um cupom
/api/v1/storefront/cart/couponAutenticadaAplica um cupom ao carrinho
A API procura o código entre as promoções com cupom e, se não encontrar, entre os vouchers. A validação usa o carrinho atual: valor mínimo, limite de uso por cliente, validade, grupos de cliente, e produtos, categorias ou sellers exigidos. Se o cupom não pode gerar desconto para este carrinho, a resposta é um erro com o motivo, e nada é gravado.
Um cupom válido é acrescentado à lista de cupons do carrinho (repetir o mesmo código não duplica). Quantos cupons realmente somam desconto depende da configuração da loja (use_single_coupon) e da regra de empilhamento de cada promoção.
Cabeçalhos
AuthorizationstringBearer <token> do cliente logado. Com token, o limite de uso por cliente e os grupos de cliente são conferidos.X-Session-IDstringCorpo da requisição
codestringobrigatórioExemplo de requisição
curl -X POST "$BASE_URL/api/v1/storefront/cart/coupon" \
-H "X-Session-ID: $SESSION_ID" \
-H "Content-Type: application/json" \
-d '{
"code": "BEMVINDO10"
}'Resposta
{
"code": "BEMVINDO10",
"coupon_code": "BEMVINDO10",
"valid": true,
"message": "coupon applied",
"discount": 2300
}Campos da resposta
codestringcoupon_codestringvalidbooleantrue numa resposta 200.messagestringcoupon applied. Texto fixo em inglês: não o exiba ao comprador.discountintegerRemover cupons
/api/v1/storefront/cart/couponAutenticadaRemove um ou todos os cupons do carrinho
Tira cupons gravados no carrinho. Com ?code=, remove só aquele código; sem o parâmetro, remove todos. Remover um código que não está no carrinho não é erro. A rota exige o módulo de promoções ligado.
Parâmetros de consulta
codestringCabeçalhos
AuthorizationstringBearer <token> do cliente logado.X-Session-IDstringcurl -X DELETE "$BASE_URL/api/v1/storefront/cart/coupon?code=BEMVINDO10" \
-H "X-Session-ID: $SESSION_ID"{ "message": "coupon removed" }Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Sem token e sem X-Session-ID | {"error":"session_id or authentication required"} |
| 400 | Corpo que não é JSON | {"error":"invalid request body"} |
| 400 | code vazio | {"error":"coupon code is required"} |
| 403 | A loja desligou cupons | {"error":"feature_not_available","feature":"coupons","detail":"switched off for this store"} |
| 403 | Módulo de promoções desligado (cupom da loja toda, ou DELETE) | {"error":"module_disabled","module":"promotions"} |
| 422 | O código não existe, não está ativo ou não vale para este carrinho | {"error":"cupom não encontrado ou inativo"} |
| 500 | Falha interna ao validar ou gravar | {"error":"failed to validate coupon","detail":"..."} |
No 422, a mensagem em error é o motivo exato e vem em português, escrita para o comprador. Exemplos reais: cupom não encontrado ou inativo, esta promoção expirou, valor mínimo do carrinho: R$ 200,00 (faltam R$ 50,00), você já utilizou este cupom 1 vez(es), nenhum item do carrinho corresponde aos produtos exigidos por este cupom. Mostre a mensagem como veio.