Categorias

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 categorias da API legada (/api/v1.0/categories... e a forma sem versão /api/categories...), o contrato compatível com a Venddor 1.0 (o mesmo contrato que os clientes antigos já usam). Ela cobre o essencial da árvore: nome, mãe, status, posição e descrição.

Como funciona

A árvore

Cada categoria guarda o parent_id (a mãe, "0" nas categorias de topo), o id_path (a cadeia de ids da raiz até ela, separados por /) e a posição. Você só escreve o parent_id; o caminho é calculado e atualizado em todas as descendentes quando você move uma categoria.

Escritório                       id_path = A
  Mesas                          id_path = A/B
    Mesas de reunião             id_path = A/B/C

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 erro 400 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

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

Produtos, imagem e SEO

• Produtos. Um produto tem uma categoria principal e pode estar em várias outras. Para ler os produtos de uma categoria use Produtos da categoria. O campo 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. Quando a categoria tem imagem, a leitura traz main_pair com o endereço dela.
• SEO. A leitura traz seo_name (o slug), page_title, meta_description e meta_keywords. Esses campos são só de leitura nesta API.

Conceitos-chave

Ids e slug

Em /api/v1.0, todo id de categoria é um UUID (345ac33e-4dcd-4d60-bedf-a2c2d47897d9). Em GET, PUT e DELETE o trecho {id} também aceita o slug da categoria (o seo_name da resposta) ou o parâmetro category_code. Já a forma sem versão (/api/categories) devolve o category_id e o parent_id como números decimais em string, mas não aceita esses números de volta no caminho (o servidor responde 500). Use o UUID ou o slug.

Autenticação e permissão

Formato das respostas

Endpoints

Auth: Admin é o administrador, autenticado por HTTP Basic ou Bearer JWT. As leituras aceitam qualquer credencial válida.

Erros comuns

1. Mandar parent_id: "0" ou vazio. A leitura devolve "0" para categorias de topo, mas na criação e na edição o 0 e a string vazia são tratados como id e dão 400 com uma mensagem técnica do banco. Para criar uma categoria de topo, omita o parent_id.
2. Ler o status. A leitura sempre devolve A, mesmo para categorias ocultas, desativadas ou na lixeira.
3. 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.
4. 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.
5. Criar uma categoria com o mesmo nome de uma irmã. Duas categorias vivas com o mesmo nome no mesmo nível dão 400. Reaproveite a que já existe.
6. Usar o id decimal da forma /api/categories de volta no caminho. A rota responde 500. Guarde o UUID ou o slug.
7. Esperar que a escrita aceite SEO ou imagem. A criação e a alteração gravam só nome, mãe, status, posição e descrição.

Próximos passos