Cadastro de Usuário

Módulo: Administração Caminho na aplicação: Menu > Administração > Usuários > "Novo Usuário" ou ícone Editar em um registro Última atualização: 20/04/2026

Para que serve

Cria e edita usuários que terão acesso ao sistema. Cada usuário é vinculado a uma ou mais filiais do tenant, com um Perfil de Acesso distinto por filial. Ao criar, o sistema envia automaticamente um e-mail de ativação para que o usuário defina sua senha.

Quem pode usar

Usuários com permissão criar ou editar no módulo Usuários.

Como usar (passo a passo)

Criando um novo usuário

1. Na Lista de Usuários, clique em Novo Usuário.
2. Preencha Nome e Email.
3. Na seção Filiais e Perfis, selecione pelo menos uma filial e um perfil para ela. A primeira filial adicionada é marcada como Padrão automaticamente.
4. Se quiser adicionar mais filiais, clique em Adicionar Filial e repita a seleção.
5. Clique em Cadastrar Usuário.
6. O sistema exibe a mensagem de sucesso, envia o e-mail de ativação e redireciona para a tela de edição do usuário recém-criado.

Editando um usuário existente

1. Na Lista de Usuários, clique no ícone Editar (lápis) na linha do usuário.
2. Ajuste os campos desejados nos cartões Dados Principais e Filiais e Perfis.
3. Na edição é possível alterar a Situação do usuário.
4. Clique em Salvar Alterações.
5. O sistema recarrega os dados do usuário na mesma tela — a tela não fecha.

Gerenciando filiais e perfis

• Clique em Adicionar Filial para incluir uma nova linha na tabela de filiais.
• Selecione a Filial e o Perfil em cada linha.
• Use o toggle Padrão para indicar qual filial o sistema abrirá automaticamente no login. Somente uma filial pode ser padrão; ao ativar uma, as demais são desmarcadas.
• Para remover uma filial, clique na lixeira da linha. O botão fica desabilitado quando há apenas uma linha.

Campos da tela

Cartão: Dados Principais

Campo	Obrigatório	O que preencher	Observações
ID	—	Apenas leitura	Exibido somente na edição; identificador sequencial interno
Situação	Não (criação) / Sim (edição)	Pendente, Ativo, Inativo, Bloqueado	Na criação o campo é bloqueado e assume "Pendente"
Nome	Sim	Nome completo do usuário	Mínimo 2 caracteres
Email	Sim	Endereço de e-mail válido	Usado como login; deve ser único no tenant (⚠️ CONFIRMAR unicidade forçada pelo backend)
Avatar (URL S3)	Não	URL da imagem de perfil armazenada no S3	Campo livre; deixe em branco para usar o avatar padrão

Cartão: Filiais e Perfis

Campo	Obrigatório	O que preencher	Observações
Filial	Sim	Selecione uma das filiais cadastradas	Busca por nome/razão social
Perfil	Sim	Selecione o perfil de acesso para essa filial	Exibe apenas perfis ativos. Ver Lista de Perfis de Acesso
Padrão	Sim (uma deve ser)	Toggle Sim/Não	Indica a filial aberta automaticamente ao fazer login

Validações e regras

• Nome é obrigatório e deve ter no mínimo 2 caracteres.
• Email é obrigatório e deve ser um endereço válido.
• Pelo menos uma filial com Filial e Perfil preenchidos deve existir antes de salvar.
• Não é permitido adicionar a mesma filial duas vezes para o mesmo usuário.
• O campo Situação fica bloqueado na criação (valor fixo: "Pendente") e editável somente na edição.
• Ao criar, o sistema envia um e-mail de ativação para o endereço informado.
• O formulário detecta alterações não salvas e exibe um aviso ao tentar sair sem salvar.

Mensagens de erro e o que fazer

Mensagem	Causa	Como resolver
"Informe o nome"	Campo Nome vazio ao submeter	Preencha o nome do usuário
"Informe o email"	Campo Email vazio ao submeter	Preencha o e-mail
"Email invalido"	E-mail com formato incorreto	Corrija o endereço de e-mail
"Adicione pelo menos uma filial com perfil"	Nenhuma linha de filial tem filial e perfil selecionados	Selecione filial e perfil em pelo menos uma linha
"Existem filiais duplicadas"	A mesma filial aparece em mais de uma linha	Remova a linha duplicada
"Erro ao carregar dados auxiliares"	Falha ao buscar lista de filiais ou perfis	Verifique a conexão e recarregue a página
"Erro ao carregar usuario"	Falha ao buscar os dados do usuário na edição	Verifique a conexão; o sistema redireciona para a lista
"Usuario criado! Um email de ativacao foi enviado."	Sucesso na criação	Informativo — aguardar ativação pelo usuário
"Usuario atualizado com sucesso"	Sucesso na edição	Informativo
Mensagem de erro genérica do backend	Erro retornado pela API	—

Integrações e dependências

• Consome usuariosService.criar() e usuariosService.atualizar().
• Carrega a lista de filiais via filiaisService.listar() (limite 100).
• Carrega a lista de perfis ativos via perfisService.listar({ situacao: 'ativo', limit: 100 }).
• Ao criar, o backend dispara o envio de e-mail de ativação via SES.
• Após a criação, redireciona para /usuarios/:id/editar (replace no histórico).
• Após a edição, recarrega os dados do usuário sem sair da tela.

Dúvidas frequentes

O usuário não recebeu o e-mail de ativação. O que fazer?

Posso alterar o e-mail de um usuário existente? Sim, o campo Email é editável na edição

Qual a diferença entre Inativo e Bloqueado?

Um usuário pode ter perfis diferentes em filiais diferentes? Sim. Cada linha da tabela Filiais e Perfis define, de forma independente, qual perfil o usuário possui em cada filial.

Histórico de alterações

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