Categorias

Como funciona a árvore de categorias da loja, os status, o SEO, a ficha técnica e o mapa de todas as rotas.

Uma categoria é um nó da árvore que organiza o catálogo: "Calçados" tem filhas "Chinelos" e "Sandálias", e cada produto fica ligado a uma ou mais categorias. A categoria também é uma página da loja: ela tem nome, endereço (slug), descrição, imagem e campos de SEO. Use esta seção para sincronizar o catálogo com um ERP ou PIM, montar menus em outro canal ou manter a árvore por script.

Esta seção documenta as rotas de administração de categorias (/api/v1/admin/categories...): nome, pai, status, posição, descrição, imagem, ícone, SEO, idiomas, ações em lote, coleções inteligentes e ficha técnica.

Como funciona

A árvore

Cada categoria guarda o parent_id (a mãe, ausente nas categorias de topo), o path (a cadeia de ids da raiz até ela, separados por /) e a depth (profundidade: 0 para topo, 1 para filha, e assim por diante). Você só escreve o parent_id; path e depth são calculados e atualizados em todas as descendentes quando você move uma categoria.

Regras que o servidor aplica ao criar ou mover:

Uma categoria não pode ser mãe de si mesma nem ser movida para dentro de uma descendente.
A profundidade máxima é 5. Mover uma subárvore inteira que passaria disso é recusado.
Duas categorias vivas (que não estão na lixeira) com o mesmo nome no mesmo nível não podem existir: a segunda recebe 409 category_name_exists com o id da que já existe.
O position ordena as irmãs (número inteiro, padrão 0). Ele é só um valor de ordenação: a plataforma não renumera as outras categorias quando você muda uma.

Os status

Letra	Nome	Lista do painel e das APIs	Loja (vitrine)
`A`	Ativa	aparece	aparece
`D`	Desativada	aparece	escondida (a página responde 404)
`H`	Oculta	aparece	escondida (a página responde 404)
`T`	Lixeira	não aparece	escondida

Detalhes que mudam o resultado:

A vitrine só mostra A. Se a categoria-mãe está D ou H, toda a subárvore dela também some da vitrine, mesmo que as filhas estejam A.
D e T são coisas diferentes. D é uma categoria desligada que você ainda enxerga e pode religar. T é a lixeira: a linha continua guardada, mas fora de todas as listas.
Na entrada, a API aceita a letra ou o nome: A/active/enabled/visible, H/hidden, D/disabled/inactive, T/deleted/trash. Qualquer outro valor (inclusive vazio) vira A, sem erro. Na saída ela sempre devolve a letra.
Mandar T ou deleted no status de uma atualização joga a categoria na lixeira sem o registro que permite restaurá-la. Para excluir, use Excluir categoria.

Excluir, lixeira e cascata

Situação da categoria	`DELETE` sem `cascade`	`DELETE` com `cascade=true`
Vazia, sem filhas vivas	Vai para a lixeira (`T`). Pode ser restaurada em até 30 dias.	Apagada de vez, junto com todas as descendentes.
Com produtos	`409 category_has_products`	Apaga de vez a categoria, as filhas e todos os produtos ligados a elas.
Com filhas vivas	`409 category_has_subcategories`	Apaga de vez a subárvore inteira.

A restauração e o esvaziamento da lixeira são feitos pela rota /api/v1/admin/recycle-bin, que depende do recurso "lixeira" da loja e pertence à referência completa.

Produtos, imagens e SEO

Produtos. Um produto tem uma categoria principal e pode estar em várias outras. Para ler os produtos de uma categoria use Listar produtos com o filtro category_id. A coluna product_count da categoria é uma contagem de apoio e pode ser menor do que a lista do painel, porque segue as regras de visibilidade da loja.
Imagem e ícone. image_url e icon_url guardam o endereço (caminho /uploads/... ou URL) de uma imagem que já está na loja.
SEO. slug (endereço da página), seo_title, seo_description e meta_keywords. Há também um gerador automático e um modelo de texto que alimenta o SEO dos produtos (SEO da categoria).
Idiomas. O texto de uma categoria pode ter uma versão por idioma. Nas leituras passe lang=pt-BR para receber o texto naquele idioma; na criação e na edição use o mapa descriptions.

Conceitos-chave

Ids e slug

Todo id de categoria é um UUID (345ac33e-4dcd-4d60-bedf-a2c2d47897d9). O slug (o endereço público da página) serve para montar links da loja, mas as rotas de administração identificam a categoria sempre pelo UUID.

Permissões

Leitura	Escrita
Privilégio `view_catalog`, `manage_catalog` ou `manage_categories`.	Privilégio `manage_categories`. Coleções inteligentes e ficha técnica pedem `manage_catalog`.

O token vem de POST /api/v1/auth/login. Guarde-o e reaproveite: o login tem limite de requisições (429).

Endpoints

Auth: Admin é o administrador, com Authorization: Bearer <token> e o privilégio indicado na seção "Permissões".

Método	Rota	O que faz	Auth	Página
GET	`/api/v1/admin/categories`	Lista todas as categorias	Admin	Listar categorias
GET	`/api/v1/admin/categories/tree`	Árvore aninhada	Admin	Listar categorias
GET	`/api/v1/admin/categories/{id}`	Consulta uma categoria	Admin	Consultar categoria
POST	`/api/v1/admin/categories`	Cria uma categoria	Admin	Criar categoria
PUT	`/api/v1/admin/categories/{id}`	Altera uma categoria	Admin	Alterar categoria
DELETE	`/api/v1/admin/categories/{id}`	Exclui uma categoria	Admin	Excluir categoria
POST	`/api/v1/admin/categories/bulk`	Muda status, move ou exclui até 100	Admin	Ações em lote
GET	`/api/v1/admin/categories/{id}/seo`	Lê o SEO	Admin	SEO da categoria
PUT	`/api/v1/admin/categories/{id}/seo`	Grava slug, título e descrição de SEO	Admin	SEO da categoria
POST	`/api/v1/admin/categories/{id}/seo/generate`	Gera o SEO a partir do nome	Admin	SEO da categoria
GET	`/api/v1/admin/categories/{id}/seo-template`	Lê o modelo de SEO dos produtos	Admin	SEO da categoria
PUT	`/api/v1/admin/categories/{id}/seo-template`	Grava o modelo de SEO dos produtos	Admin	SEO da categoria
POST	`/api/v1/admin/categories/smart-preview`	Simula uma coleção inteligente	Admin	Coleções inteligentes
PUT	`/api/v1/admin/categories/{id}/smart-rules`	Liga ou desliga a coleção inteligente	Admin	Coleções inteligentes
POST	`/api/v1/admin/categories/{id}/materialize`	Recalcula os produtos da coleção	Admin	Coleções inteligentes
GET	`/api/v1/admin/categories/{id}/feature-template`	Lê a ficha técnica	Admin	Ficha técnica
PUT	`/api/v1/admin/categories/{id}/feature-template`	Grava a ficha técnica	Admin	Ficha técnica

Erros comuns

Mandar parent_id vazio ou "0" para criar uma categoria de topo. O valor é tratado como id e a chamada responde 400 invalid parent_id. Para criar uma categoria de topo, omita o parent_id.
Esperar que DELETE apague de vez. Sem cascade, uma categoria vazia vai para a lixeira: some das listas, mas continua restaurável por 30 dias. Uma categoria com produtos ou filhas recebe 409.
Usar cascade=true por conveniência. Ele apaga os produtos da categoria e das filhas, sem lixeira. Mova os produtos antes se quiser preservá-los.
Gravar a categoria de topo com o mesmo nome de outra. Duas categorias vivas com o mesmo nome no mesmo nível dão 409 category_name_exists. Reaproveite a que já existe (o existing_id vem no erro).
Gravar meta_keywords pelo endpoint de SEO. Ele não grava esse campo. Use PUT /api/v1/admin/categories/{id} (veja SEO da categoria).
Esperar paginação na lista. GET /api/v1/admin/categories devolve todas as categorias de uma vez; para recortar, filtre no seu lado ou use a árvore.

Próximos passos

Listar categorias

Lista plana e árvore.

Criar categoria

Crie uma categoria de topo ou filha.

Excluir categoria

Lixeira, conflitos e cascata.

SEO da categoria

Slug, título, descrição e modelo de texto.

API atual/Guia rápido

Categorias

Como funciona a árvore de categorias da loja, os status, o SEO, a ficha técnica e o mapa de todas as rotas.

Como funciona

A árvore

Regras que o servidor aplica ao criar ou mover:

Uma categoria não pode ser mãe de si mesma nem ser movida para dentro de uma descendente.
A profundidade máxima é 5. Mover uma subárvore inteira que passaria disso é recusado.
Duas categorias vivas (que não estão na lixeira) com o mesmo nome no mesmo nível não podem existir: a segunda recebe 409 category_name_exists com o id da que já existe.
O position ordena as irmãs (número inteiro, padrão 0). Ele é só um valor de ordenação: a plataforma não renumera as outras categorias quando você muda uma.

Os status

Letra	Nome	Lista do painel e das APIs	Loja (vitrine)
`A`	Ativa	aparece	aparece
`D`	Desativada	aparece	escondida (a página responde 404)
`H`	Oculta	aparece	escondida (a página responde 404)
`T`	Lixeira	não aparece	escondida

Detalhes que mudam o resultado:

A vitrine só mostra A. Se a categoria-mãe está D ou H, toda a subárvore dela também some da vitrine, mesmo que as filhas estejam A.
D e T são coisas diferentes. D é uma categoria desligada que você ainda enxerga e pode religar. T é a lixeira: a linha continua guardada, mas fora de todas as listas.
Na entrada, a API aceita a letra ou o nome: A/active/enabled/visible, H/hidden, D/disabled/inactive, T/deleted/trash. Qualquer outro valor (inclusive vazio) vira A, sem erro. Na saída ela sempre devolve a letra.
Mandar T ou deleted no status de uma atualização joga a categoria na lixeira sem o registro que permite restaurá-la. Para excluir, use Excluir categoria.

Excluir, lixeira e cascata

Situação da categoria	`DELETE` sem `cascade`	`DELETE` com `cascade=true`
Vazia, sem filhas vivas	Vai para a lixeira (`T`). Pode ser restaurada em até 30 dias.	Apagada de vez, junto com todas as descendentes.
Com produtos	`409 category_has_products`	Apaga de vez a categoria, as filhas e todos os produtos ligados a elas.
Com filhas vivas	`409 category_has_subcategories`	Apaga de vez a subárvore inteira.

A restauração e o esvaziamento da lixeira são feitos pela rota /api/v1/admin/recycle-bin, que depende do recurso "lixeira" da loja e pertence à referência completa.

Produtos, imagens e SEO

Produtos. Um produto tem uma categoria principal e pode estar em várias outras. Para ler os produtos de uma categoria use Listar produtos com o filtro category_id. A coluna product_count da categoria é uma contagem de apoio e pode ser menor do que a lista do painel, porque segue as regras de visibilidade da loja.
Imagem e ícone. image_url e icon_url guardam o endereço (caminho /uploads/... ou URL) de uma imagem que já está na loja.
SEO. slug (endereço da página), seo_title, seo_description e meta_keywords. Há também um gerador automático e um modelo de texto que alimenta o SEO dos produtos (SEO da categoria).
Idiomas. O texto de uma categoria pode ter uma versão por idioma. Nas leituras passe lang=pt-BR para receber o texto naquele idioma; na criação e na edição use o mapa descriptions.

Conceitos-chave

Ids e slug

Permissões

Leitura	Escrita
Privilégio `view_catalog`, `manage_catalog` ou `manage_categories`.	Privilégio `manage_categories`. Coleções inteligentes e ficha técnica pedem `manage_catalog`.

O token vem de POST /api/v1/auth/login. Guarde-o e reaproveite: o login tem limite de requisições (429).

Endpoints

Auth: Admin é o administrador, com Authorization: Bearer <token> e o privilégio indicado na seção "Permissões".

Método	Rota	O que faz	Auth	Página
GET	`/api/v1/admin/categories`	Lista todas as categorias	Admin	Listar categorias
GET	`/api/v1/admin/categories/tree`	Árvore aninhada	Admin	Listar categorias
GET	`/api/v1/admin/categories/{id}`	Consulta uma categoria	Admin	Consultar categoria
POST	`/api/v1/admin/categories`	Cria uma categoria	Admin	Criar categoria
PUT	`/api/v1/admin/categories/{id}`	Altera uma categoria	Admin	Alterar categoria
DELETE	`/api/v1/admin/categories/{id}`	Exclui uma categoria	Admin	Excluir categoria
POST	`/api/v1/admin/categories/bulk`	Muda status, move ou exclui até 100	Admin	Ações em lote
GET	`/api/v1/admin/categories/{id}/seo`	Lê o SEO	Admin	SEO da categoria
PUT	`/api/v1/admin/categories/{id}/seo`	Grava slug, título e descrição de SEO	Admin	SEO da categoria
POST	`/api/v1/admin/categories/{id}/seo/generate`	Gera o SEO a partir do nome	Admin	SEO da categoria
GET	`/api/v1/admin/categories/{id}/seo-template`	Lê o modelo de SEO dos produtos	Admin	SEO da categoria
PUT	`/api/v1/admin/categories/{id}/seo-template`	Grava o modelo de SEO dos produtos	Admin	SEO da categoria
POST	`/api/v1/admin/categories/smart-preview`	Simula uma coleção inteligente	Admin	Coleções inteligentes
PUT	`/api/v1/admin/categories/{id}/smart-rules`	Liga ou desliga a coleção inteligente	Admin	Coleções inteligentes
POST	`/api/v1/admin/categories/{id}/materialize`	Recalcula os produtos da coleção	Admin	Coleções inteligentes
GET	`/api/v1/admin/categories/{id}/feature-template`	Lê a ficha técnica	Admin	Ficha técnica
PUT	`/api/v1/admin/categories/{id}/feature-template`	Grava a ficha técnica	Admin	Ficha técnica

Erros comuns

Mandar parent_id vazio ou "0" para criar uma categoria de topo. O valor é tratado como id e a chamada responde 400 invalid parent_id. Para criar uma categoria de topo, omita o parent_id.
Esperar que DELETE apague de vez. Sem cascade, uma categoria vazia vai para a lixeira: some das listas, mas continua restaurável por 30 dias. Uma categoria com produtos ou filhas recebe 409.
Usar cascade=true por conveniência. Ele apaga os produtos da categoria e das filhas, sem lixeira. Mova os produtos antes se quiser preservá-los.
Gravar a categoria de topo com o mesmo nome de outra. Duas categorias vivas com o mesmo nome no mesmo nível dão 409 category_name_exists. Reaproveite a que já existe (o existing_id vem no erro).
Gravar meta_keywords pelo endpoint de SEO. Ele não grava esse campo. Use PUT /api/v1/admin/categories/{id} (veja SEO da categoria).
Esperar paginação na lista. GET /api/v1/admin/categories devolve todas as categorias de uma vez; para recortar, filtre no seu lado ou use a árvore.

Próximos passos

Listar categorias

Lista plana e árvore.

Criar categoria

Crie uma categoria de topo ou filha.

Excluir categoria

Lixeira, conflitos e cascata.

SEO da categoria

Slug, título, descrição e modelo de texto.