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_type`	Gera o cupom quando	`trigger_value`
`order_completed`	Qualquer pedido é concluído.	Ignorado
`first_order`	É o primeiro pedido concluído do cliente.	Ignorado
`nth_order`	O número de pedidos concluídos do cliente é exatamente N.	O N
`min_order_amount`	O valor do pedido é igual ou maior que o mínimo.	Mínimo em centavos
`manual`	Nunca 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

bash

curl "$BASE_URL/api/v1/vendor/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,
      "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
}

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

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"
}

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

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O 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", "..."]}`
400	No detalhe: `id` que não é número inteiro.	`{"error":"invalid rule ID","detail":"strconv.Atoi: parsing \"abc\": invalid syntax"}`
404	No detalhe: a regra não existe ou é de outro seller.	`{"error":"rule not found","detail":"auto-coupon rule not found: 99"}`
500	Falha ao listar.	`{"error":"failed to list auto-coupon rules","detail":"..."}`

Veja também

Consultar cupons automáticos

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

Quando a regra dispara (trigger_type):

`trigger_type`	Gera o cupom quando	`trigger_value`
`order_completed`	Qualquer pedido é concluído.	Ignorado
`first_order`	É o primeiro pedido concluído do cliente.	Ignorado
`nth_order`	O número de pedidos concluídos do cliente é exatamente N.	O N
`min_order_amount`	O valor do pedido é igual ou maior que o mínimo.	Mínimo em centavos
`manual`	Nunca 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

bash

curl "$BASE_URL/api/v1/vendor/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,
      "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
}

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

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"
}

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

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O 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", "..."]}`
400	No detalhe: `id` que não é número inteiro.	`{"error":"invalid rule ID","detail":"strconv.Atoi: parsing \"abc\": invalid syntax"}`
404	No detalhe: a regra não existe ou é de outro seller.	`{"error":"rule not found","detail":"auto-coupon rule not found: 99"}`
500	Falha ao listar.	`{"error":"failed to list auto-coupon rules","detail":"..."}`