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

# POST /api/v1/categories: Nova Categoria de Produtos

> Cria uma nova categoria na loja com nome obrigatório, descrição opcional e campo order para controlar a sequência de exibição no catálogo de produtos.

Use este endpoint para criar uma nova categoria na sua loja. As categorias ajudam a organizar o catálogo de produtos, facilitando a navegação dos clientes. Você pode definir um nome, uma descrição opcional e um número de ordem para controlar a sequência em que a categoria aparece na vitrine.

## Método

`POST /api/v1/categories` — Requer autenticação.

## Parâmetros do Body

<ParamField body="name" type="string" required>
  Nome da categoria. Será exibido no catálogo da loja.
</ParamField>

<ParamField body="description" type="string">
  Descrição da categoria. Campo opcional para fornecer mais contexto sobre os produtos agrupados.
</ParamField>

<ParamField body="order" type="number">
  Controla a ordem de exibição da categoria no catálogo. Valores menores aparecem primeiro. Caso não informado, a categoria será adicionada ao final da lista.
</ParamField>

## Exemplo de Requisição

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/categories' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Nova Categoria",
    "description": "Descrição da categoria",
    "order": 1
  }'
```

## Resposta

```json theme={null}
{
  "message": "Categoria criada com sucesso",
  "category": {
    "id": "cat_456",
    "name": "Nova Categoria",
    "description": "Descrição da categoria",
    "order": 1,
    "createdAt": "2026-05-07T10:00:00.000Z"
  }
}
```

## Campos da Resposta

<ResponseField name="message" type="string">
  Mensagem de confirmação da operação.
</ResponseField>

<ResponseField name="category" type="object">
  Objeto com os dados da categoria recém-criada.

  <Expandable title="Propriedades da categoria">
    <ResponseField name="id" type="string">
      Identificador único gerado automaticamente para a nova categoria.
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome da categoria conforme informado na requisição.
    </ResponseField>

    <ResponseField name="description" type="string">
      Descrição da categoria conforme informada na requisição.
    </ResponseField>

    <ResponseField name="order" type="number">
      Ordem de exibição da categoria no catálogo.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Data e hora de criação da categoria no formato ISO 8601.
    </ResponseField>
  </Expandable>
</ResponseField>


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