API atual/Referência completa/Créditos e descontos

Cupons de desconto

Valida um cupom, registra o resgate e lista os cupons já usados.

Cupons dão desconto percentual, fixo ou frete grátis. Há cupons da loja inteira e cupons de um seller, que descontam só os itens daquele seller. As três rotas exigem o token do cliente. O módulo voucher-system é exigido só para cupons da loja inteira (e para códigos que não existem).

Validar um cupom

Um cupom (voucher) dá desconto no pedido. Esta rota não gasta nada: confere o código (ativo, dentro das datas, com usos disponíveis, com o pedido mínimo atendido) e calcula o desconto para o order_total informado. Um cupom inválido volta com 200 e valid: false, com o motivo em reason.

POST/api/v1/storefront/vouchers/validateCliente

Confere o código e calcula o desconto para um total

Corpo da requisição

codestringobrigatório

Código do cupom, sem diferenciar maiúsculas.

order_totalintegerobrigatório

Total do pedido em centavos, base do cálculo e do pedido mínimo. Para cupom de um seller específico, vale o subtotal dos itens dele no carrinho do cliente, não este número.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/vouchers/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BEMVINDO10",
    "order_total": 22500
  }'

Resposta

200Cupom válido

json

{
  "voucher": {
    "id": 17,
    "vendor_id": null,
    "code": "BEMVINDO10",
    "type": "percentage",
    "value": 1000,
    "min_order": 20000,
    "max_uses": 500,
    "used_count": 42,
    "max_per_user": 1,
    "starts_at": "2026-10-01T00:00:00Z",
    "expires_at": "2026-12-31T23:59:59Z",
    "is_active": true,
    "description": "10% de desconto na primeira compra",
    "created_at": "2026-09-28T12:00:00Z",
    "updated_at": "2026-10-10T09:00:00Z"
  },
  "discount_amount": 2250,
  "valid": true
}

200Cupom inválido

json

{
  "voucher": null,
  "discount_amount": 0,
  "valid": false,
  "reason": "VOUCHER_NOT_FOUND"
}

Campos da resposta

validboolean

true se o cupom pode ser usado agora.

discount_amountinteger

Desconto calculado, em centavos. Cupom de frete grátis dá 0 aqui: o desconto do frete é aplicado pelo checkout.

reasonstring

VOUCHER_CODE_REQUIREDVOUCHER_NOT_FOUNDVOUCHER_INACTIVEVOUCHER_NOT_STARTEDVOUCHER_EXPIREDVOUCHER_MAX_USES_REACHEDVOUCHER_MAX_PER_USER_REACHEDVOUCHER_MIN_ORDER_NOT_MET

Só quando valid é false. Código de máquina para você traduzir na sua tela.

voucherobject

Dados do cupom (ausente/null se o código não existe): id, vendor_id (seller dono, ou null se da loja inteira), code, type, value, min_order, max_uses, used_count, max_per_user, starts_at, expires_at, is_active, description, created_at, updated_at.

voucher.type, voucher.valuestring

fixedpercentagefree_shipping

fixed: value em centavos. percentage: value em pontos-base (1000 = 10%). free_shipping: sem valor monetário.

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `voucher-system` está desligado nesta loja.	`{"error":"module_disabled","module":"voucher-system"}`
500	Falha ao validar.	`{"error":"failed to validate voucher","detail":"..."}`

Resgatar um cupom

Registra o uso do cupom: soma 1 ao contador de usos e grava o resgate. As regras são conferidas de novo no momento do resgate (ativo, datas, limite de usos, limite por cliente), mesmo com várias chamadas simultâneas. O cupom é identificado pelo id numérico (devolvido por validar), não pelo código. No checkout normal a plataforma resgata o cupom sozinha; use esta rota apenas num checkout próprio.

POST/api/v1/storefront/vouchers/redeemCliente

Registra o uso de um cupom por um cliente em um pedido

Corpo da requisição

voucher_idintegerobrigatório

Id numérico do cupom (voucher.id da validação).

order_idstringobrigatório

Pedido que recebeu o desconto.

amountintegerobrigatório

Desconto a registrar, em centavos, maior que zero. Em cupom fixed é limitado ao value do cupom; em free_shipping é gravado como 0; em percentage não há teto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/vouchers/redeem" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "voucher_id": 17,
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 2250
  }'

Resposta

200Resgate registrado

json

{
  "id": 301,
  "voucher_id": 17,
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "amount": 2250,
  "created_at": "2026-10-11T15:12:00Z"
}

Campos da resposta

idinteger

Id do resgate.

voucher_idinteger

O cupom.

user_iduuid

O cliente.

order_idstring

O pedido.

amountinteger

Desconto registrado, em centavos.

created_atstring

Quando foi resgatado (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Falta `voucher_id`, `order_id`, ou `amount` não é positivo.	`{"error":"voucher_id is required"}`
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `voucher-system` está desligado nesta loja.	`{"error":"module_disabled","module":"voucher-system"}`
404	Cupom inexistente.	`{"error":"voucher not found"}`
409	O cupom acabou de esgotar, vencer, ou não está ativo, ou o cliente já usou o máximo permitido. A mensagem diz qual (em inglês).	`{"error":"voucher 17 fully redeemed"}`

Meus cupons usados

Lista os resgates do cliente logado, do mais recente para o mais antigo. Sem paginação.

GET/api/v1/storefront/vouchers/my-redemptionsCliente

Cupons que o cliente já resgatou

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/vouchers/my-redemptions" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resgates

json

{
  "redemptions": [
    {
      "id": 301,
      "voucher_id": 17,
      "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "amount": 2250,
      "created_at": "2026-10-11T15:12:00Z"
    }
  ]
}

Campos da resposta

redemptionsarray

Lista vazia se o cliente nunca resgatou.

idinteger

Id do resgate.

voucher_idinteger

O cupom.

user_iduuid

O cliente.

order_idstring

O pedido.

amountinteger

Desconto registrado, em centavos.

created_atstring

Quando foi resgatado (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`

Veja também

API atual/Referência completa/Créditos e descontos

Cupons de desconto

Valida um cupom, registra o resgate e lista os cupons já usados.

Validar um cupom

POST/api/v1/storefront/vouchers/validateCliente

Confere o código e calcula o desconto para um total

Corpo da requisição

codestringobrigatório

Código do cupom, sem diferenciar maiúsculas.

order_totalintegerobrigatório

Total do pedido em centavos, base do cálculo e do pedido mínimo. Para cupom de um seller específico, vale o subtotal dos itens dele no carrinho do cliente, não este número.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/vouchers/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BEMVINDO10",
    "order_total": 22500
  }'

Resposta

200Cupom válido

json

{
  "voucher": {
    "id": 17,
    "vendor_id": null,
    "code": "BEMVINDO10",
    "type": "percentage",
    "value": 1000,
    "min_order": 20000,
    "max_uses": 500,
    "used_count": 42,
    "max_per_user": 1,
    "starts_at": "2026-10-01T00:00:00Z",
    "expires_at": "2026-12-31T23:59:59Z",
    "is_active": true,
    "description": "10% de desconto na primeira compra",
    "created_at": "2026-09-28T12:00:00Z",
    "updated_at": "2026-10-10T09:00:00Z"
  },
  "discount_amount": 2250,
  "valid": true
}

200Cupom inválido

json

{
  "voucher": null,
  "discount_amount": 0,
  "valid": false,
  "reason": "VOUCHER_NOT_FOUND"
}

Campos da resposta

validboolean

true se o cupom pode ser usado agora.

discount_amountinteger

Desconto calculado, em centavos. Cupom de frete grátis dá 0 aqui: o desconto do frete é aplicado pelo checkout.

reasonstring

VOUCHER_CODE_REQUIREDVOUCHER_NOT_FOUNDVOUCHER_INACTIVEVOUCHER_NOT_STARTEDVOUCHER_EXPIREDVOUCHER_MAX_USES_REACHEDVOUCHER_MAX_PER_USER_REACHEDVOUCHER_MIN_ORDER_NOT_MET

Só quando valid é false. Código de máquina para você traduzir na sua tela.

voucherobject

voucher.type, voucher.valuestring

fixedpercentagefree_shipping

fixed: value em centavos. percentage: value em pontos-base (1000 = 10%). free_shipping: sem valor monetário.

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `voucher-system` está desligado nesta loja.	`{"error":"module_disabled","module":"voucher-system"}`
500	Falha ao validar.	`{"error":"failed to validate voucher","detail":"..."}`

Resgatar um cupom

POST/api/v1/storefront/vouchers/redeemCliente

Registra o uso de um cupom por um cliente em um pedido

Corpo da requisição

voucher_idintegerobrigatório

Id numérico do cupom (voucher.id da validação).

order_idstringobrigatório

Pedido que recebeu o desconto.

amountintegerobrigatório

Desconto a registrar, em centavos, maior que zero. Em cupom fixed é limitado ao value do cupom; em free_shipping é gravado como 0; em percentage não há teto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/vouchers/redeem" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "voucher_id": 17,
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 2250
  }'

Resposta

200Resgate registrado

json

{
  "id": 301,
  "voucher_id": 17,
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "amount": 2250,
  "created_at": "2026-10-11T15:12:00Z"
}

Campos da resposta

idinteger

Id do resgate.

voucher_idinteger

O cupom.

user_iduuid

O cliente.

order_idstring

O pedido.

amountinteger

Desconto registrado, em centavos.

created_atstring

Quando foi resgatado (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Falta `voucher_id`, `order_id`, ou `amount` não é positivo.	`{"error":"voucher_id is required"}`
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `voucher-system` está desligado nesta loja.	`{"error":"module_disabled","module":"voucher-system"}`
404	Cupom inexistente.	`{"error":"voucher not found"}`
409	O cupom acabou de esgotar, vencer, ou não está ativo, ou o cliente já usou o máximo permitido. A mensagem diz qual (em inglês).	`{"error":"voucher 17 fully redeemed"}`

Meus cupons usados

Lista os resgates do cliente logado, do mais recente para o mais antigo. Sem paginação.

GET/api/v1/storefront/vouchers/my-redemptionsCliente

Cupons que o cliente já resgatou

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/vouchers/my-redemptions" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resgates

json

{
  "redemptions": [
    {
      "id": 301,
      "voucher_id": 17,
      "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "amount": 2250,
      "created_at": "2026-10-11T15:12:00Z"
    }
  ]
}

Campos da resposta

redemptionsarray

Lista vazia se o cliente nunca resgatou.

idinteger

Id do resgate.

voucher_idinteger

O cupom.

user_iduuid

O cliente.

order_idstring

O pedido.

amountinteger

Desconto registrado, em centavos.

created_atstring

Quando foi resgatado (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`