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

Criar, alterar e excluir regra

Cadastra, ajusta e remove uma regra de cupom automático.

Crie uma regra por campanha de relacionamento: pós-compra, reativação de quem comprou uma vez, recompensa para pedidos grandes. A regra vale para os pedidos concluídos a partir de agora. O PUT é parcial: envie só o que muda. Se a loja usa o Protetor de Margem, a criação é recusada quando o desconto levaria a margem abaixo do piso (a mensagem vem em detail).

Criar uma regra

POST/api/v1/admin/auto-couponsAdmin

Cria uma regra de cupom automático

Corpo da requisição

namestringobrigatório
Nome da regra.
trigger_typestringobrigatório
order_completedfirst_ordernth_ordermin_order_amountmanual
Quando gerar o cupom.
discount_typestringobrigatório
percentagefixed
Tipo do desconto.
discount_valueintegerobrigatório
Pontos-base (percentage) ou centavos (fixed). Maior que zero.
descriptionstring
Descrição livre.
trigger_valueintegerpadrão: 0
N de nth_order ou mínimo em centavos de min_order_amount.
coupon_prefixstringpadrão: AUTO
Prefixo do código.
min_order_amountintegerpadrão: 0
Subtotal mínimo para usar o cupom, em centavos.
max_usesintegerpadrão: 1
Usos por cupom gerado. Zero ou negativo vira 1.
valid_daysintegerpadrão: 30
Dias de validade do cupom gerado. Zero ou negativo vira 30.
statusstringpadrão: active
active ou disabled (ou A/D). Vazio vira A.
send_emailbooleanpadrão: true
Envia o cupom por e-mail ao cliente.
vendor_iduuid
Torna a regra de um seller. Omita para regra da loja.

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/admin/auto-coupons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "10% na segunda compra",
    "trigger_type": "first_order",
    "discount_type": "percentage",
    "discount_value": 1000,
    "coupon_prefix": "VOLTE",
    "min_order_amount": 15000,
    "valid_days": 30
  }'

Resposta: criar

201Regra criada
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: criar

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"}
400Nome vazio, trigger_type ou discount_type fora da lista, discount_value menor ou igual a zero, corpo inválido ou oferta abaixo do piso de margem. Todas as recusas desta rota são 400, com o motivo em detail.{"error":"failed to create rule","detail":"invalid trigger_type: monthly"}

Alterar uma regra

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

Altera campos de uma regra

Parâmetros de caminho

idintegerobrigatório
Id da regra (inteiro).

Corpo da requisição

namestring
Nome da regra.
trigger_typestring
order_completedfirst_ordernth_ordermin_order_amountmanual
Quando gerar o cupom.
discount_typestring
percentagefixed
Tipo do desconto.
discount_valueinteger
Pontos-base (percentage) ou centavos (fixed). Maior que zero.
descriptionstring
Descrição livre.
trigger_valueinteger
N de nth_order ou mínimo em centavos de min_order_amount.
coupon_prefixstring
Prefixo do código.
min_order_amountinteger
Subtotal mínimo para usar o cupom, em centavos.
max_usesinteger
Usos por cupom gerado. Zero ou negativo vira 1.
valid_daysinteger
Dias de validade do cupom gerado. Zero ou negativo vira 30.
statusstring
active ou disabled (ou A/D). Vazio vira A.
send_emailboolean
Envia o cupom por e-mail ao cliente.
vendor_iduuid
Torna a regra de um seller. Omita para regra da loja.

Exemplo de requisição: alterar

bash
curl -X PUT "$BASE_URL/api/v1/admin/auto-coupons/3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_value": 1500,
    "valid_days": 45
  }'

Resposta: alterar

200Regra alterada
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": 1500,
  "min_order_amount": 15000,
  "max_uses": 1,
  "valid_days": 45,
  "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: alterar

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\". ..."}
400Validação (discount_value, trigger_type, discount_type), corpo inválido, ou regra inexistente (auto-coupon rule not found).{"error":"failed to update rule","detail":"auto-coupon rule not found: 99999"}

Excluir uma regra

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

Exclui uma regra e os registros de cupons gerados

Parâmetros de caminho

idintegerobrigatório
Id da regra (inteiro).

Exemplo de requisição: excluir

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

Resposta: excluir

200Regra excluída
json
{
  "message": "rule deleted"
}

Erros: excluir

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\". ..."}
404Regra inexistente.{"error":"failed to delete rule","detail":"auto-coupon rule not found: 99999"}
Para parar de emitir, desative; não exclua

Envie {"status":"disabled"} para a regra deixar de gerar cupons sem perder o histórico. A exclusão apaga o registro de todos os cupons já gerados por ela (a lista de Cupons gerados fica sem eles) e não revoga os códigos que os clientes já têm.

Um cupom por cliente por regra

Cada pedido concluído que casa com a regra gera um cupom novo. Em order_completed, um cliente que compra cinco vezes ganha cinco cupons. Prefira first_order ou nth_order quando a ideia é premiar uma vez.

Veja também

  • Cupons automáticos: visão geral
  • Consultar regras
  • Cupons gerados
Anterior
Consultar regras
Próxima
Cupons gerados
Nesta página
  • Criar uma regra
  • Exemplo de requisição: criar
  • Resposta: criar
  • Erros: criar
  • Alterar uma regra
  • Exemplo de requisição: alterar
  • Resposta: alterar
  • Erros: alterar
  • Excluir uma regra
  • Exemplo de requisição: excluir
  • Resposta: excluir
  • Erros: excluir
  • Veja também