Referência da API

Produtos e opções

Cada produto tem uma ou mais opções (ex.: 7D, 30D), cada uma com preço e estoque próprios. stock_available é null quando não há limite (entrega fixa sem teto, ou produto só com cargo). Mudanças disparam PRODUCT_* e reescrevem o painel publicado no Discord em segundos.

Rotas deste grupo8

GET/productsListar produtosproducts:read
GET/products/{id}Ver um produtoproducts:read
POST/productsCriar produtoproducts:create
PATCH/products/{id}Editar produtoproducts:update
DELETE/products/{id}Apagar produtoproducts:delete
POST/products/{id}/variantsCriar opçãoproducts:update
PATCH/products/{id}/variants/{variantId}Editar opçãoproducts:update
DELETE/products/{id}/variants/{variantId}Apagar opçãoproducts:delete

Listar produtos

GET/api/v1/products

Com as opções e o estoque disponível de cada uma.

Permissão: products:read

Parâmetros da URL

`active`	booleano	true só os à venda; false só os pausados.
`q`	texto	Busca pelo nome.
`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/products \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "data": [
    {
      "id": "cmvrllzcq000bssokqrrb39n8",
      "name": "Key Steam",
      "description": "Key de ativação na Steam.",
      "image_url": "https://exemplo.com/key.png",
      "active": true,
      "published": true,
      "role_id": null,
      "role_days": null,
      "allowed_role_ids": [],
      "min_quantity": null,
      "max_quantity": 5,
      "hide_stock": false,
      "question": null,
      "delivery_note": "Resgate em store.steampowered.com/account/redeemwalletcode",
      "variants": [
        {
          "id": "cmvrllzcq000cssokzx1yq2pa",
          "name": "30D",
          "price_cents": 1500,
          "compare_at_cents": 1990,
          "cost_cents": 500,
          "active": true,
          "position": 0,
          "fixed_delivery": false,
          "stock_available": 42
        }
      ],
      "created_at": "2026-10-28T04:10:00.000Z",
      "updated_at": "2026-11-08T15:31:12.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

Ver um produto

GET/api/v1/products/{id}

Com as opções e o estoque.

Permissão: products:read

Exemplo

curl

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

Resposta 200

{
  "id": "cmvrllzcq000bssokqrrb39n8",
  "name": "Key Steam",
  "description": "Key de ativação na Steam.",
  "image_url": "https://exemplo.com/key.png",
  "active": true,
  "published": true,
  "role_id": null,
  "role_days": null,
  "allowed_role_ids": [],
  "min_quantity": null,
  "max_quantity": 5,
  "hide_stock": false,
  "question": null,
  "delivery_note": "Resgate em store.steampowered.com/account/redeemwalletcode",
  "variants": [
    {
      "id": "cmvrllzcq000cssokzx1yq2pa",
      "name": "30D",
      "price_cents": 1500,
      "compare_at_cents": 1990,
      "cost_cents": 500,
      "active": true,
      "position": 0,
      "fixed_delivery": false,
      "stock_available": 42
    }
  ],
  "created_at": "2026-10-28T04:10:00.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}

Criar produto

POST/api/v1/products

Nasce com uma opção (Padrão, ou o nome em variant_name) com o preço informado. Depois, adicione opções e estoque.

Permissão: products:create

Corpo (JSON)

`name`obrigatório	texto	Nome, de 2 a 80 caracteres.
`description`	texto	Descrição (até 2.000 caracteres).
`image_url`	texto \| null	Imagem por link https.
`active`	booleano	À venda (padrão true). false pausa o produto.
`role_id`	texto \| null	Cargo do Discord entregue na compra (ID).
`role_days`	inteiro \| null	Prazo do cargo (7, 30, 90 ou 365): vira assinatura. Exige role_id.
`allowed_role_ids`	lista de textos	Só quem tem um desses cargos compra (até 10). Vazio: todos.
`min_quantity / max_quantity`	inteiro \| null	Quantidade por pedido, de 1 a 99.
`hide_stock`	booleano	Mostra só “Em estoque” ou “Esgotado” no Discord.
`question`	texto \| null	Pergunta feita ao cliente antes do Pix (até 100).
`delivery_note`	texto \| null	Mensagem junto da entrega (até 500).
`price_cents`obrigatório	inteiro	Preço da primeira opção, em centavos (mínimo 100).
`cost_cents`	inteiro \| null	Quanto você paga por unidade (para o lucro).
`variant_name`	texto	Nome da primeira opção (padrão: Padrão).

Exemplo

curl

curl -X POST https://zolvibot.app/api/v1/products \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Key Steam","price_cents":1500,"cost_cents":500,"description":"Key de ativação na Steam."}'

Resposta 201

{
  "id": "cmvrllzcq000bssokqrrb39n8",
  "name": "Key Steam",
  "description": "Key de ativação na Steam.",
  "image_url": "https://exemplo.com/key.png",
  "active": true,
  "published": true,
  "role_id": null,
  "role_days": null,
  "allowed_role_ids": [],
  "min_quantity": null,
  "max_quantity": 5,
  "hide_stock": false,
  "question": null,
  "delivery_note": "Resgate em store.steampowered.com/account/redeemwalletcode",
  "variants": [
    {
      "id": "cmvrllzcq000cssokzx1yq2pa",
      "name": "30D",
      "price_cents": 1500,
      "compare_at_cents": 1990,
      "cost_cents": 500,
      "active": true,
      "position": 0,
      "fixed_delivery": false,
      "stock_available": 42
    }
  ],
  "created_at": "2026-10-28T04:10:00.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}

Editar produto

PATCH/api/v1/products/{id}

Muda só os campos enviados; null limpa os opcionais. Preço e estoque ficam nas opções.

Permissão: products:update

Corpo (JSON)

`name`	texto	Nome, de 2 a 80 caracteres.
`description`	texto	Descrição (até 2.000 caracteres).
`image_url`	texto \| null	Imagem por link https.
`active`	booleano	À venda (padrão true). false pausa o produto.
`role_id`	texto \| null	Cargo do Discord entregue na compra (ID).
`role_days`	inteiro \| null	Prazo do cargo (7, 30, 90 ou 365): vira assinatura. Exige role_id.
`allowed_role_ids`	lista de textos	Só quem tem um desses cargos compra (até 10). Vazio: todos.
`min_quantity / max_quantity`	inteiro \| null	Quantidade por pedido, de 1 a 99.
`hide_stock`	booleano	Mostra só “Em estoque” ou “Esgotado” no Discord.
`question`	texto \| null	Pergunta feita ao cliente antes do Pix (até 100).
`delivery_note`	texto \| null	Mensagem junto da entrega (até 500).

Exemplo

curl

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

Resposta 200

{
  "id": "cmvrllzcq000bssokqrrb39n8",
  "name": "Key Steam",
  "description": "Key de ativação na Steam.",
  "image_url": "https://exemplo.com/key.png",
  "active": false,
  "published": true,
  "role_id": null,
  "role_days": null,
  "allowed_role_ids": [],
  "min_quantity": null,
  "max_quantity": 5,
  "hide_stock": false,
  "question": null,
  "delivery_note": "Resgate em store.steampowered.com/account/redeemwalletcode",
  "variants": [
    {
      "id": "cmvrllzcq000cssokzx1yq2pa",
      "name": "30D",
      "price_cents": 1500,
      "compare_at_cents": 1990,
      "cost_cents": 500,
      "active": true,
      "position": 0,
      "fixed_delivery": false,
      "stock_available": 42
    }
  ],
  "created_at": "2026-10-28T04:10:00.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}

Apagar produto

DELETE/api/v1/products/{id}

Só produto nunca vendido nem publicado no Discord (o estoque vai junto). Nos outros casos, pause com active: false.

Permissão: products:delete

Exemplo

curl

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

Resposta 200

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

Criar opção

POST/api/v1/products/{id}/variants

Até 25 por produto (limite do menu do Discord), sem nome repetido. Devolve o produto inteiro.

Permissão: products:update

Corpo (JSON)

`name`obrigatório	texto	Nome, de 1 a 40 caracteres (ex.: 30D).
`price_cents`obrigatório	inteiro	Preço em centavos (mínimo 100).
`cost_cents`	inteiro \| null	Custo por unidade.
`compare_at_cents`	inteiro \| null	Preço “de” (riscado), maior que o preço.
`active`	booleano	À venda (padrão true).

Exemplo

curl

curl -X POST https://zolvibot.app/api/v1/products/ID/variants \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"90D","price_cents":3990,"compare_at_cents":4990}'

Resposta 201

{
  "id": "cmvrllzcq000bssokqrrb39n8",
  "name": "Key Steam",
  "description": "Key de ativação na Steam.",
  "image_url": "https://exemplo.com/key.png",
  "active": true,
  "published": true,
  "role_id": null,
  "role_days": null,
  "allowed_role_ids": [],
  "min_quantity": null,
  "max_quantity": 5,
  "hide_stock": false,
  "question": null,
  "delivery_note": "Resgate em store.steampowered.com/account/redeemwalletcode",
  "variants": [
    {
      "id": "cmvrllzcq000cssokzx1yq2pa",
      "name": "30D",
      "price_cents": 1500,
      "compare_at_cents": 1990,
      "cost_cents": 500,
      "active": true,
      "position": 0,
      "fixed_delivery": false,
      "stock_available": 42
    }
  ],
  "created_at": "2026-10-28T04:10:00.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}

Editar opção

PATCH/api/v1/products/{id}/variants/{variantId}

name, price_cents, cost_cents, compare_at_cents e active. Devolve o produto inteiro.

Permissão: products:update

Exemplo

curl

curl -X PATCH https://zolvibot.app/api/v1/products/ID/variants/VARIANT_ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"price_cents":3490}'

Resposta 200

{
  "id": "cmvrllzcq000bssokqrrb39n8",
  "name": "Key Steam",
  "description": "Key de ativação na Steam.",
  "image_url": "https://exemplo.com/key.png",
  "active": true,
  "published": true,
  "role_id": null,
  "role_days": null,
  "allowed_role_ids": [],
  "min_quantity": null,
  "max_quantity": 5,
  "hide_stock": false,
  "question": null,
  "delivery_note": "Resgate em store.steampowered.com/account/redeemwalletcode",
  "variants": [
    {
      "id": "cmvrllzcq000cssokzx1yq2pa",
      "name": "30D",
      "price_cents": 1500,
      "compare_at_cents": 1990,
      "cost_cents": 500,
      "active": true,
      "position": 0,
      "fixed_delivery": false,
      "stock_available": 42
    }
  ],
  "created_at": "2026-10-28T04:10:00.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}

Apagar opção

DELETE/api/v1/products/{id}/variants/{variantId}

Só opção sem vendas, e o produto precisa ficar com pelo menos uma. As keys livres dela vão junto.

Permissão: products:delete

Exemplo

curl

curl -X DELETE https://zolvibot.app/api/v1/products/ID/variants/VARIANT_ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "id": "cmvrllzcq000bssokqrrb39n8",
  "name": "Key Steam",
  "description": "Key de ativação na Steam.",
  "image_url": "https://exemplo.com/key.png",
  "active": true,
  "published": true,
  "role_id": null,
  "role_days": null,
  "allowed_role_ids": [],
  "min_quantity": null,
  "max_quantity": 5,
  "hide_stock": false,
  "question": null,
  "delivery_note": "Resgate em store.steampowered.com/account/redeemwalletcode",
  "variants": [
    {
      "id": "cmvrllzcq000cssokzx1yq2pa",
      "name": "30D",
      "price_cents": 1500,
      "compare_at_cents": 1990,
      "cost_cents": 500,
      "active": true,
      "position": 0,
      "fixed_delivery": false,
      "stock_available": 42
    }
  ],
  "created_at": "2026-10-28T04:10:00.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}