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/usersEscopos necessários
| Rota | Escopo | Permissão adicional |
|---|---|---|
GET /users/ | users:read | - |
GET /users/{user_id} | users:read | - |
GET /users/{user_id}/vinculos | users:read | sim |
POST /users/ | users:write | sim |
PUT /users/{user_id} | users:write | sim |
POST /users/{user_id}/redefinir-senha | users:write | sim |
DELETE /users/{user_id} | users:write | sim |
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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID 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"eimpedimentotraz 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID 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).
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
nome | str | sim | Nome completo do usuário. |
email | EmailStr | sim | E-mail válido (validação estrita na escrita). |
login | str | sim | Login de acesso. |
grupo | str | sim | Grupo/equipe do usuário. |
telefone | str | sim | Telefone de contato. |
senha | str | não | Ausente ou em branco: o servidor gera senha provisória e envia por e-mail. Nunca é retornada em respostas. |
cargo | str | não | Cargo. |
setor | str | não | Setor. |
ativo | str | não | Situação do usuário. |
role | str | não | Papel legado. Default "user". |
perfil | PerfilUsuario | não | Perfil de acesso do usuário. Default sem privilégios adicionais. |
UserUpdate
Todos os campos são opcionais; apenas os enviados são atualizados.
| Campo | Tipo | Observações |
|---|---|---|
nome | str | Novo nome. |
email | EmailStr | Novo e-mail (validação estrita na escrita). |
senha | str | Nova senha. Nunca retornada em respostas. |
login | str | Novo login. |
grupo | str | Novo grupo. |
telefone | str | Novo telefone. |
cargo | str | Novo cargo. |
setor | str | Novo setor. |
ativo | str | Nova situação. |
role | str | Novo papel legado. |
perfil | PerfilUsuario | Novo perfil de acesso. |
UserRead
Estende UserBase acrescentando id. Não inclui senha - o campo não existe no schema de leitura.
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador do usuário. |
nome | str | Nome completo. |
email | str | E-mail. Na leitura é str (tolerante) e não EmailStr. |
login | str | Login de acesso. |
grupo | str | Grupo/equipe. |
telefone | str | Telefone de contato. |
cargo | str | null | Cargo, quando informado. |
setor | str | null | Setor, quando informado. |
ativo | str | null | Situação do usuário. |
role | str | null | Papel legado. |
perfil | PerfilUsuario | Perfil de acesso do usuário. |
imagem_perfil | str | null | Foto de perfil como data-URI base64. |
senha_provisoria | bool | A senha em uso é a provisória e ainda não foi trocada. |
senha_provisoria_expirada | bool | A 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" }, e403como{ "message": ... }. Validação (422) usa{ "detail": [...] }. - Para os dados do usuário autenticado, use
GET /auth/me. Veja Auth.