Vale-presente
Valida o código de um vale-presente e usa o saldo em um pedido.
Duas rotas para o cliente pagar (parte do) pedido com um vale. Ambas exigem o token do cliente. O módulo gift-certificates é exigido só para vales da loja inteira; um vale de um seller específico funciona mesmo com o módulo desligado.
Validar um vale-presente
Um vale-presente (gift certificate) é um crédito com código que a loja ou um seller emite e que o cliente usa como pagamento. Esta rota não gasta nada: só confere se o código é válido e devolve o saldo utilizável neste carrinho. Para um vale de um seller específico, o saldo utilizável é limitado ao subtotal dos itens daquele seller no carrinho atual do cliente.
/api/v1/storefront/gift-certificates/validateClienteConfere o código e diz quanto dá para usar neste carrinho
Corpo da requisição
codestringobrigatórioExemplo de requisição
curl -X POST "$BASE_URL/api/v1/storefront/gift-certificates/validate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"code": "PRESENTE-50"
}'Resposta
{
"valid": true,
"code": "PRESENTE-50",
"balance": 5000,
"expires_at": "2027-03-31T23:59:59Z"
}Campos da resposta
validbooleantrue nesta resposta; vale inválido volta como erro 400.codestringbalanceintegerexpires_atstringnull se não vence.Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 400 | code ausente. | {"error":"code is required"} |
| 400 | O vale não existe, está inativo, sem saldo ou vencido. A mensagem diz qual (em inglês). | {"error":"gift certificate has expired"} |
| 401 | Sem token de cliente no cabeçalho Authorization. | {"error":"missing authorization header"} |
| 403 | O módulo gift-certificates está desligado nesta loja. | {"error":"module_disabled","module":"gift-certificates"} |
Usar um vale-presente
Debita o saldo do vale na hora e registra o uso contra o order_id. O vale vira used quando o saldo zera. Se o pedido for cancelado ou reembolsado, o valor usado volta ao vale. No checkout normal a plataforma aplica o vale sozinha; use esta rota apenas num checkout próprio.
/api/v1/storefront/gift-certificates/applyClienteDebita o saldo do vale e registra o uso em um pedido
Corpo da requisição
codestringobrigatórioorder_iduuidobrigatórioamountintegerpadrão: 00 (ou omitido) usa todo o saldo. Acima do saldo, é reduzido ao saldo.Exemplo de requisição
curl -X POST "$BASE_URL/api/v1/storefront/gift-certificates/apply" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"code": "PRESENTE-50",
"order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
"amount": 3000
}'Resposta
{
"id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"certificate_id": "8f9a0b1c-2d3e-4f50-8a1b-2c3d4e5f6a7b",
"order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
"amount_used": 3000,
"created_at": "2026-10-11T15:10:00Z",
"refunded_at": null
}Campos da resposta
iduuidcertificate_iduuidorder_iduuidamount_usedintegercreated_atstringrefunded_atstringnull; recebe a data se o uso for estornado.Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 400 | code ou order_id ausente. | {"error":"code and order_id are required"} |
| 400 | O vale não existe, está inativo, sem saldo ou vencido. A mensagem diz qual (em inglês). | {"error":"gift certificate has expired"} |
| 401 | Sem token de cliente no cabeçalho Authorization. | {"error":"missing authorization header"} |
| 403 | O módulo gift-certificates está desligado nesta loja. | {"error":"module_disabled","module":"gift-certificates"} |