Adicionar Estoque

Cadastra o que o cliente recebe quando a compra é paga. Sem estoque, o produto não pode ser vendido. Método: POST /api/v1/products/:id/stock Autenticação: Obrigatória. Inclua o header Authorization: Bearer sk_live_sua_api_key. Escopo necessário: catalog.write.

Tipos de estoque

`type`	Como funciona	Quando usar
`normal`	Cada item é entregue a um único cliente e sai do estoque.	Contas, keys e códigos únicos.
`ghost`	Estoque ilimitado. Todo cliente recebe o mesmo conteúdo e o estoque nunca acaba.	Recargas, links de acesso, cursos, arquivos e serviços.
`mixed`	Uma informação fixa para todos (`fixedLink`) mais uma key única por cliente (`items`).	Uma instrução comum somada a uma key individual.

Ao trocar o tipo do estoque, os itens disponíveis do tipo anterior são removidos. No ghost, enviar de novo substitui o conteúdo anterior.

Parâmetros de caminho

string

required

UUID do produto.

Parâmetros do corpo

string

required

normal, ghost (ilimitado) ou mixed.

string

Obrigatório no ghost. O conteúdo entregue a todos os clientes: um link ou um texto.

array

Obrigatório no normal e no mixed. No normal, aceita textos (["KEY-1", "KEY-2"]) ou objetos ([{ "link": "KEY-1" }]). No mixed, envie objetos com link. Até 250 itens por produto ou variação.

string

Obrigatório no mixed. A informação fixa que todo cliente recebe junto com a key dele.

string

UUID da variação. Em produto variable, o estoque é de cada variação: envie uma requisição por variação.

number | null

Só no ghost. Número exibido como estoque na loja (por exemplo, 100). Envie null para não mostrar número. A venda não é limitada por ele.

Estoque ilimitado

O caso mais comum em recargas e produtos digitais. O cliente recebe o link depois do pagamento, e o produto nunca fica sem estoque.

curl -X POST 'https://api.bukiopay.com/api/v1/products/c3b4168f-d732-44ed-8c67-6080cec06b09/stock' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "ghost",
    "link": "Sua recarga será creditada em até 10 minutos no Player ID informado.",
    "ghostStockDisplay": null
  }'

Resposta:

{
  "message": "Estoque fantasma adicionado com sucesso",
  "items": [
    {
      "id": "5b2f0a8e-7c41-4d3a-9e6b-1f2a3b4c5d6e",
      "product_id": "c3b4168f-d732-44ed-8c67-6080cec06b09",
      "variant_id": null,
      "type": "ghost",
      "link": "Sua recarga será creditada em até 10 minutos no Player ID informado.",
      "status": "available"
    }
  ],
  "totalAdded": 1,
  "isGhost": true
}

Na listagem de produtos, o produto com estoque ilimitado vem com stock: null.

Itens únicos

curl -X POST 'https://api.bukiopay.com/api/v1/products/c3b4168f-d732-44ed-8c67-6080cec06b09/stock' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "normal",
    "items": ["KEY-AAAA-1111", "KEY-BBBB-2222"]
  }'

Resposta:

{
  "message": "Estoque adicionado com sucesso",
  "items": [
    { "id": "0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a", "type": "normal", "link": "KEY-AAAA-1111", "status": "available" },
    { "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b", "type": "normal", "link": "KEY-BBBB-2222", "status": "available" }
  ],
  "totalAdded": 2,
  "newStock": 2
}

newStock é o total disponível depois do cadastro. Os itens novos são somados aos que já existem.

Estoque de uma variação

Envie o variantId da variação. Os ids vêm em variations[].id na listagem de produtos.

{
  "type": "ghost",
  "link": "Recarga de 100 diamantes enviada para o Player ID informado.",
  "variantId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

Outros endpoints de estoque

Todos com o escopo catalog.write.

Método	Endpoint	O que faz
`PUT`	`/api/v1/products/:id/stock/:itemId`	Troca o conteúdo de um item disponível. Corpo: `{ "link": "novo conteúdo" }`.
`DELETE`	`/api/v1/products/:id/stock/:itemId`	Remove um item disponível.
`DELETE`	`/api/v1/products/:id/stock`	Remove todo o estoque disponível do produto e das variações. Responde com `removedCount`.
`POST`	`/api/v1/products/:id/stock/file`	Estoque ilimitado com um arquivo de até 50 MB, enviado como `multipart/form-data` no campo `file` (e `variantId`, se for de uma variação).

Itens já entregues não são alterados nem removidos por esses endpoints.

Erros comuns

Status	Mensagem	Causa
`400`	Tipo de estoque inválido. Deve ser “ghost”, “normal” ou “mixed”	`type` ausente ou diferente dos três.
`400`	Para estoque ilimitado, é obrigatório informar um conteúdo (link ou texto)	`ghost` sem `link`.
`400`	Para estoque misto, o fixedLink (informação fixa) é obrigatório	`mixed` sem `fixedLink`.
`400`	Limite de 250 itens por produto…	Passou do limite de itens disponíveis.
`403`	Esta chave não tem a permissão…	A chave não tem `catalog.write`.

Introdução à API

Cobranças PIX

Saques

Webhooks

Pedidos

Produtos

Campos Personalizados

Categorias

Cupons

Loja

Adicionar Estoque

Tipos de estoque

Parâmetros de caminho

Parâmetros do corpo

Estoque ilimitado

Itens únicos

Estoque de uma variação

Outros endpoints de estoque

Erros comuns

​Tipos de estoque

​Parâmetros de caminho

​Parâmetros do corpo

​Estoque ilimitado

​Itens únicos

​Estoque de uma variação

​Outros endpoints de estoque

​Erros comuns

Tipos de estoque

Parâmetros de caminho

Parâmetros do corpo

Estoque ilimitado

Itens únicos

Estoque de uma variação

Outros endpoints de estoque

Erros comuns