Visão Geral de Usuários
Gerenciamento dos usuários (operadores) de uma conta: criação, listagem, edição, status, assinatura digital e vínculo de roles da clínica no provedor de identidade.
Todas as rotas exigem o header Authorization: Bearer {accessToken} (JWT do provedor de identidade, WorkOS) ou x-api-key. Veja a seção Autenticação.
Toda operação é escopada pela accountId do token — um usuário só enxerga e altera usuários da própria conta. Registros excluídos da clínica (soft delete) nunca são retornados.
Base
https://api-dev.imagemais.com.br/api/users
Rotas e permissões
| Método | Rota | Permissão | Descrição |
|---|---|---|---|
GET | /users | read_users | Lista usuários ativos (paginado) |
GET | /users/me | — (só autenticado) | Dados do usuário logado |
GET | /users/me/permissions | — (só autenticado) | Permissões do usuário logado na clínica |
GET | /users/{id} | read_users | Busca um usuário por ID |
GET | /users/{id}/roles | give_roles | Slugs das roles do usuário na clínica |
GET | /users/with-consultation-permission | read_consultations | Usuários que podem atender consultas |
POST | /users | create_users | Adiciona um usuário (ou convida quem já atende em outra clínica) |
POST | /users/{id}/password-reset | update_users | Reenvia o link de senha (ou o convite) |
PATCH | /users | update_users | Atualiza um usuário |
PATCH | /users/status | update_users | Alterna ativo/inativo |
PATCH | /users/collector | update_users | Alterna a flag de coletador |
PATCH | /users/roles | give_roles | Substitui as roles do usuário |
POST | /users/{id}/signature | upload_signature | Envia a assinatura digital |
DELETE | /users/{id}/signature | upload_signature | Remove a assinatura digital |
DELETE | /users | delete_users | Deleta (soft delete) um usuário |
Rotas com @CheckPermissions exigem todas as permissões listadas (no token JWT ou na API Key); caso contrário a resposta é 403 Forbidden.
Objeto de usuário
As rotas de leitura retornam o usuário sem o campo password, incluindo as relações status, council e doctors:
{
"id": 12,
"accountId": 3,
"name": "João da Silva",
"email": "joao.silva@example.com",
"phone": "(81) 98888-7777",
"statusId": 1,
"isCollector": false,
"lastLogin": null,
"pictureId": null,
"createdAt": "2026-07-01T13:20:00.000Z",
"updatedAt": "2026-07-10T09:15:00.000Z",
"status": { "id": 1, "name": "active" },
"council": { "id": 4, "type": "CRM", "code": "12345", "uf": "PE" },
"doctors": [
{ "id": 7, "name": "Dr. João", "startTime": "08:00", "endTime": "17:00", "isActive": true }
]
}
Campos de convite: invitationPending é true enquanto a pessoa ainda não aceitou o convite para esta clínica (nesse caso nome, telefone e conselho vêm vazios); invitationExpired indica convite pendente que já passou da validade. auth0Id é um campo legado, mantido enquanto o cadastro antigo existir; workosUserId é o id da pessoa no provedor de identidade.
Pessoa em mais de uma clínica
Uma pessoa (mesmo e-mail e senha) pode atender em várias clínicas. O cadastro dela é um só, e cada clínica tem um vínculo próprio, com status, exclusão, último acesso e flag de coletador. Por isso:
- listagens, buscas e seleções mostram só quem tem vínculo ativo na clínica do token;
- bloquear, excluir, mudar roles e coletador valem só na clínica do token;
- nome, senha, telefone, conselho, assinatura e prescritor Memed pertencem à pessoa: o administrador de uma clínica não os altera quando ela tem vínculo ativo em outra (
403); - adicionar um e-mail que já existe em outra clínica envia um convite, que a pessoa aceita ou recusa.