> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bukiopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adicionar Estoque

> Cadastra o estoque de um produto ou de uma variação: itens únicos, estoque ilimitado ou misto.

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. |

<Note>
  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.
</Note>

## Parâmetros de caminho

<ParamField path="id" type="string" required>
  UUID do produto.
</ParamField>

## Parâmetros do corpo

<ParamField body="type" type="string" required>
  `normal`, `ghost` (ilimitado) ou `mixed`.
</ParamField>

<ParamField body="link" type="string">
  Obrigatório no `ghost`. O conteúdo entregue a todos os clientes: um link ou um texto.
</ParamField>

<ParamField body="items" type="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.
</ParamField>

<ParamField body="fixedLink" type="string">
  Obrigatório no `mixed`. A informação fixa que todo cliente recebe junto com a key dele.
</ParamField>

<ParamField body="variantId" type="string">
  UUID da variação. Em produto `variable`, o estoque é de cada variação: envie uma requisição por variação.
</ParamField>

<ParamField body="ghostStockDisplay" type="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.
</ParamField>

## 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.

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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](/api-reference/products/list).

```json theme={null}
{
  "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). |

<Note>
  Itens já entregues não são alterados nem removidos por esses endpoints.
</Note>

## 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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.