Alterar categoria

Altera nome, mãe, status, posição, descrição, imagem e SEO de uma categoria, enviando só os campos que mudam.

Use esta operação para renomear uma categoria, mudá-la de lugar na árvore, escondê-la da loja ou reordenar as irmãs. A alteração é parcial: só os campos presentes no corpo mudam; o que você não enviar fica como está.

Mover uma categoria (mudar o parent_id) recalcula o path e a depth dela e de todas as descendentes. O servidor recusa mover uma categoria para dentro de si mesma ou de uma descendente, e recusa a mudança que faria a subárvore passar da profundidade 5.

PUT/api/v1/admin/categories/{id}Admin

Atualiza uma categoria

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio manage_categories. Devolve a categoria completa já alterada.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

namestring

Novo nome. Renomear para o nome de uma irmã viva dá 409.

slugstring

Novo endereço da página. É normalizado (acentos e espaços) e, se já existir, recebe sufixo numérico. Não pode ficar vazio.

descriptionstring

Nova descrição (aceita HTML).

parent_idstring

UUID da nova mãe. Envie string vazia ("") para mover a categoria para o topo. Reenviar a mesma mãe não é uma mudança e não dispara nenhuma verificação.

image_urlstring

Endereço da imagem (/uploads/... ou URL).

icon_urlstring

Endereço do ícone.

positioninteger

Nova posição entre as irmãs.

statusstring

AHD

Novo status, em letra ou por nome. Veja a home da seção para a tabela. Um valor desconhecido vira A. Não envie T ou deleted: para excluir use Excluir categoria.

seo_titlestring

Título de SEO.

seo_descriptionstring

Descrição de SEO.

meta_keywordsstring

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

usergroup_idsarray

Lista de grupos de clientes que podem ver a categoria na loja. Omita para não mudar; envie [] para voltar a mostrá-la a todos.

whatsapp_hiddenboolean

true tira a categoria e seus produtos do catálogo do WhatsApp.

look_tryon_enabledboolean

true liga a prova virtual de look nos produtos da categoria.

descriptionsobject

Textos por idioma, no mesmo formato da criação. Só os idiomas enviados são regravados; os demais ficam intactos.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mesas e bancadas","status":"H","position":20,"image_url":"/uploads/categorias/mesas.png"}'

Resposta

200Categoria alterada

json

{
  "id": "b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
  "parent_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "name": "Mesas e bancadas",
  "slug": "mesas",
  "description": "Mesas para escritório e home office.",
  "image_url": "/uploads/categorias/mesas.png",
  "seo_title": "Mesas de escritório",
  "seo_description": "Mesas retas, em L e de reunião com entrega para todo o Brasil.",
  "position": 20,
  "status": "H",
  "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:51:06.650814Z",
  "category_id": "b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
  "category": "Mesas e bancadas",
  "seo_name": "mesas",
  "timestamp": 1791751854,
  "updated_timestamp": 1791751866
}

A resposta é a categoria completa, com os campos de Listar categorias.

Erros

Status	Quando	Corpo
400	Corpo não é JSON válido	`{"error":"invalid request body","detail":"..."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `manage_categories`	`{"error":"insufficient privileges","required":"manage_categories"}`
409	O novo nome ou a nova mãe cria uma gêmea de uma irmã viva	`{"error":"category_name_exists","existing_id":"...","message":"Já existe a categoria \"Mesas\" neste mesmo nível. ..."}`
500	Categoria não existe, movimento circular, mãe inexistente, profundidade excedida ou slug vazio	`{"error":"failed to update category","detail":"category not found"}`

Veja também