API atual/Referência completa/Promoções do seller

Criar, alterar e excluir regra

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

Crie uma regra por campanha de relacionamento: pós-compra, recompra, recompensa para pedidos grandes. A regra vale para os pedidos concluídos a partir de agora, nunca para os antigos. A regra nasce do seller do token (vendor_id do corpo é ignorado) e avalia só a parte do pedido que é dele. O PUT é parcial: envie só o que muda.

Criar uma regra

POST/api/v1/vendor/auto-couponsSeller

Cria uma regra de cupom automático do seller

Corpo da requisição

namestringobrigatório

Nome da regra.

trigger_typestringobrigatório

order_completedfirst_ordernth_ordermin_order_amountmanual

Quando gerar o cupom. Veja a tabela em Consultar cupons automáticos.

discount_typestringobrigatório

percentagefixed

Tipo do desconto.

discount_valueintegerobrigatório

Pontos-base em percentage (1000 = 10%) ou centavos em 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 gerado.

min_order_amountintegerpadrão: 0

Subtotal mínimo, em centavos, para usar o cupom.

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; uma palavra desconhecida também vira A.

send_emailbooleanpadrão: true

Envia o cupom por e-mail ao cliente.

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/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": "",
  "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 da resposta são os descritos em Consultar cupons automáticos.

Alterar uma regra

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

Altera uma regra de cupom automático do seller

Envie só os campos que mudam. Um corpo sem nenhum campo conhecido devolve a regra como está. A alteração vale para os cupons gerados daqui em diante; os cupons já emitidos não mudam.

Parâmetros de caminho

idintegerobrigatório

Id da regra (número inteiro).

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição.

trigger_typestring

order_completedfirst_ordernth_ordermin_order_amountmanual

Novo gatilho.

trigger_valueinteger

Novo parâmetro do gatilho.

coupon_prefixstring

Novo prefixo.

discount_typestring

percentagefixed

Novo tipo de desconto.

discount_valueinteger

Novo valor. Maior que zero.

min_order_amountinteger

Novo subtotal mínimo, em centavos.

max_usesinteger

Novos usos por cupom. Aqui o valor é gravado como enviado, sem o ajuste de zero para 1 da criação.

valid_daysinteger

Nova validade, em dias. Também gravada como enviada.

statusstring

activedisabledAD

Novo status. Use disabled para pausar a regra.

send_emailboolean

Liga ou desliga o e-mail.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/auto-coupons/3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

Resposta: alterar

200Regra alterada

json

{
  "id": 3,
  "name": "10% na segunda compra",
  "trigger_type": "first_order",
  "discount_type": "percentage",
  "discount_value": 1000,
  "status": "D",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "updated_at": "2026-10-11T15:02:44.870Z"
}

A resposta é a regra inteira (trimada aqui).

Excluir uma regra

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

Exclui uma regra de cupom automático do seller

Parâmetros de caminho

idintegerobrigatório

Id da regra (número inteiro).

Resposta: excluir

200Regra excluída

json

{ "message": "rule deleted" }

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	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`id` que não é inteiro.	`{"error":"invalid rule ID","detail":"..."}`
400	Na criação: dado inválido (`name` vazio, `trigger_type`, `discount_type` desconhecido, `discount_value` menor ou igual a zero) ou oferta abaixo do piso de margem da loja. O motivo vem em `detail`.	`{"error":"failed to create rule","detail":"discount_value must be positive"}`
400	Na alteração: a regra não existe (ou é de outro seller), ou o dado é inválido. Aqui não existe `404`.	`{"error":"failed to update rule","detail":"auto-coupon rule not found: 99"}`
404	Na exclusão: a regra não existe ou é de outro seller.	`{"error":"failed to delete rule","detail":"auto-coupon rule not found: 99"}`

Veja também

API atual/Referência completa/Promoções do seller

Criar, alterar e excluir regra

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

Criar uma regra

POST/api/v1/vendor/auto-couponsSeller

Cria uma regra de cupom automático do seller

Corpo da requisição

namestringobrigatório

Nome da regra.

trigger_typestringobrigatório

order_completedfirst_ordernth_ordermin_order_amountmanual

Quando gerar o cupom. Veja a tabela em Consultar cupons automáticos.

discount_typestringobrigatório

percentagefixed

Tipo do desconto.

discount_valueintegerobrigatório

Pontos-base em percentage (1000 = 10%) ou centavos em 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 gerado.

min_order_amountintegerpadrão: 0

Subtotal mínimo, em centavos, para usar o cupom.

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; uma palavra desconhecida também vira A.

send_emailbooleanpadrão: true

Envia o cupom por e-mail ao cliente.

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/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": "",
  "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 da resposta são os descritos em Consultar cupons automáticos.

Alterar uma regra

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

Altera uma regra de cupom automático do seller

Envie só os campos que mudam. Um corpo sem nenhum campo conhecido devolve a regra como está. A alteração vale para os cupons gerados daqui em diante; os cupons já emitidos não mudam.

Parâmetros de caminho

idintegerobrigatório

Id da regra (número inteiro).

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição.

trigger_typestring

order_completedfirst_ordernth_ordermin_order_amountmanual

Novo gatilho.

trigger_valueinteger

Novo parâmetro do gatilho.

coupon_prefixstring

Novo prefixo.

discount_typestring

percentagefixed

Novo tipo de desconto.

discount_valueinteger

Novo valor. Maior que zero.

min_order_amountinteger

Novo subtotal mínimo, em centavos.

max_usesinteger

Novos usos por cupom. Aqui o valor é gravado como enviado, sem o ajuste de zero para 1 da criação.

valid_daysinteger

Nova validade, em dias. Também gravada como enviada.

statusstring

activedisabledAD

Novo status. Use disabled para pausar a regra.

send_emailboolean

Liga ou desliga o e-mail.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/auto-coupons/3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

Resposta: alterar

200Regra alterada

json

{
  "id": 3,
  "name": "10% na segunda compra",
  "trigger_type": "first_order",
  "discount_type": "percentage",
  "discount_value": 1000,
  "status": "D",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "updated_at": "2026-10-11T15:02:44.870Z"
}

A resposta é a regra inteira (trimada aqui).

Excluir uma regra

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

Exclui uma regra de cupom automático do seller

Parâmetros de caminho

idintegerobrigatório

Id da regra (número inteiro).

Resposta: excluir

200Regra excluída

json

{ "message": "rule deleted" }

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	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`id` que não é inteiro.	`{"error":"invalid rule ID","detail":"..."}`
400	Na criação: dado inválido (`name` vazio, `trigger_type`, `discount_type` desconhecido, `discount_value` menor ou igual a zero) ou oferta abaixo do piso de margem da loja. O motivo vem em `detail`.	`{"error":"failed to create rule","detail":"discount_value must be positive"}`
400	Na alteração: a regra não existe (ou é de outro seller), ou o dado é inválido. Aqui não existe `404`.	`{"error":"failed to update rule","detail":"auto-coupon rule not found: 99"}`
404	Na exclusão: a regra não existe ou é de outro seller.	`{"error":"failed to delete rule","detail":"auto-coupon rule not found: 99"}`