VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cupons automáticos

Consultar regras

Lista as regras de cupom automático e detalha uma regra.

Use a lista para ver quais regras estão ativas e o que cada uma entrega. O detalhe devolve a mesma estrutura de um item da lista.

Listar regras

GET/api/v1/admin/auto-couponsAdmin

Lista as regras de cupom automático

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. Fora disso volta a 20.
searchstring
Parte do nome ou do prefixo, sem diferenciar maiúsculas.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/admin/auto-coupons?per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Página de regras
json
{
  "rules": [
    {
      "id": 3,
      "name": "10% na segunda compra",
      "description": "Cupom enviado depois do primeiro pedido concluído",
      "trigger_type": "first_order",
      "trigger_value": 0,
      "coupon_prefix": "VOLTE",
      "discount_type": "percentage",
      "discount_value": 1000,
      "min_order_amount": 15000,
      "max_uses": 1,
      "valid_days": 30,
      "status": "A",
      "send_email": true,
      "created_at": "2026-10-11T14:20:05.113Z",
      "updated_at": "2026-10-11T14:20:05.113Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

rulesarray

Regras da página, da mais nova para a mais antiga. Sem resultados vem null.

idinteger
Identificador da regra. Atenção: é um número inteiro, não UUID.
namestring
Nome da regra.
descriptionstring
Descrição livre.
trigger_typestring
Quando gerar o cupom (veja a tabela na home da seção).
trigger_valueinteger
Parâmetro do gatilho: o valor mínimo do pedido em centavos (min_order_amount) ou o N (nth_order). Ignorado nos demais.
coupon_prefixstring
Prefixo do código gerado.
discount_typestring
percentage ou fixed.
discount_valueinteger
Pontos-base em percentage (1000 = 10%); centavos em fixed.
min_order_amountinteger
Subtotal mínimo, em centavos, para usar o cupom gerado.
max_usesinteger
Quantas vezes cada cupom gerado pode ser usado.
valid_daysinteger
Validade do cupom gerado, em dias a partir da geração.
statusstring
A ativa ou D desativada.
send_emailboolean
Se o cliente recebe o cupom por e-mail.
vendor_iduuid | omitted
Seller dono da regra. Ausente = regra da loja.
created_atstring (RFC 3339)
Criação.
updated_atstring (RFC 3339)
Última alteração.
totalinteger
Total de regras que casam com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página.
total_pagesinteger
Total de páginas.

Erros: listar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403Módulo promotions ou auto-coupons desligado na loja.{"error":"module_disabled","module":"auto-coupons"}
403Falta 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"}

Detalhar uma regra

GET/api/v1/admin/auto-coupons/{id}Admin

Detalha uma regra de cupom automático

Parâmetros de caminho

idintegerobrigatório
Id da regra (inteiro).

Exemplo de requisição: detalhar

bash
curl "$BASE_URL/api/v1/admin/auto-coupons/3" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Regra
json
{
  "id": 3,
  "name": "10% na segunda compra",
  "description": "Cupom enviado depois do primeiro pedido concluído",
  "trigger_type": "first_order",
  "trigger_value": 0,
  "coupon_prefix": "VOLTE",
  "discount_type": "percentage",
  "discount_value": 1000,
  "min_order_amount": 15000,
  "max_uses": 1,
  "valid_days": 30,
  "status": "A",
  "send_email": true,
  "created_at": "2026-10-11T14:20:05.113Z",
  "updated_at": "2026-10-11T14:20:05.113Z"
}

Campos da resposta

idinteger
Identificador da regra. Atenção: é um número inteiro, não UUID.
namestring
Nome da regra.
descriptionstring
Descrição livre.
trigger_typestring
Quando gerar o cupom (veja a tabela na home da seção).
trigger_valueinteger
Parâmetro do gatilho: o valor mínimo do pedido em centavos (min_order_amount) ou o N (nth_order). Ignorado nos demais.
coupon_prefixstring
Prefixo do código gerado.
discount_typestring
percentage ou fixed.
discount_valueinteger
Pontos-base em percentage (1000 = 10%); centavos em fixed.
min_order_amountinteger
Subtotal mínimo, em centavos, para usar o cupom gerado.
max_usesinteger
Quantas vezes cada cupom gerado pode ser usado.
valid_daysinteger
Validade do cupom gerado, em dias a partir da geração.
statusstring
A ativa ou D desativada.
send_emailboolean
Se o cliente recebe o cupom por e-mail.
vendor_iduuid | omitted
Seller dono da regra. Ausente = regra da loja.
created_atstring (RFC 3339)
Criação.
updated_atstring (RFC 3339)
Última alteração.

Erros: detalhar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403Módulo promotions ou auto-coupons desligado na loja.{"error":"module_disabled","module":"auto-coupons"}
403Falta 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"}
400O id da regra não é um número inteiro.{"error":"invalid rule ID","detail":"número em formato não aceito: \"abc\". ..."}
404Não existe regra com esse id.{"error":"rule not found","detail":"auto-coupon rule not found: 99999"}
Lista vazia é `null`

Quando não há regras, rules vem como null e não como []. Trate os dois casos no seu código.

Veja também

  • Cupons automáticos: visão geral
  • Criar, alterar e excluir regra
  • Cupons gerados
Anterior
Cupons automáticos
Próxima
Criar, alterar e excluir regra
Nesta página
  • Listar regras
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Detalhar uma regra
  • Exemplo de requisição: detalhar
  • Resposta: detalhar
  • Erros: detalhar
  • Veja também