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

Vouchers

Lista, consulta, cria, altera e apaga vouchers.

Operações sobre um voucher de cada vez.

Listar vouchers

GET/api/v1/admin/vouchersAdmin

Lista vouchers

Parâmetros de consulta

searchstring
Trecho do código ou da descrição.
statusstring
activeexpiredinactiveexhausted
active (ligado e não expirado), expired, inactive ou exhausted (usos esgotados).
typestring
fixed, percentage ou free_shipping.
vendor_iduuid
Só vouchers deste seller.
marketplace_onlyboolean
true = só os da loja toda.
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página; fora de 1 a 100 vale 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vouchers?status=active&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vouchers
json
{
  "vouchers": [
    {
      "id": 79,
      "vendor_id": null,
      "code": "BEMVINDO10",
      "type": "percentage",
      "value": 1000,
      "min_order": 5000,
      "max_uses": 500,
      "used_count": 0,
      "max_per_user": 1,
      "starts_at": "2026-10-11T00:00:00Z",
      "expires_at": "2026-12-31T23:59:59Z",
      "is_active": true,
      "description": "Primeira compra",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 38,
  "page": 1,
  "per_page": 20,
  "total_pages": 2
}

Campos da resposta

totalinteger
Total.
pageinteger
Página.
per_pageinteger
Tamanho.
total_pagesinteger
Total de páginas.
vouchersarray
Vouchers.
idinteger
Id do voucher.
vendor_iduuid|null
Seller dono; null = vale para a loja toda.
codestring
Código em maiúsculas.
typestring
fixedpercentagefree_shipping
fixed, percentage ou free_shipping.
valueinteger
Centavos (fixed) ou pontos-base (percentage).
min_orderinteger
Pedido mínimo em centavos.
max_usesinteger
Limite total de usos; 0 = ilimitado.
used_countinteger
Usos já feitos.
max_per_userinteger
Limite por cliente; 0 = ilimitado.
starts_atstring|null
Início da validade (RFC 3339).
expires_atstring|null
Fim da validade (RFC 3339).
is_activeboolean
Ligado.
descriptionstring
Nota interna.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403Módulo voucher-system desligado na loja.{"error":"module_disabled","module":"voucher-system"}

Consultar um voucher

GET/api/v1/admin/vouchers/{id}Admin

Consulta um voucher

Parâmetros de caminho

idintegerobrigatório
Id do voucher.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vouchers/79" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Voucher
json
{
  "id": 79,
  "vendor_id": null,
  "code": "BEMVINDO10",
  "type": "percentage",
  "value": 1000,
  "min_order": 5000,
  "max_uses": 500,
  "used_count": 0,
  "max_per_user": 1,
  "starts_at": "2026-10-11T00:00:00Z",
  "expires_at": "2026-12-31T23:59:59Z",
  "is_active": true,
  "description": "Primeira compra",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger
Id do voucher.
vendor_iduuid|null
Seller dono; null = vale para a loja toda.
codestring
Código em maiúsculas.
typestring
fixedpercentagefree_shipping
fixed, percentage ou free_shipping.
valueinteger
Centavos (fixed) ou pontos-base (percentage).
min_orderinteger
Pedido mínimo em centavos.
max_usesinteger
Limite total de usos; 0 = ilimitado.
used_countinteger
Usos já feitos.
max_per_userinteger
Limite por cliente; 0 = ilimitado.
starts_atstring|null
Início da validade (RFC 3339).
expires_atstring|null
Fim da validade (RFC 3339).
is_activeboolean
Ligado.
descriptionstring
Nota interna.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400id não numérico.{"error":"invalid voucher id"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403Módulo voucher-system desligado na loja.{"error":"module_disabled","module":"voucher-system"}
404Voucher inexistente.{"error":"voucher not found"}

Criar um voucher

POST/api/v1/admin/vouchersAdmin

Cria um voucher

Corpo da requisição

codestring
Código. Vazio = gerado. Vira maiúsculas.
typestringobrigatório
fixedpercentagefree_shipping
Tipo de desconto.
valueinteger
Centavos ou pontos-base. fixed: maior que 0. percentage: de 1 a 10000. Ignorado em free_shipping.
min_orderintegerpadrão: 0
Pedido mínimo em centavos.
max_usesintegerpadrão: 0
Limite total; 0 = ilimitado.
max_per_userintegerpadrão: 0
Limite por cliente; 0 = ilimitado.
starts_atstring
Início (RFC 3339).
expires_atstring
Fim (RFC 3339).
is_activebooleanpadrão: true
Padrão true.
descriptionstring
Nota interna.
vendor_iduuid
Restringe a um seller.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/vouchers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BEMVINDO10",
    "type": "percentage",
    "value": 1000,
    "min_order": 5000,
    "max_uses": 500,
    "max_per_user": 1,
    "expires_at": "2026-12-31T23:59:59Z",
    "description": "Primeira compra"
  }'

Resposta

201Voucher criado
json
{
  "id": 79,
  "vendor_id": null,
  "code": "BEMVINDO10",
  "type": "percentage",
  "value": 1000,
  "min_order": 5000,
  "max_uses": 500,
  "used_count": 0,
  "max_per_user": 1,
  "starts_at": "2026-10-11T00:00:00Z",
  "expires_at": "2026-12-31T23:59:59Z",
  "is_active": true,
  "description": "Primeira compra",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger
Id do voucher.
vendor_iduuid|null
Seller dono; null = vale para a loja toda.
codestring
Código em maiúsculas.
typestring
fixedpercentagefree_shipping
fixed, percentage ou free_shipping.
valueinteger
Centavos (fixed) ou pontos-base (percentage).
min_orderinteger
Pedido mínimo em centavos.
max_usesinteger
Limite total de usos; 0 = ilimitado.
used_countinteger
Usos já feitos.
max_per_userinteger
Limite por cliente; 0 = ilimitado.
starts_atstring|null
Início da validade (RFC 3339).
expires_atstring|null
Fim da validade (RFC 3339).
is_activeboolean
Ligado.
descriptionstring
Nota interna.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400type inválido, value fora da regra do tipo ou código repetido.{"error":"percentage voucher value must be 1-10000 basis points (0.01%-100%)"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403Módulo voucher-system desligado na loja.{"error":"module_disabled","module":"voucher-system"}
422O desconto derruba produtos abaixo do piso do Protetor de Margem. O corpo é o detalhamento do protetor.{"allowed":false,"...":"..."}

Alterar um voucher

Atualização parcial: só os campos enviados mudam. used_count não pode ser editado.

PUT/api/v1/admin/vouchers/{id}Admin

Altera um voucher

Parâmetros de caminho

idintegerobrigatório
Id do voucher.

Corpo da requisição

codestring
Novo código. Vira maiúsculas. Não envie string vazia.
typestring
fixedpercentagefree_shipping
Tipo do desconto. Ao enviar type, envie value junto: um value omitido é validado como 0 e é recusado em fixed e percentage.
valueinteger
Centavos ou pontos-base. fixed: maior que 0. percentage: de 1 a 10000. Ignorado em free_shipping.
min_orderinteger
Pedido mínimo em centavos.
max_usesinteger
Limite total; 0 = ilimitado.
max_per_userinteger
Limite por cliente; 0 = ilimitado.
starts_atstring
Início (RFC 3339).
expires_atstring
Fim (RFC 3339).
is_activeboolean
Liga ou desliga o cupom.
descriptionstring
Nota interna.
vendor_iduuid
Restringe a um seller.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/vouchers/79" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "max_uses": 1000
  }'

Resposta

200Voucher alterado
json
{
  "id": 79,
  "vendor_id": null,
  "code": "BEMVINDO10",
  "type": "percentage",
  "value": 1000,
  "min_order": 5000,
  "max_uses": 1000,
  "used_count": 0,
  "max_per_user": 1,
  "starts_at": "2026-10-11T00:00:00Z",
  "expires_at": "2026-12-31T23:59:59Z",
  "is_active": false,
  "description": "Primeira compra",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger
Id do voucher.
vendor_iduuid|null
Seller dono; null = vale para a loja toda.
codestring
Código em maiúsculas.
typestring
fixedpercentagefree_shipping
fixed, percentage ou free_shipping.
valueinteger
Centavos (fixed) ou pontos-base (percentage).
min_orderinteger
Pedido mínimo em centavos.
max_usesinteger
Limite total de usos; 0 = ilimitado.
used_countinteger
Usos já feitos.
max_per_userinteger
Limite por cliente; 0 = ilimitado.
starts_atstring|null
Início da validade (RFC 3339).
expires_atstring|null
Fim da validade (RFC 3339).
is_activeboolean
Ligado.
descriptionstring
Nota interna.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400id inválido, corpo inválido, tipo/valor inválido ou código repetido.{"error":"voucher code already exists"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403Módulo voucher-system desligado na loja.{"error":"module_disabled","module":"voucher-system"}
404Voucher inexistente.{"error":"voucher 79 not found"}

Apagar um voucher

DELETE/api/v1/admin/vouchers/{id}Admin

Apaga um voucher

Parâmetros de caminho

idintegerobrigatório
Id do voucher.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/vouchers/79" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado
json
{
  "message": "voucher deleted"
}

Erros

StatusQuandoCorpo de exemplo
400id não numérico.{"error":"invalid voucher id"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403Módulo voucher-system desligado na loja.{"error":"module_disabled","module":"voucher-system"}
404Voucher inexistente.{"error":"voucher 79 not found"}
Definitivo

Para pausar o código mantendo o histórico, use PUT com is_active: false.

Veja também

  • Vouchers
Anterior
Vouchers
Próxima
Geração em lote e usos
Nesta página
  • Listar vouchers
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um voucher
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar um voucher
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um voucher
  • Exemplo de requisição
  • Resposta
  • Erros
  • Apagar um voucher
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também