API atual/Referência completa/Promoções e cupons

Cupons automáticos do cliente

Lista os cupons que o cliente logado ganhou de regras automáticas da loja e valida um código de cupom automático.

Um cupom automático é um código único que a loja gera para um cliente depois de um evento, por exemplo "10% de desconto na próxima compra" após a primeira compra. A regra que o gera é configurada no painel; estas rotas são o lado do cliente: ver os códigos que ele tem e conferir se um código ainda vale.

As duas rotas exigem cliente logado (Authorization: Bearer) e dependem do módulo de cupons automáticos (sem ele: 403 {"error":"module_disabled","module":"auto-coupons"}). Aplicar o código num pedido continua sendo feito como qualquer cupom: no carrinho ou no checkout.

Listar meus cupons

GET/api/v1/storefront/auto-coupons/mineCliente

Lista os cupons automáticos do cliente logado

Devolve só os cupons gerados para o cliente do token, paginados, com filtro opcional de situação. Serve para a tela "Meus cupons" da conta.

Cabeçalhos

Authorizationstringobrigatório

Bearer <token> do cliente. Sem ele: 401 missing authorization header.

Parâmetros de consulta

statusstring

activeusedexpired

active: ainda tem usos e não venceu. used: usos esgotados. expired: venceu sem ser usado. Qualquer outro valor é ignorado e a lista vem sem filtro.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/auto-coupons/mine?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cupons do cliente

json

{
  "coupons": [
    {
      "id": 41,
      "rule_id": 3,
      "coupon_code": "VOLTE-9F2A-71C0",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "discount_type": "percentage",
      "discount_value": 1000,
      "min_order_amount": 10000,
      "max_uses": 1,
      "uses_count": 0,
      "expires_at": "2026-11-10T23:59:59Z",
      "created_at": "2026-10-11T21:06:41Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

O exemplo ilustra o formato: o cliente de teste da documentação não tinha cupons, e a resposta real dele foi {"coupons":null,"total":0,"page":1,"per_page":20,"total_pages":0}.

Campos da resposta

couponsarray|null

Cupons da página. Vem null (não []) quando não há nenhum.

coupons[].idinteger

Id numérico do cupom gerado.

coupons[].rule_idinteger

Id da regra que gerou o cupom.

coupons[].coupon_codestring

O código que o cliente digita.

coupons[].order_idstring

Pedido que disparou a geração. Vazio quando o cupom não veio de um pedido.

coupons[].user_idstring

Cliente dono do cupom.

coupons[].discount_typestring

percentagefixed

Tipo do desconto.

coupons[].discount_valueinteger

Basis points quando percentage (1000 = 10%); centavos quando fixed.

coupons[].min_order_amountinteger

Valor mínimo de pedido em centavos. 0 quando não há mínimo.

coupons[].max_usesinteger

Quantas vezes o código pode ser usado.

coupons[].uses_countinteger

Quantas vezes já foi usado.

coupons[].expires_atstring

Validade, RFC 3339. null quando não vence.

coupons[].vendor_iduuid

Presente quando o cupom só vale para os itens de um seller. Ausente quando vale na loja toda.

coupons[].created_atstring

Quando o cupom foi gerado, RFC 3339.

totalinteger

Total de cupons que atendem ao filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
401	Token inválido ou vencido	`{"error":"invalid or expired token"}`
403	Módulo de cupons automáticos desligado	`{"error":"module_disabled","module":"auto-coupons"}`
500	Falha ao consultar	`{"error":"failed to list your coupons","detail":"..."}`

Validar um cupom automático

POST/api/v1/storefront/auto-coupons/validateCliente

Valida um código de cupom automático

Confere se um código de cupom automático existe, ainda tem usos e não venceu, e devolve os dados públicos dele. Não aplica o cupom em nada. A busca ignora maiúsculas e minúsculas.

Esta rota não confere se o cupom é do cliente que chama, nem se o pedido atinge o min_order_amount: ela responde só sobre existência, usos e validade. A conferência completa acontece quando o código é aplicado no carrinho ou no checkout.

Cabeçalhos

Authorizationstringobrigatório

Bearer <token> do cliente.

Content-Typestringobrigatório

application/json.

Corpo da requisição

codestringobrigatório

Código do cupom automático.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/auto-coupons/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "VOLTE-9F2A-71C0"
}'

Resposta

200Cupom válido

json

{
  "valid": true,
  "coupon_code": "VOLTE-9F2A-71C0",
  "discount_type": "percentage",
  "discount_value": 1000,
  "min_order_amount": 10000,
  "expires_at": "2026-11-10T23:59:59Z"
}

Campos da resposta

validboolean

Sempre true nesta resposta. Cupom inválido vira erro 400.

coupon_codestring

Código, como está cadastrado.

discount_typestring

percentagefixed

Tipo do desconto.

discount_valueinteger

Basis points (percentage) ou centavos (fixed).

min_order_amountinteger

Valor mínimo de pedido em centavos.

expires_atstring

Validade, RFC 3339, ou null.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `code`	`{"error":"code is required"}`
400	Código inexistente	`{"error":"invalid coupon","detail":"coupon not found: NOPE"}`
400	Todos os usos gastos	`{"error":"invalid coupon","detail":"coupon has been fully redeemed"}`
400	Vencido	`{"error":"invalid coupon","detail":"coupon has expired"}`
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Módulo desligado	`{"error":"module_disabled","module":"auto-coupons"}`

Veja também

Cupons automáticos do cliente

Lista os cupons que o cliente logado ganhou de regras automáticas da loja e valida um código de cupom automático.

Listar meus cupons

GET/api/v1/storefront/auto-coupons/mineCliente

Lista os cupons automáticos do cliente logado

Devolve só os cupons gerados para o cliente do token, paginados, com filtro opcional de situação. Serve para a tela "Meus cupons" da conta.

Cabeçalhos

Authorizationstringobrigatório

Bearer <token> do cliente. Sem ele: 401 missing authorization header.

Parâmetros de consulta

statusstring

activeusedexpired

active: ainda tem usos e não venceu. used: usos esgotados. expired: venceu sem ser usado. Qualquer outro valor é ignorado e a lista vem sem filtro.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/auto-coupons/mine?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cupons do cliente

json

{
  "coupons": [
    {
      "id": 41,
      "rule_id": 3,
      "coupon_code": "VOLTE-9F2A-71C0",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "discount_type": "percentage",
      "discount_value": 1000,
      "min_order_amount": 10000,
      "max_uses": 1,
      "uses_count": 0,
      "expires_at": "2026-11-10T23:59:59Z",
      "created_at": "2026-10-11T21:06:41Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

O exemplo ilustra o formato: o cliente de teste da documentação não tinha cupons, e a resposta real dele foi {"coupons":null,"total":0,"page":1,"per_page":20,"total_pages":0}.

Campos da resposta

couponsarray|null

Cupons da página. Vem null (não []) quando não há nenhum.

coupons[].idinteger

Id numérico do cupom gerado.

coupons[].rule_idinteger

Id da regra que gerou o cupom.

coupons[].coupon_codestring

O código que o cliente digita.

coupons[].order_idstring

Pedido que disparou a geração. Vazio quando o cupom não veio de um pedido.

coupons[].user_idstring

Cliente dono do cupom.

coupons[].discount_typestring

percentagefixed

Tipo do desconto.

coupons[].discount_valueinteger

Basis points quando percentage (1000 = 10%); centavos quando fixed.

coupons[].min_order_amountinteger

Valor mínimo de pedido em centavos. 0 quando não há mínimo.

coupons[].max_usesinteger

Quantas vezes o código pode ser usado.

coupons[].uses_countinteger

Quantas vezes já foi usado.

coupons[].expires_atstring

Validade, RFC 3339. null quando não vence.

coupons[].vendor_iduuid

Presente quando o cupom só vale para os itens de um seller. Ausente quando vale na loja toda.

coupons[].created_atstring

Quando o cupom foi gerado, RFC 3339.

totalinteger

Total de cupons que atendem ao filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
401	Token inválido ou vencido	`{"error":"invalid or expired token"}`
403	Módulo de cupons automáticos desligado	`{"error":"module_disabled","module":"auto-coupons"}`
500	Falha ao consultar	`{"error":"failed to list your coupons","detail":"..."}`

Validar um cupom automático

POST/api/v1/storefront/auto-coupons/validateCliente

Valida um código de cupom automático

Confere se um código de cupom automático existe, ainda tem usos e não venceu, e devolve os dados públicos dele. Não aplica o cupom em nada. A busca ignora maiúsculas e minúsculas.

Cabeçalhos

Authorizationstringobrigatório

Bearer <token> do cliente.

Content-Typestringobrigatório

application/json.

Corpo da requisição

codestringobrigatório

Código do cupom automático.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/auto-coupons/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "VOLTE-9F2A-71C0"
}'

Resposta

200Cupom válido

json

{
  "valid": true,
  "coupon_code": "VOLTE-9F2A-71C0",
  "discount_type": "percentage",
  "discount_value": 1000,
  "min_order_amount": 10000,
  "expires_at": "2026-11-10T23:59:59Z"
}

Campos da resposta

validboolean

Sempre true nesta resposta. Cupom inválido vira erro 400.

coupon_codestring

Código, como está cadastrado.

discount_typestring

percentagefixed

Tipo do desconto.

discount_valueinteger

Basis points (percentage) ou centavos (fixed).

min_order_amountinteger

Valor mínimo de pedido em centavos.

expires_atstring

Validade, RFC 3339, ou null.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `code`	`{"error":"code is required"}`
400	Código inexistente	`{"error":"invalid coupon","detail":"coupon not found: NOPE"}`
400	Todos os usos gastos	`{"error":"invalid coupon","detail":"coupon has been fully redeemed"}`
400	Vencido	`{"error":"invalid coupon","detail":"coupon has expired"}`
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Módulo desligado	`{"error":"module_disabled","module":"auto-coupons"}`