Users

Endpoints administrativos da WebApiAlcance para a gestão de usuários - os operadores da Alcance Contabilidade. Cobrem listagem geral, detalhamento por ID, criação, atualização, redefinição de senha, prévia de remoção e exclusão. Para os dados do usuário autenticado, use GET /auth/me (ver Auth).

Acesso restrito

Este domínio é administrativo: lida com credenciais e acessos de usuários. Além do escopo, as operações de gestão exigem permissão adicional; sem ela, a resposta é 403. Não conceda estes escopos a credenciais de integração.

Todos os endpoints exigem autenticação. Veja Autenticação.

Base path

/api/v1/users

Escopos necessários

RotaEscopoPermissão adicional
GET /users/users:read-
GET /users/{user_id}users:read-
GET /users/{user_id}/vinculosusers:readsim
POST /users/users:writesim
PUT /users/{user_id}users:writesim
POST /users/{user_id}/redefinir-senhausers:writesim
DELETE /users/{user_id}users:writesim

O escopo é derivado da rota: o prefixo /users vira o recurso users, e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Escopo não é suficiente

Ter users:write não basta para as rotas marcadas na tabela. Sem a permissão adicional, a resposta é 403 Forbidden. O mesmo vale para GET /users/{user_id}/vinculos, apesar de ser leitura.

Endpoints

POST /users/

Cria um novo usuário no sistema. Sem senha, o servidor gera uma senha provisória e a envia por e-mail ao usuário (ver Auth).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (UserCreate): nome, email, login, grupo e telefone (obrigatórios), além de senha, cargo, setor, ativo, role e perfil (opcionais).

Request

{
  "nome": "Usuário Exemplo",
  "email": "usuario.exemplo@exemplo.com.br",
  "login": "usuario.exemplo",
  "grupo": "Operações",
  "telefone": "71988887777",
  "cargo": "Assistente",
  "setor": "Contábil"
}

Sem senha, o servidor gera uma senha provisória e a envia por e-mail ao usuário, que deve trocá-la no primeiro acesso. Com senha, o valor informado é gravado e nenhum e-mail é enviado.

Response 201 Created

{
  "status": "success",
  "message": "Usuário criado com sucesso",
  "data": {
    "id": 42,
    "nome": "Usuário Exemplo",
    "email": "usuario.exemplo@exemplo.com.br",
    "login": "usuario.exemplo",
    "grupo": "Operações",
    "telefone": "71988887777",
    "cargo": "Assistente",
    "setor": "Contábil",
    "ativo": "1",
    "role": "user",
    "perfil": "<perfil>",
    "senha_provisoria": null,
    "email_enviado": true,
    "email_erro": null
  }
}

email_enviado e email_erro descrevem o envio da senha provisória (vêm null quando senha foi informada). senha_provisoria só vem preenchida, em texto, uma única vez, quando o e-mail falhou, para o operador repassar por canal seguro; nos demais casos é null. Regras de negócio violadas (ex.: e-mail já em uso por conta ativa) retornam o envelope de erro (status: "error"). Atribuir perfis com mais privilégios exige permissão adicional (403 sem ela). A resposta não é armazenável em cache.

Escopo: users:write

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

GET /users/

Lista todos os usuários cadastrados no sistema. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhum usuário encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lista de usuários recuperada com sucesso",
  "data": [
    { "id": 1, "nome": "Usuário Exemplo", "login": "usuario.exemplo", "perfil": "<perfil>" },
    { "id": 7, "nome": "Maria Souza", "login": "maria.souza", "perfil": "<perfil>" }
  ]
}

Escopo: users:read

GET /users/{user_id}

Detalha um usuário pelo ID inteiro. O data é um UserRead.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
user_idintpathsimID interno do usuário

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Usuário encontrado com sucesso",
  "data": {
    "id": 7,
    "nome": "Maria Souza",
    "email": "maria.souza@exemplo.com.br",
    "login": "maria.souza",
    "grupo": "Operações",
    "telefone": "71999998888",
    "cargo": "Analista Contábil",
    "setor": "Fiscal",
    "ativo": "1",
    "role": "user",
    "perfil": "<perfil>",
    "senha_provisoria": false,
    "senha_provisoria_expirada": false
  }
}

senha_provisoria indica que a senha em uso foi definida pelo servidor e ainda não foi trocada; senha_provisoria_expirada indica que passou do prazo de 7 dias (o login fica bloqueado até nova redefinição). Os dois campos também vêm em GET /users/. Quando não encontrado, retorna o envelope de erro com message: "Usuário não encontrado.".

Escopo: users:read

PUT /users/{user_id}

Atualiza um usuário existente. O body é um UserUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
user_idintpathsimID do usuário

Request (UserUpdate - todos os campos opcionais, incluindo senha, role e perfil)

{
  "cargo": "Analista Sênior",
  "setor": "Fiscal",
  "ativo": "1"
}

Response 200 OK

{
  "status": "success",
  "message": "Usuário atualizado com sucesso",
  "data": {
    "id": 7,
    "nome": "Maria Souza",
    "email": "maria.souza@exemplo.com.br",
    "login": "maria.souza",
    "grupo": "Operações",
    "telefone": "71999998888",
    "cargo": "Analista Sênior",
    "setor": "Fiscal",
    "ativo": "1",
    "role": "user",
    "perfil": "<perfil>"
  }
}

Alterar dados sensíveis de certas contas (como senha, email, login, ativo, perfil ou role) ou atribuir perfis com mais privilégios exige permissão adicional; sem ela, a resposta é 403. Campos que não mudam de valor (ex.: formulário que reenvia o e-mail atual) não contam.

Escopo: users:write

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

POST /users/{user_id}/redefinir-senha

Gera uma senha provisória para o usuário user_id, envia-a por e-mail ao endereço cadastrado e encerra todas as sessões dele. Até o titular trocar a senha, as rotas de dados ficam fechadas para ele (ver Senha provisória).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
user_idintpathsimID do usuário que terá a senha redefinida

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Senha redefinida. A senha provisória foi enviada por e-mail.",
  "data": {
    "email_enviado": true,
    "email_erro": null,
    "senha_provisoria": null,
    "email": "maria.souza@exemplo.com.br"
  }
}

Se o envio do e-mail falhar, a senha já terá sido trocada mesmo assim: email_enviado vem false, email_erro traz o motivo e senha_provisoria traz a senha em texto, para o operador repassá-la por um canal seguro - é exibida uma única vez. Com o e-mail entregue, senha_provisoria é sempre null. A resposta não é armazenável em cache.

Erros (corpo { "message": ... }):

  • 403 Forbidden - sem permissão para redefinir a senha do usuário indicado.
  • 404 Not Found - usuário não encontrado.
  • 400 Bad Request - conta inativa, ou usuário sem e-mail cadastrado.

Escopo: users:write

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

GET /users/{user_id}/vinculos

Informa quantos registros dependem do usuário e o que DELETE /users/{user_id} fará com ele - é a prévia da remoção. A acao e o pode_remover seguem a mesma regra do DELETE, então a prévia não diverge do que de fato acontece.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
user_idintpathsimID do usuário

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Vínculos recuperados com sucesso",
  "data": {
    "user_id": 7,
    "nome": "Maria Souza",
    "autoria": [
      { "tabela": "registros_exemplo", "coluna": "campo_exemplo", "rotulo": "Atividades", "total": 152 }
    ],
    "posse": [],
    "estado": [],
    "pode_remover": true,
    "acao": "anonimizado",
    "impedimento": null
  }
}

Os vínculos vêm em três grupos, porque a consequência da remoção é diferente para cada um:

  • autoria - preservado; segue apontando para a conta anonimizada.
  • posse - só some se for exclusão real (usuário sem nenhum vínculo).
  • estado - impede a remoção até ser reatribuído. Com itens aqui, pode_remover é false, acao é "bloqueado" e impedimento traz a mensagem com o que reatribuir.

acao vale "excluido" (sem nenhum vínculo), "anonimizado" (com vínculos, sem bloqueio) ou "bloqueado". rotulo é texto de interface e pode mudar. Quando o usuário não existe, retorna o envelope de erro com message: "Usuário não encontrado.".

Escopo: users:read

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

DELETE /users/{user_id}

Remove um usuário do sistema. Operação sensível e destrutiva. Quem decide o caminho é o servidor: sem nenhum vínculo, o usuário é excluído; com vínculos, é anonimizado (os dados pessoais são apagados e o histórico de autoria é preservado); com vínculos de estado, a remoção é rejeitada. Consulte GET /users/{user_id}/vinculos antes para saber o que vai acontecer.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
user_idintpathsimID do usuário

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Usuário excluído com sucesso",
  "data": {
    "acao": "excluido"
  }
}

Com vínculos, acao vem "anonimizado" e a mensagem é "Usuário anonimizado: os dados pessoais foram removidos e o histórico preservado". Usuário inexistente ou remoção bloqueada por vínculos de estado retornam o envelope de erro (status: "error").

Escopo: users:write

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

Schemas

UserCreate

Estende UserBase acrescentando senha (opcional).

CampoTipoObrigatórioObservações
nomestrsimNome completo do usuário.
emailEmailStrsimE-mail válido (validação estrita na escrita).
loginstrsimLogin de acesso.
grupostrsimGrupo/equipe do usuário.
telefonestrsimTelefone de contato.
senhastrnãoAusente ou em branco: o servidor gera senha provisória e envia por e-mail. Nunca é retornada em respostas.
cargostrnãoCargo.
setorstrnãoSetor.
ativostrnãoSituação do usuário.
rolestrnãoPapel legado. Default "user".
perfilPerfilUsuarionãoPerfil de acesso do usuário. Default sem privilégios adicionais.

UserUpdate

Todos os campos são opcionais; apenas os enviados são atualizados.

CampoTipoObservações
nomestrNovo nome.
emailEmailStrNovo e-mail (validação estrita na escrita).
senhastrNova senha. Nunca retornada em respostas.
loginstrNovo login.
grupostrNovo grupo.
telefonestrNovo telefone.
cargostrNovo cargo.
setorstrNovo setor.
ativostrNova situação.
rolestrNovo papel legado.
perfilPerfilUsuarioNovo perfil de acesso.

UserRead

Estende UserBase acrescentando id. Não inclui senha - o campo não existe no schema de leitura.

CampoTipoNotas
idintIdentificador do usuário.
nomestrNome completo.
emailstrE-mail. Na leitura é str (tolerante) e não EmailStr.
loginstrLogin de acesso.
grupostrGrupo/equipe.
telefonestrTelefone de contato.
cargostr | nullCargo, quando informado.
setorstr | nullSetor, quando informado.
ativostr | nullSituação do usuário.
rolestr | nullPapel legado.
perfilPerfilUsuarioPerfil de acesso do usuário.
imagem_perfilstr | nullFoto de perfil como data-URI base64.
senha_provisoriaboolA senha em uso é a provisória e ainda não foi trocada.
senha_provisoria_expiradaboolA provisória passou de 7 dias sem troca.

Notas

Senha nunca é retornada

senha existe apenas nos schemas de escrita (UserCreate, UserUpdate). O schema de leitura UserRead não possui o campo. Uma senha só é devolvida em texto no caso da senha provisória de POST /users/ e POST /users/{user_id}/redefinir-senha quando o envio por e-mail falha (exibição única).

Validação de e-mail assimétrica

Na escrita o email é EmailStr (validação estrita). Na leitura UserRead.email é apenas str, para que registros antigos não derrubem a listagem inteira.

role vs. perfil

perfil é o perfil de acesso do usuário. role é um campo legado; seu default é "user".

  • Toda resposta de sucesso segue o envelope { "status": "success", "message", "data" }. Erros de regra de negócio vêm como { "status": "error", "message", "details" }, e 403 como { "message": ... }. Validação (422) usa { "detail": [...] }.
  • Para os dados do usuário autenticado, use GET /auth/me. Veja Auth.