API atual/Referência completa/Cupons automáticos

Cupons gerados

Lista os cupons já emitidos pelas regras e confere se um código gerado ainda é utilizável.

Estas duas rotas são de acompanhamento: ver quem ganhou o quê e quanto já foi usado, e conferir um código quando o cliente reclama que "não funcionou". Elas leem o registro dos cupons gerados, não o carrinho.

Listar cupons gerados

GET/api/v1/admin/auto-coupons/couponsAdmin

Lista os cupons gerados pelas regras

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

rule_idinteger

Só cupons desta regra. Valor que não é número é ignorado.

user_iduuid

Só cupons deste cliente.

statusstring

activeusedexpired

active (utilizável), used (esgotado) ou expired (vencido).

searchstring

Parte do código, sem diferenciar maiúsculas.

Exemplo de requisição: listar

bash

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

Resposta: listar

200Página de cupons

json

{
  "coupons": [
    {
      "id": 41,
      "rule_id": 3,
      "coupon_code": "VOLTE-3F9A-1C7B",
      "order_id": "9d5b8e61-0a3c-4f7e-8b21-6c4d2f1a9e03",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "discount_type": "percentage",
      "discount_value": 1000,
      "min_order_amount": 15000,
      "max_uses": 1,
      "uses_count": 0,
      "expires_at": "2026-11-10T14:25:00Z",
      "created_at": "2026-10-11T14:25:00Z",
      "coupon_id": 41,
      "code": "VOLTE-3F9A-1C7B",
      "timestamp": 1791728700,
      "expiry_date": 1794320700
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

couponsarray

Cupons da página. Sem resultados vem null.

idinteger

Identificador do cupom gerado (inteiro).

rule_idinteger

Regra que o gerou.

coupon_codestring

O código, no formato PREFIXO-XXXX-XXXX (hexadecimal em maiúsculas).

order_iduuid

Pedido que disparou a geração.

user_iduuid

Cliente que ganhou o cupom.

discount_typestring

Copiado da regra no momento da geração.

discount_valueinteger

Copiado da regra.

min_order_amountinteger

Copiado da regra, em centavos.

max_usesinteger

Máximo de usos.

uses_countinteger

Usos até agora.

expires_atstring (RFC 3339) | null

Validade. null = não expira.

vendor_iduuid | omitted

Seller, quando o cupom veio de uma regra de seller.

created_atstring (RFC 3339)

Geração.

coupon_id, code, timestamp, expiry_datemixed

Apelidos de compatibilidade com a plataforma antiga (repetem id, coupon_code, created_at e expires_at, estes dois em segundos Unix). Ignore-os em integrações novas.

totalinteger

Total que casa com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página.

total_pagesinteger

Total de páginas.

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Módulo `promotions` ou `auto-coupons` desligado na loja.	`{"error":"module_disabled","module":"auto-coupons"}`
403	Falta o privilégio: `view_auto_coupons` (ou `view_promotions`) para ler, `manage_auto_coupons` (ou `manage_promotions`) para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`

Conferir um cupom gerado

POST/api/v1/admin/auto-coupons/validateAdmin

Confere se um cupom gerado existe, não expirou e não foi esgotado

Corpo da requisição

codestringobrigatório

O código, sem diferenciar maiúsculas.

Exemplo de requisição: conferir

bash

curl -X POST "$BASE_URL/api/v1/admin/auto-coupons/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "VOLTE-3F9A-1C7B"
  }'

Resposta: conferir

200Cupom utilizável

json

{
  "id": 41,
  "rule_id": 3,
  "coupon_code": "VOLTE-3F9A-1C7B",
  "order_id": "9d5b8e61-0a3c-4f7e-8b21-6c4d2f1a9e03",
  "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "discount_type": "percentage",
  "discount_value": 1000,
  "min_order_amount": 15000,
  "max_uses": 1,
  "uses_count": 0,
  "expires_at": "2026-11-10T14:25:00Z",
  "created_at": "2026-10-11T14:25:00Z",
  "coupon_id": 41,
  "code": "VOLTE-3F9A-1C7B",
  "timestamp": 1791728700,
  "expiry_date": 1794320700
}

Campos da resposta

idinteger

Identificador do cupom gerado (inteiro).

rule_idinteger

Regra que o gerou.

coupon_codestring

O código, no formato PREFIXO-XXXX-XXXX (hexadecimal em maiúsculas).

order_iduuid

Pedido que disparou a geração.

user_iduuid

Cliente que ganhou o cupom.

discount_typestring

Copiado da regra no momento da geração.

discount_valueinteger

Copiado da regra.

min_order_amountinteger

Copiado da regra, em centavos.

max_usesinteger

Máximo de usos.

uses_countinteger

Usos até agora.

expires_atstring (RFC 3339) | null

Validade. null = não expira.

vendor_iduuid | omitted

Seller, quando o cupom veio de uma regra de seller.

created_atstring (RFC 3339)

Geração.

coupon_id, code, timestamp, expiry_datemixed

Apelidos de compatibilidade com a plataforma antiga (repetem id, coupon_code, created_at e expires_at, estes dois em segundos Unix). Ignore-os em integrações novas.

Erros: conferir

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Módulo `promotions` ou `auto-coupons` desligado na loja.	`{"error":"module_disabled","module":"auto-coupons"}`
403	Falta o privilégio: `view_auto_coupons` (ou `view_promotions`) para ler, `manage_auto_coupons` (ou `manage_promotions`) para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`code` ausente.	`{"error":"code is required"}`
400	Código inexistente, esgotado ou vencido. O motivo vem em `detail` (em inglês): `coupon not found: ...`, `coupon has been fully redeemed` ou `coupon has expired`.	`{"error":"invalid coupon","detail":"coupon has expired"}`

Veja também

Cupons gerados

Lista os cupons já emitidos pelas regras e confere se um código gerado ainda é utilizável.

Listar cupons gerados

GET/api/v1/admin/auto-coupons/couponsAdmin

Lista os cupons gerados pelas regras

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

rule_idinteger

Só cupons desta regra. Valor que não é número é ignorado.

user_iduuid

Só cupons deste cliente.

statusstring

activeusedexpired

active (utilizável), used (esgotado) ou expired (vencido).

searchstring

Parte do código, sem diferenciar maiúsculas.

Exemplo de requisição: listar

bash

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

Resposta: listar

200Página de cupons

json

{
  "coupons": [
    {
      "id": 41,
      "rule_id": 3,
      "coupon_code": "VOLTE-3F9A-1C7B",
      "order_id": "9d5b8e61-0a3c-4f7e-8b21-6c4d2f1a9e03",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "discount_type": "percentage",
      "discount_value": 1000,
      "min_order_amount": 15000,
      "max_uses": 1,
      "uses_count": 0,
      "expires_at": "2026-11-10T14:25:00Z",
      "created_at": "2026-10-11T14:25:00Z",
      "coupon_id": 41,
      "code": "VOLTE-3F9A-1C7B",
      "timestamp": 1791728700,
      "expiry_date": 1794320700
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

couponsarray

Cupons da página. Sem resultados vem null.

idinteger

Identificador do cupom gerado (inteiro).

rule_idinteger

Regra que o gerou.

coupon_codestring

O código, no formato PREFIXO-XXXX-XXXX (hexadecimal em maiúsculas).

order_iduuid

Pedido que disparou a geração.

user_iduuid

Cliente que ganhou o cupom.

discount_typestring

Copiado da regra no momento da geração.

discount_valueinteger

Copiado da regra.

min_order_amountinteger

Copiado da regra, em centavos.

max_usesinteger

Máximo de usos.

uses_countinteger

Usos até agora.

expires_atstring (RFC 3339) | null

Validade. null = não expira.

vendor_iduuid | omitted

Seller, quando o cupom veio de uma regra de seller.

created_atstring (RFC 3339)

Geração.

coupon_id, code, timestamp, expiry_datemixed

Apelidos de compatibilidade com a plataforma antiga (repetem id, coupon_code, created_at e expires_at, estes dois em segundos Unix). Ignore-os em integrações novas.

totalinteger

Total que casa com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página.

total_pagesinteger

Total de páginas.

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Módulo `promotions` ou `auto-coupons` desligado na loja.	`{"error":"module_disabled","module":"auto-coupons"}`
403	Falta o privilégio: `view_auto_coupons` (ou `view_promotions`) para ler, `manage_auto_coupons` (ou `manage_promotions`) para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`

Conferir um cupom gerado

POST/api/v1/admin/auto-coupons/validateAdmin

Confere se um cupom gerado existe, não expirou e não foi esgotado

Corpo da requisição

codestringobrigatório

O código, sem diferenciar maiúsculas.

Exemplo de requisição: conferir

bash

curl -X POST "$BASE_URL/api/v1/admin/auto-coupons/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "VOLTE-3F9A-1C7B"
  }'

Resposta: conferir

200Cupom utilizável

json

{
  "id": 41,
  "rule_id": 3,
  "coupon_code": "VOLTE-3F9A-1C7B",
  "order_id": "9d5b8e61-0a3c-4f7e-8b21-6c4d2f1a9e03",
  "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "discount_type": "percentage",
  "discount_value": 1000,
  "min_order_amount": 15000,
  "max_uses": 1,
  "uses_count": 0,
  "expires_at": "2026-11-10T14:25:00Z",
  "created_at": "2026-10-11T14:25:00Z",
  "coupon_id": 41,
  "code": "VOLTE-3F9A-1C7B",
  "timestamp": 1791728700,
  "expiry_date": 1794320700
}

Campos da resposta

idinteger

Identificador do cupom gerado (inteiro).

rule_idinteger

Regra que o gerou.

coupon_codestring

O código, no formato PREFIXO-XXXX-XXXX (hexadecimal em maiúsculas).

order_iduuid

Pedido que disparou a geração.

user_iduuid

Cliente que ganhou o cupom.

discount_typestring

Copiado da regra no momento da geração.

discount_valueinteger

Copiado da regra.

min_order_amountinteger

Copiado da regra, em centavos.

max_usesinteger

Máximo de usos.

uses_countinteger

Usos até agora.

expires_atstring (RFC 3339) | null

Validade. null = não expira.

vendor_iduuid | omitted

Seller, quando o cupom veio de uma regra de seller.

created_atstring (RFC 3339)

Geração.

coupon_id, code, timestamp, expiry_datemixed

Apelidos de compatibilidade com a plataforma antiga (repetem id, coupon_code, created_at e expires_at, estes dois em segundos Unix). Ignore-os em integrações novas.

Erros: conferir

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Módulo `promotions` ou `auto-coupons` desligado na loja.	`{"error":"module_disabled","module":"auto-coupons"}`
403	Falta o privilégio: `view_auto_coupons` (ou `view_promotions`) para ler, `manage_auto_coupons` (ou `manage_promotions`) para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`code` ausente.	`{"error":"code is required"}`
400	Código inexistente, esgotado ou vencido. O motivo vem em `detail` (em inglês): `coupon not found: ...`, `coupon has been fully redeemed` ou `coupon has expired`.	`{"error":"invalid coupon","detail":"coupon has expired"}`