Referência da API

Estoque

Os itens únicos de cada opção (keys, contas, links): cada um é entregue para um comprador só. Itens vendidos nunca mudam nem saem (ficam no histórico do pedido). Mudanças disparam STOCK_UPDATED.

Rotas deste grupo5

GET/products/{id}/stockListar estoquestock:read
POST/products/{id}/stockAdicionar estoquestock:create
PATCH/products/{id}/stock/{itemId}Editar itemstock:update
DELETE/products/{id}/stock/{itemId}Remover um itemstock:delete
DELETE/products/{id}/stockRemover vários itensstock:delete

Listar estoque

GET/api/v1/products/{id}/stock

Na ordem em que saem (os mais antigos primeiro). Traz o conteúdo de cada item.

Permissão: stock:read

Parâmetros da URL

`variant_id`	texto	Só de uma opção.
`status`	texto	available (livres) ou sold (vendidos).
`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/ID/stock \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "data": [
    {
      "id": "cmw8g0stk0001ssstock00001",
      "variant_id": "cmvrllzcq000cssokzx1yq2pa",
      "content": "XK3F-9QPL-22MZ",
      "sold": false,
      "order_number": null,
      "delivered_at": null,
      "created_at": "2026-11-08T20:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

Adicionar estoque

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

Até 5.000 itens por envio e 10.000 livres por opção; cada item com até 1.000 caracteres. O que já existe no produto (livre ou vendido) é ignorado e contado em skipped.

Permissão: stock:create

Corpo (JSON)

`variant_id`obrigatório	texto	A opção que recebe os itens.
`items`obrigatório	lista de textos	Um item por posição.

Exemplo

curl

curl -X POST https://zolvibot.app/api/v1/products/ID/stock \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":"cmvrllzcq000cssokzx1yq2pa","items":["XK3F-9QPL-22MZ","B7TR-4WNA-81CD"]}'

Resposta 201

{
  "added": 2,
  "skipped": 0,
  "stock_available": 44
}

Editar item

PATCH/api/v1/products/{id}/stock/{itemId}

Troca o conteúdo de um item livre. Não aceita conteúdo que já está no produto.

Permissão: stock:update

Corpo (JSON)

contentobrigatório texto O conteúdo novo.

Exemplo

curl

curl -X PATCH https://zolvibot.app/api/v1/products/ID/stock/ITEM_ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"content":"XK3F-9QPL-22MX"}'

Resposta 200

{
  "id": "cmw8g0stk0001ssstock00001",
  "variant_id": "cmvrllzcq000cssokzx1yq2pa",
  "content": "XK3F-9QPL-22MX",
  "sold": false
}

Remover um item

DELETE/api/v1/products/{id}/stock/{itemId}

Só item livre.

Permissão: stock:delete

Exemplo

curl

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

Resposta 200

{
  "removed": 1
}

Remover vários itens

DELETE/api/v1/products/{id}/stock

Envie ids (itens escolhidos) ou variant_id com all_available: true (todos os livres da opção).

Permissão: stock:delete

Corpo (JSON)

`ids`	lista de textos	Ids dos itens (até 5.000).
`variant_id`	texto	A opção, junto com all_available.
`all_available`	booleano	true remove todos os livres da opção.

Exemplo

curl

curl -X DELETE https://zolvibot.app/api/v1/products/ID/stock \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":"cmvrllzcq000cssokzx1yq2pa","all_available":true}'

Resposta 200

{
  "removed": 42
}