VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Promoções do seller

Consultar cupons automáticos

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

Um cupom automático é um cupom que a plataforma gera e entrega sozinha depois que um cliente conclui uma compra: "fez o primeiro pedido, ganha 10% na próxima". O seller não cria cada código: ele cadastra uma regra (gatilho, desconto, validade) e, a cada pedido concluído que casar com ela, nasce um código único para aquele cliente, enviado por e-mail. Estas rotas leem as regras do seller. A regra de seller avalia só a parte do pedido que é dele e o cupom gerado só desconta os itens dele.

Quando a regra dispara (trigger_type):

trigger_typeGera o cupom quandotrigger_value
order_completedQualquer pedido é concluído.Ignorado
first_orderÉ o primeiro pedido concluído do cliente.Ignorado
nth_orderO número de pedidos concluídos do cliente é exatamente N.O N
min_order_amountO valor do pedido é igual ou maior que o mínimo.Mínimo em centavos
manualNunca sozinho: reservado a campanhas que geram o código por conta própria.Ignorado

Listar regras

GET/api/v1/vendor/auto-couponsSeller

Lista as regras de cupom automático do seller

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 dessa faixa volta a 20.
searchstring
Texto procurado no nome ou no prefixo do código (sem diferenciar maiúsculas).

Exemplo de requisição: listar

Resposta: listar

200Página de regras

Campos da resposta

rulesarray

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

idinteger
Identificador da regra. É um número inteiro, não UUID.
namestring
Nome da regra.
descriptionstring
Descrição livre.
trigger_typestring
Quando gerar o cupom (tabela acima).
trigger_valueinteger
Parâmetro do gatilho: N em nth_order, mínimo em centavos em min_order_amount.
coupon_prefixstring
Prefixo do código gerado (padrão AUTO).
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. Só regras A disparam.
send_emailboolean
Se o cliente recebe o cupom por e-mail.
vendor_iduuid
Seller dono da regra: sempre o seu.
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.

Detalhar uma regra

GET/api/v1/vendor/auto-coupons/{id}Seller

Detalha uma regra de cupom automático do seller

Parâmetros de caminho

idintegerobrigatório
Id da regra (número inteiro).

Resposta: detalhar

200Regra encontrada

Os campos são os de cada item de rules.

Erros

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"missing authorization header"}
403O token não é de um usuário seller, ou o seller não tem privilégio de configurações.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings", "..."]}
400No detalhe: id que não é número inteiro.{"error":"invalid rule ID","detail":"strconv.Atoi: parsing \"abc\": invalid syntax"}
404No detalhe: a regra não existe ou é de outro seller.{"error":"rule not found","detail":"auto-coupon rule not found: 99"}
500Falha ao listar.{"error":"failed to list auto-coupon rules","detail":"..."}
Mensagens em inglês

As mensagens invalid rule ID e rule not found voltam em inglês, como no exemplo. detail pode trazer o texto técnico do Go; não dependa dele.

O cupom não é preso ao cliente

O código gerado fica gravado com o cliente que o ganhou e o checkout limita a 1 uso por cliente, mas quem tiver o código pode digitá-lo. Use max_uses baixo e valid_days curto em campanhas sensíveis.

Veja também

  • Criar, alterar e excluir regra
  • Consultar promoções
  • Visão geral
Anterior
Criar, alterar e excluir promoção
Próxima
Criar, alterar e excluir regra
Nesta página
  • Listar regras
  • Exemplo de requisição: listar
  • Resposta: listar
  • Detalhar uma regra
  • Resposta: detalhar
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/vendor/auto-coupons?per_page=20" \
  -H "Authorization: Bearer $TOKEN"
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,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "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
}
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,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T14:20:05.113Z",
  "updated_at": "2026-10-11T14:20:05.113Z"
}