Consultar usuário
Retorna os dados de um usuário pelo ID.
Atualizar usuário (administrativo)
Edita os dados cadastrais de um usuário da empresa do contexto. Perfil exigido: Administrador da empresa edita qualquer usuário; um usuário comum só edita a si mesmo e apenas `nome`, `email` e `celular`. Alterar `tipo` reescreve as permissões do usuário na empresa; alterar `login` muda o acesso; alterar `email` dispara o e-mail de confirmação. Para editar só o próprio cadastro, PUT /v1/usuarios também serve. Para alterar permissões por unidade use PUT /v1/usuarios/permissoes. Operação administrativa que altera acesso e dados pessoais. Exija confirmação humana antes de executar a partir de um agente autônomo.
Atualizar o próprio usuário
Atualiza `nome`, `email` e `celular` do PRÓPRIO usuário autenticado (o ID vem do token). Para editar outro usuário use PUT /v1/usuarios/{id} (administrativo).
Buscar usuários
Busca usuários por nome/filtros (Search, TipoUsuario, UnidadeId etc.) - o campo usuario da resposta é o ID a usar em ExecutorId/EmitenteId/UsuarioId. Ver [Glossário de IDs e enums](/guides/glossario-ids-enums).
Criar usuário
Cria um usuário na empresa do contexto, já com as permissões correspondentes ao `tipo`, e dispara o e-mail para o PRÓPRIO usuário definir a senha — a API nunca recebe nem define senha. Use no onboarding de uma pessoa nova (fluxo administrativo; ver a receita 'Cadastrar usuário e definir permissões com IA'). Perfil exigido: Administrador da empresa. `permissaoInicial` (ID de GET /v1/permissoes) é obrigatória para os tipos 3 (Operacional) e 4 (Chamado) e ignorada para o tipo 2 (Administrador). Login único entre usuários ativos e e-mail único por empresa (422 se já existirem). Responde 201 com o `usuario` criado e as permissões geradas; 201 NÃO garante que o e-mail foi enviado — confira `linkDefinicaoSenhaEnviado` e, se `false`, use POST /v1/usuarios/{id}/reenviar-definicao-senha. Não repita este POST por falha de e-mail: o login já existe. NÃO envie o header `UnidadeId` neste POST: para os tipos 3 e 4 ele cria uma linha de permissão extra para essa unidade (e o tipo 2 recebe permissão em TODAS as unidades ativas). O cabeçalho `Location` do 201 pode vir com `http://` (a API roda atrás de proxy TLS): não o siga automaticamente — use o `usuario` do corpo. Efeito externo (cria acesso ao sistema e envia e-mail). Exija confirmação humana antes de executar a partir de um agente autônomo.
Renovar sessão do usuário
Renova o token de sessão do usuário (RefreshUserSessionCommand) - distinto do refresh de JWT do AuthCenter descrito em Autenticação.
Salvar assinatura do usuário
Define/atualiza a assinatura registrada de um usuário (SaveSignatureCommand) - usada em aprovações/auditorias com temAssinatura=true.
Inativar usuário
Inativa um usuário pelo ID: bloqueia novos logins (tokens já emitidos valem até expirar). Perfil exigido: Administrador da empresa. Use ao desligar alguém ou ao suspeitar de credencial comprometida (inclusive de usuário de integração). Operação sensível que revoga acesso. Exija confirmação humana antes de executar a partir de um agente autônomo.
Atualizar permissões do usuário
SUBSTITUI integralmente o conjunto de permissões de UM usuário na empresa do contexto: o que não vier em `itens` é removido. Fluxo seguro: GET /v1/usuarios/{id}/permissoes → ajuste a lista → PUT com a lista COMPLETA. `itens` deve conter ao menos um item com `site` nulo (linha base que habilita o login) e no máximo 10.000 itens; cada `site` deve ser unidade da empresa e cada `permissao` um perfil ativo e compatível com o tipo do usuário (GET /v1/permissoes). Perfil exigido: Administrador da empresa, ou Operacional com a operação de gestão de usuários nas unidades concedidas. Contrato alterado: o corpo antigo (`usuariosIds`, `permissaoId`, `unidadesIds`, `empresaId`) não é mais aceito — a empresa vem do token. Operação administrativa que concede e revoga acesso — siga o princípio do menor privilégio. Exija confirmação humana antes de executar a partir de um agente autônomo.
Reenviar link de definição de senha
Reenvia ao usuário o e-mail com o link para definir a senha. Use quando o e-mail da criação não chegou. Perfil exigido: Administrador da empresa. O desfecho vem no STATUS HTTP: 200 = o serviço de e-mail aceitou o envio (não garante entrega); 422 = o envio foi recusado, corrija login/e-mail do cadastro (repetir não adianta); 502 = serviço de autenticação indisponível, tente mais tarde; 504 = sem resposta a tempo — o e-mail PODE ter saído, confirme com o usuário antes de reenviar; 429 = já houve reenvio para este usuário há menos de 60 s. Cada novo link invalida o anterior, inclusive um que a pessoa já abriu — nunca reenvie em laço. Efeito externo (envia e-mail). Exija confirmação humana antes de executar a partir de um agente autônomo.
Consultar permissões do usuário
Retorna o conjunto atual de permissões do usuário na empresa do contexto (uma linha por unidade, mais a linha base com `site` nulo). Use ANTES de PUT /v1/usuarios/permissoes: como aquele endpoint substitui o conjunto inteiro, leia o estado atual, altere e reenvie tudo. Perfil exigido: Administrador da empresa, ou Operacional com a operação de gestão de usuários em todas as unidades do usuário consultado (não é possível consultar a si mesmo). Somente leitura.