Cupom e vale-presente
Aplica e remove um cupom de desconto e um vale-presente em uma sessão de checkout.
Dois abatimentos que o cliente digita no checkout. O cupom é um código promocional que dá desconto ou frete grátis. O vale-presente (gift certificate) é um saldo pré-pago que abate o total, como um cartão-presente. Cada um tem uma chamada para aplicar (POST) e uma para remover (DELETE); todas devolvem a sessão com o total recalculado.
O desconto de catálogo é preservado ao aplicar ou remover o cupom: a sessão guarda catalog_discount à parte. O ciclo de vida do cupom e o cadastro são tratados na administração; aqui só o uso no checkout.
Aplicar um cupom
/api/storefront/checkout/{sessionId}/couponClienteAplicar um cupom à sessão
Parâmetros de caminho
sessionIduuidobrigatórioCorpo da requisição
coupon_codestringobrigatórioRemover o cupom
/api/storefront/checkout/{sessionId}/couponClienteRemover o cupom da sessão
Tira o cupom e volta o total ao valor sem ele. O frete grátis concedido pelo cupom também é desfeito (o de promoção automática continua).
Parâmetros de caminho
sessionIduuidobrigatórioAplicar um vale-presente
/api/storefront/checkout/{sessionId}/gift-certificateClienteAplicar um vale-presente à sessão
Abate do total o saldo do vale. O valor abatido aparece em gift_cert_amount, em centavos.
Parâmetros de caminho
sessionIduuidobrigatórioCorpo da requisição
codestringobrigatórioRemover o vale-presente
/api/storefront/checkout/{sessionId}/gift-certificateClienteRemover o vale-presente da sessão
Parâmetros de caminho
sessionIduuidobrigatórioExemplo de requisição
curl -X POST "$BASE_URL/api/storefront/checkout/$SESSION_ID/coupon" \
-H "X-Session-ID: $VISITOR_ID" -H "Content-Type: application/json" \
-d '{"coupon_code":"BEMVINDO10"}'
curl -X DELETE "$BASE_URL/api/storefront/checkout/$SESSION_ID/coupon" \
-H "X-Session-ID: $VISITOR_ID"
curl -X POST "$BASE_URL/api/storefront/checkout/$SESSION_ID/gift-certificate" \
-H "X-Session-ID: $VISITOR_ID" -H "Content-Type: application/json" \
-d '{"code":"VALE-ABCD-1234"}'Resposta
{
"id": "bcc7b882-448e-4b50-b870-41521b747889",
"step": "payment",
"subtotal": 30000,
"discount": 10500,
"catalog_discount": 7500,
"coupon_code": "BEMVINDO10",
"free_shipping": false,
"gift_cert_code": null,
"gift_cert_amount": 0,
"total": 19500
}Todas as quatro chamadas devolvem a sessão descrita em Iniciar checkout. Campos relevantes: coupon_code e discount (cupom), free_shipping (se o cupom dá frete grátis), gift_cert_code e gift_cert_amount (vale-presente), total.
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo inválido | {"error": "invalid request body"} |
| 400 | Cupom inexistente, inativo, expirado ou fora das regras | {"error": "coupon not applicable: cupom não encontrado ou inativo"} (a mensagem após os dois-pontos vem da regra que recusou, em português) |
| 400 | Vale-presente inexistente | {"error": "invalid gift certificate: gift certificate not found"} |
| 400 | coupon_code ou code vazio | {"error": "coupon_code is required"} ou {"error": "gift certificate code is required"} |
| 400 | Vale-presente desligado na loja | {"error": "gift certificates are not enabled"} |
| 403 | Chave sfk_ ou token vat_ sem o escopo | {"error": "missing_scope", "required": "..."} |
| 403 | Cupons desligados na loja (só nas rotas de cupom) | {"error": "feature_not_available", "feature": "coupons", "detail": "switched off for this store"} |
| 404 | Sessão inexistente ou de outra pessoa | {"error": "checkout session not found"} |