Skip to main content

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.

Autenticação necessária

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.

Isolamento por conta (multi-tenant)

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étodoRotaPermissãoDescrição
GET/usersread_usersLista 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_usersBusca um usuário por ID
GET/users/{id}/rolesgive_rolesSlugs das roles do usuário na clínica
GET/users/with-consultation-permissionread_consultationsUsuários que podem atender consultas
POST/userscreate_usersAdiciona um usuário (ou convida quem já atende em outra clínica)
POST/users/{id}/password-resetupdate_usersReenvia o link de senha (ou o convite)
PATCH/usersupdate_usersAtualiza um usuário
PATCH/users/statusupdate_usersAlterna ativo/inativo
PATCH/users/collectorupdate_usersAlterna a flag de coletador
PATCH/users/rolesgive_rolesSubstitui as roles do usuário
POST/users/{id}/signatureupload_signatureEnvia a assinatura digital
DELETE/users/{id}/signatureupload_signatureRemove a assinatura digital
DELETE/usersdelete_usersDeleta (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.