Criar categoria

Cria uma categoria de topo ou filha, com status, posição e descrição.

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.0/categoriesAdmin

Criar uma categoria

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Bearer <JWT>. Corpo em JSON.

Corpo da requisição

categorystringobrigatório

Nome da categoria. É também a base do slug.

parent_idstring

UUID da categoria-mãe. Omita para criar uma categoria de topo: "0" e string vazia são rejeitados com erro 400.

statusstringpadrão: A

AHD

Status inicial, em letra ou por nome (active, hidden, disabled). Um valor desconhecido vira A. Não envie T: isso cria a categoria já na lixeira.

positionintegerpadrão: 0

Posição entre as irmãs.

descriptionstring

Descrição (aceita HTML).

company_idstring

Aceito por compatibilidade e ignorado: a categoria pertence à loja.

POST/api/categoriesAdmin

Criar uma categoria (rota sem /v1.0)

A mesma operação sem o /v1.0, com o mesmo corpo. A resposta traz o category_id como UUID.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/categories" \
  -H "Content-Type: application/json" \
  -d '{"category":"Mesas","parent_id":"345ac33e-4dcd-4d60-bedf-a2c2d47897d9","status":"A","position":10}'

Resposta

201Categoria criada

json

{ "category_id": "b854c1fa-3318-408d-baa7-343de4fbce09" }

Campos da resposta

category_idstring

UUID da categoria criada. Para ler os demais campos, consulte-a (Consultar categoria).

Erros

Status	Quando	Corpo
400	Corpo não é JSON válido	`{"message":"Invalid JSON","status":400}`
400	Sem nome	`{"message":"Field 'category' is required","status":400}`
400	`parent_id` é um UUID que não existe	`{"message":"parent category not found: <uuid>","status":400}`
400	`parent_id` com `"0"`, vazio ou texto que não é UUID	`{"message":"get parent category: query category 0: pq: invalid input syntax for type uuid: \"0\" (22P02)","status":400}`
400	Já existe categoria com esse nome na mesma mãe	`{"message":"category name \"Escritório\" already exists under this parent (id 345ac33e-...)","status":400}`
401	Sem credenciais ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Não é administrador	`{"message":"Forbidden: admin scope required","status":403}`

Veja também