Referência da API

Cupons

Códigos de desconto que o cliente usa no carrinho. O código não pode ser igual ao de um afiliado (os dois usam o mesmo campo no carrinho).

Rotas deste grupo5

GET/couponsListar cuponscoupons:read
POST/couponsCriar cupomcoupons:create
GET/coupons/{id}Ver um cupomcoupons:read
PATCH/coupons/{id}Editar cupomcoupons:update
DELETE/coupons/{id}Apagar cupomcoupons:delete

Listar cupons

GET/api/v1/coupons

Do mais novo para o mais antigo.

Permissão: coupons:read

Parâmetros da URL

`active`	booleano	Valendo ou pausados.
`q`	texto	Busca pelo código.
`page`	inteiro	Página, a partir de 1. Padrão 1.
`per_page`	inteiro	Itens por página, de 1 a 100. Padrão 20.

Exemplo

curl

curl https://zolvibot.app/api/v1/coupons \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "data": [
    {
      "id": "cmw9c0up00001sscoupon0001",
      "code": "BLACK10",
      "percent_off": 10,
      "amount_off_cents": null,
      "max_uses": 100,
      "uses": 12,
      "expires_at": "2026-11-30T02:59:59.000Z",
      "active": true,
      "created_at": "2026-11-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

Criar cupom

POST/api/v1/coupons

Desconto em porcentagem ou em valor (um dos dois).

Permissão: coupons:create

Corpo (JSON)

`code`obrigatório	texto	3 a 32 letras, números, - ou _ (vira maiúsculo).
`percent_off`	inteiro	De 1 a 95.
`amount_off_cents`	inteiro	Desconto fixo em centavos.
`max_uses`	inteiro \| null	Limite de usos (vazio: sem limite).
`expires_at`	data ISO \| null	Validade.
`active`	booleano	Valendo (padrão true).
`announce`	booleano	true posta o cupom no canal público da loja.

Exemplo

curl

curl -X POST https://zolvibot.app/api/v1/coupons \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"code":"BLACK10","percent_off":10,"max_uses":100,"expires_at":"2026-11-30T23:59:59-03:00"}'

Resposta 201

{
  "id": "cmw9c0up00001sscoupon0001",
  "code": "BLACK10",
  "percent_off": 10,
  "amount_off_cents": null,
  "max_uses": 100,
  "uses": 0,
  "expires_at": "2026-11-30T02:59:59.000Z",
  "active": true,
  "created_at": "2026-11-01T12:00:00.000Z",
  "announced": false
}

Ver um cupom

GET/api/v1/coupons/{id}

Pelo id ou pelo código.

Permissão: coupons:read

Exemplo

curl

curl https://zolvibot.app/api/v1/coupons/BLACK10 \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "id": "cmw9c0up00001sscoupon0001",
  "code": "BLACK10",
  "percent_off": 10,
  "amount_off_cents": null,
  "max_uses": 100,
  "uses": 12,
  "expires_at": "2026-11-30T02:59:59.000Z",
  "active": true,
  "created_at": "2026-11-01T12:00:00.000Z"
}

Editar cupom

PATCH/api/v1/coupons/{id}

code, percent_off ou amount_off_cents (mandar um troca o tipo), max_uses, expires_at e active.

Permissão: coupons:update

Exemplo

curl

curl -X PATCH https://zolvibot.app/api/v1/coupons/BLACK10 \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'

Resposta 200

{
  "id": "cmw9c0up00001sscoupon0001",
  "code": "BLACK10",
  "percent_off": 10,
  "amount_off_cents": null,
  "max_uses": 100,
  "uses": 12,
  "expires_at": "2026-11-30T02:59:59.000Z",
  "active": false,
  "created_at": "2026-11-01T12:00:00.000Z"
}

Apagar cupom

DELETE/api/v1/coupons/{id}

Só cupom nunca usado em pedido; usado, pause com active: false.

Permissão: coupons:delete

Exemplo

curl

curl -X DELETE https://zolvibot.app/api/v1/coupons/BLACK10 \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "deleted": true,
  "id": "cmw9c0up00001sscoupon0001"
}