Cadastro de Categoria

Módulo: Produtos Caminho na aplicação: Menu > Produtos > Categorias > "Nova Categoria" ou ícone Editar na lista Última atualização: 20/04/2026

Para que serve

Criar e editar categorias de produtos com suporte a hierarquia de até 3 níveis. Cada categoria pode ter uma comissão padrão e uma imagem associada.

Quem pode usar

Qualquer usuário com acesso ao módulo de Produtos.

Como usar (passo a passo)

Criar uma categoria:

1. Acesse Menu > Produtos > Categorias e clique em Nova Categoria.
2. Preencha a descrição (obrigatório).
3. Selecione uma Categoria Pai para criar uma subcategoria; deixe em branco para criar uma categoria raiz (nível 1).
4. Informe a comissão padrão se necessário.
5. Clique em Cadastrar Categoria. O sistema redireciona para a tela de edição da categoria recém-criada.

Editar uma categoria:

1. Na Lista de Categorias, clique no ícone Editar (lápis) na linha da categoria ou subcategoria desejada.
2. Altere os campos e clique em Salvar Alterações. O sistema permanece na tela de edição.

Adicionar imagem (somente na edição):

1. No modo de edição, localize o card "Imagem".
2. Use o componente de upload para enviar a imagem ao S3.

Campos da tela

Campo	Obrigatório	O que preencher	Observações
ID	Não (leitura)	—	Exibido somente na edição; identificador interno sequencial
Status	Não	Ativo / Inativo	Padrão: Ativo
Descrição	Sim	Nome da categoria	Mensagem: "Informe a descricao"
Categoria Pai (opcional)	Não	Selecione a categoria pai para criar uma subcategoria	Placeholder: "Nenhuma (nível 1)". Apenas categorias de nível 1 e 2 podem ser pai. A categoria atual não aparece nas opções
Comissão %	Não	Percentual de comissão padrão para produtos desta categoria	Padrão: 0. Mín: 0, Máx: 100; precisão: 2 casas decimais
Imagem	Não	Upload de imagem (somente na edição)	Armazenada no S3; suporta visualização e exclusão

Validações e regras

• Descrição é o único campo obrigatório.
• Categorias de nível 3 não podem ser pai de outra categoria (hierarquia máxima: 3 níveis).
• Uma categoria não pode ser definida como pai de si mesma.
• O rótulo do seletor de pai indica o nível: "└ Subcategoria (Nível 2)".
• Ao criar, o sistema redireciona para /categorias/:id/editar com replace: true.
• Ao editar, o sistema recarrega o registro após salvar, sem redirecionar.
• Se houver alterações não salvas, o sistema avisa ao tentar sair.
• O upload de imagem só está disponível no modo de edição.

Mensagens de erro e o que fazer

Mensagem	Causa	Como resolver
"Informe a descricao"	Campo Descrição vazio ao salvar	Preencha o nome da categoria
"Categoria criada com sucesso"	Criação bem-sucedida	—
"Categoria atualizada com sucesso"	Edição bem-sucedida	—
"Erro ao carregar categoria"	Falha ao buscar dados na API	Verifique a conexão; o sistema retorna à lista de categorias
"Erro ao salvar categoria"	—	Verifique a mensagem retornada e corrija os dados informados

Integrações e dependências

• Lista de Categorias: ponto de entrada para acessar este formulário.
• Cadastro de Produto: categorias são vinculadas a produtos no campo "Categoria".
• AWS S3: imagem da categoria armazenada via upload multipart.
• categoriasService — endpoints POST /categorias, PUT /categorias/:id, GET /categorias/:id, POST /categorias/:id/imagem, DELETE /categorias/:id/imagem.

Dúvidas frequentes

Quantos níveis de hierarquia a categoria suporta? Até 3 níveis: categoria raiz (nível 1) → subcategoria (nível 2) → subcategoria de subcategoria (nível 3).

Por que não consigo selecionar uma categoria de nível 3 como pai? O sistema bloqueia essa seleção para manter a hierarquia máxima de 3 níveis. Apenas categorias de nível 1 e 2 aparecem no seletor de pai.

Posso alterar o nível de uma categoria depois de criá-la? Sim. Altere o campo "Categoria Pai" na edição. O nível é recalculado automaticamente pelo backend.

Qual a diferença entre Categoria e Grupo? Ambos organizam produtos. Categorias suportam 3 níveis de hierarquia. Grupos suportam 2 níveis. O uso depende da necessidade de organização do tenant.

Histórico de alterações

Data	Alteração
20/04/2026	Documento inicial criado.