Geração em lote e usos

Gera até 1000 vouchers de uma vez e lista quem usou um voucher.

O lote serve a campanhas: cada cliente ou parceiro recebe um código único com as mesmas regras. Os usos mostram em qual pedido e com que valor o código foi aplicado.

Gerar em lote

POST/api/v1/admin/vouchers/bulkAdmin

Gera vouchers em lote

Corpo da requisição

countintegerobrigatório

Quantos gerar, de 1 a 1000.

typestringobrigatório

fixedpercentagefree_shipping

Tipo.

valueinteger

Centavos ou pontos-base.

min_orderinteger

Pedido mínimo em centavos.

max_usesinteger

Usos totais por código.

max_per_userinteger

Usos por cliente.

starts_atstring

Início.

expires_atstring

Fim.

descriptionstring

Nota interna.

prefixstring

Prefixo dos códigos (vira maiúsculas).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/vouchers/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 3,
    "type": "fixed",
    "value": 1000,
    "max_uses": 1,
    "prefix": "PARCEIRO",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Resposta

201Vouchers gerados

json

{
  "vouchers": [
    {
      "id": 80,
      "vendor_id": null,
      "code": "PARCEIRO-7K2M9QXA",
      "type": "fixed",
      "value": 1000,
      "min_order": 5000,
      "max_uses": 1,
      "used_count": 0,
      "max_per_user": 0,
      "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"
    }
  ],
  "count": 3
}

Campos da resposta

countinteger

Quantos foram criados.

vouchersarray

Os vouchers criados, no formato da lista.

Erros

Status	Quando	Corpo de exemplo
400	`count` fora de 1 a 1000, `type` ou `value` inválidos.	`{"error":"count must be between 1 and 1000, got 5000"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	Módulo `voucher-system` desligado na loja.	`{"error":"module_disabled","module":"voucher-system"}`

Listar os usos

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

Lista os usos de um voucher

Parâmetros de caminho

idintegerobrigatório

Id do voucher.

Exemplo de requisição

bash

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

Resposta

200Usos

json

{
  "redemptions": [
    {
      "id": 15,
      "voucher_id": 79,
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "amount": 599,
      "created_at": "2026-10-11T15:00:00Z"
    }
  ]
}

Campos da resposta

redemptionsarray

Usos do voucher.

redemptions[].user_iduuid

Cliente.

redemptions[].order_iduuid

Pedido.

redemptions[].amountinteger

Desconto realmente aplicado, em centavos.

redemptions[].created_atstring

Quando (RFC 3339).

Erros

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

Veja também

Vouchers

API atual/Referência completa/Vouchers

Geração em lote e usos

Gera até 1000 vouchers de uma vez e lista quem usou um voucher.

O lote serve a campanhas: cada cliente ou parceiro recebe um código único com as mesmas regras. Os usos mostram em qual pedido e com que valor o código foi aplicado.

Gerar em lote

POST/api/v1/admin/vouchers/bulkAdmin

Gera vouchers em lote

Corpo da requisição

countintegerobrigatório

Quantos gerar, de 1 a 1000.

typestringobrigatório

fixedpercentagefree_shipping

Tipo.

valueinteger

Centavos ou pontos-base.

min_orderinteger

Pedido mínimo em centavos.

max_usesinteger

Usos totais por código.

max_per_userinteger

Usos por cliente.

starts_atstring

Início.

expires_atstring

Fim.

descriptionstring

Nota interna.

prefixstring

Prefixo dos códigos (vira maiúsculas).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/vouchers/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 3,
    "type": "fixed",
    "value": 1000,
    "max_uses": 1,
    "prefix": "PARCEIRO",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Resposta

201Vouchers gerados

json

{
  "vouchers": [
    {
      "id": 80,
      "vendor_id": null,
      "code": "PARCEIRO-7K2M9QXA",
      "type": "fixed",
      "value": 1000,
      "min_order": 5000,
      "max_uses": 1,
      "used_count": 0,
      "max_per_user": 0,
      "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"
    }
  ],
  "count": 3
}

Campos da resposta

countinteger

Quantos foram criados.

vouchersarray

Os vouchers criados, no formato da lista.

Erros

Status	Quando	Corpo de exemplo
400	`count` fora de 1 a 1000, `type` ou `value` inválidos.	`{"error":"count must be between 1 and 1000, got 5000"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	Módulo `voucher-system` desligado na loja.	`{"error":"module_disabled","module":"voucher-system"}`

Listar os usos

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

Lista os usos de um voucher

Parâmetros de caminho

idintegerobrigatório

Id do voucher.

Exemplo de requisição

bash

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

Resposta

200Usos

json

{
  "redemptions": [
    {
      "id": 15,
      "voucher_id": 79,
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "amount": 599,
      "created_at": "2026-10-11T15:00:00Z"
    }
  ]
}

Campos da resposta

redemptionsarray

Usos do voucher.

redemptions[].user_iduuid

Cliente.

redemptions[].order_iduuid

Pedido.

redemptions[].amountinteger

Desconto realmente aplicado, em centavos.

redemptions[].created_atstring

Quando (RFC 3339).

Erros

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

Veja também

Vouchers