Criar categoria

Cria uma categoria de topo ou filha, com status, posição, descrição, imagem, SEO e textos por idioma.

Use esta operação para cadastrar uma categoria nova, por exemplo quando seu ERP ou PIM tem uma família de produtos que ainda não existe na loja. A categoria nasce no nível que você indicar (de topo ou filha de outra) e o servidor calcula path e depth sozinho.

Antes de criar, leia as categorias existentes (Listar categorias): duas categorias vivas com o mesmo nome no mesmo nível não são permitidas, e a segunda recebe erro. O slug (endereço da página) é gerado a partir do nome e, se já existir, ganha um sufixo numérico (-2).

POST/api/v1/admin/categoriesAdmin

Cria uma categoria

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio manage_categories. Corpo em JSON.

Corpo da requisição

namestringobrigatório

Nome da categoria, de 1 a 500 caracteres.

slugstring

Endereço da página. Sem ele, o servidor gera a partir do nome. Acentos e espaços são normalizados (Mesas de Escritório vira mesas-de-escritorio) e, se o slug já existe, recebe um sufixo (-2).

parent_iduuid

Categoria-mãe. Omita para criar uma categoria de topo. Um valor que não é UUID dá 400; um UUID que não existe dá 400 parent category not found.

descriptionstring

Descrição (aceita HTML).

image_urlstring

Endereço (/uploads/... ou URL) de uma imagem que já está na loja.

icon_urlstring

Endereço do ícone da categoria.

positionintegerpadrão: 0

Posição entre as irmãs.

statusstringpadrão: A

AHD

Status inicial. Aceita a letra ou o nome (active, hidden, disabled). Qualquer valor desconhecido vira A, sem erro. Não envie T/deleted: isso cria a categoria já na lixeira.

seo_titlestring

Título de SEO da página.

seo_descriptionstring

Descrição de SEO (meta description).

meta_keywordsstring

Palavras-chave de SEO, separadas por vírgula.

whatsapp_hiddenbooleanpadrão: false

true tira a categoria e seus produtos do catálogo do WhatsApp, sem escondê-la da loja.

descriptionsobject

Textos por idioma. A chave é o código do idioma (pt-BR, en). Os idiomas que você não enviar copiam o texto do idioma padrão.

{lang}.namestring

Nome naquele idioma.

{lang}.descriptionstring

Descrição naquele idioma.

{lang}.seo_titlestring

Título de SEO naquele idioma.

{lang}.seo_descriptionstring

Descrição de SEO naquele idioma.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/categories" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mesas",
    "parent_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
    "status": "A",
    "position": 10,
    "description": "Mesas para escritório e home office.",
    "seo_title": "Mesas de escritório",
    "seo_description": "Mesas retas, em L e de reunião com entrega para todo o Brasil."
  }'

Resposta

201Categoria criada

json

{
  "id": "b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
  "parent_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "name": "Mesas",
  "slug": "mesas",
  "description": "Mesas para escritório e home office.",
  "seo_title": "Mesas de escritório",
  "seo_description": "Mesas retas, em L e de reunião com entrega para todo o Brasil.",
  "position": 10,
  "status": "A",
  "path": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9/b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
  "depth": 1,
  "product_count": 0,
  "created_at": "2026-10-11T20:50:54.571831Z",
  "updated_at": "2026-10-11T20:50:54.571831Z",
  "category_id": "b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
  "category": "Mesas",
  "seo_name": "mesas",
  "timestamp": 1791751854,
  "updated_timestamp": 1791751854
}

A resposta é a categoria completa, com os campos descritos em Listar categorias. A criação avisa a vitrine para renovar o cache das listas e do menu.

Erros

Status	Quando	Corpo
400	Corpo não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	Sem nome	`{"error":"name is required"}`
400	`parent_id` inválido	`{"error":"invalid parent_id","detail":"\"x\" não é o id de uma categoria: parent_id é o uuid da categoria-pai (...)"}`
400	`parent_id` é um UUID que não existe	`{"error":"parent category not found","detail":"nenhuma categoria com o id <uuid>: ... Nada foi criado."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `manage_categories`	`{"error":"insufficient privileges","required":"manage_categories"}`
409	Já existe categoria viva com o mesmo nome na mesma mãe	`{"error":"category_name_exists","existing_id":"345ac33e-...","message":"Já existe a categoria \"Escritório\" neste mesmo nível. Use a existente (id ...) em vez de criar outra com o mesmo nome."}`
500	A nova categoria passaria da profundidade 5, ou falha interna	`{"error":"failed to create category","detail":"category depth exceeds maximum of 5 levels"}`

Veja também