POST Criar Usuário
Adiciona uma pessoa à clínica. A pessoa é criada no provedor de identidade (onde acontece o login) e no banco local, recebe o vínculo com a clínica e, opcionalmente, roles e dados de conselho profissional.
Envie o header Authorization: Bearer {accessToken} (token de usuário) ou x-api-key: {apiKey} (integrações). Veja Autenticação.
Exige a permissão create_users.
Sem password, a pessoa recebe por e-mail o link para definir a própria senha no primeiro acesso (reenvie em Reenviar Link de Senha). Com password, o e-mail já nasce verificado e nenhuma mensagem é enviada.
Se qualquer etapa falhar (usuário, vínculo, roles), o que já foi criado é desfeito.
Se o e-mail já pertence a uma pessoa que atende em outra clínica, a resposta é a mesma de um usuário novo (201), mas a pessoa recebe um convite por e-mail e só entra na clínica depois de aceitar. Até lá, ela aparece na listagem com invitationPending: true, não aparece nas seleções de médico, coletor ou responsável, e a password enviada é ignorada. O convite vale 7 dias. Aceitar ou recusar é feito pela própria pessoa.
E-mail de usuário ativo ou com convite pendente nesta clínica retorna 409. Usuário excluído desta clínica é reativado com o mesmo cadastro.
Endpoint
POST https://api-dev.imagemais.com.br/api/users
Corpo da Requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | ✅ | Nome completo (mínimo 5 caracteres) |
email | string | ✅ | E-mail válido (guardado em minúsculas) |
password | string | ❌ | Senha forte (mínimo 8 caracteres). Vazia ou omitida: a pessoa define a senha por e-mail. Senha fraca ou já exposta em vazamentos é recusada |
phone | string | ❌ | Telefone |
rolesIds | string[] | ❌ | Slugs das roles da clínica (ex.: org-recepcao; mínimo 1 se enviado) — veja Listar Roles |
council | object | ❌ | Conselho profissional: { type, code, uf } |
Requisição
curl -X 'POST' \n 'https://api-dev.imagemais.com.br/api/users' \n -H 'accept: application/json' \n -H 'Authorization: Bearer {accessToken}' \n -H 'Content-Type: application/json' \n -d '{
"name": "João da Silva",
"email": "joao.silva@example.com",
"phone": "(81) 98888-7777",
"rolesIds": [
"org-recepcao"
],
"council": {
"type": "CRM",
"code": "12345",
"uf": "PE"
}
}'
Respostas
201 Sucesso
Retorna o usuário criado (sem password), com status e council.
{
"id": 12,
"accountId": 3,
"name": "João da Silva",
"email": "joao.silva@example.com",
"phone": "(81) 98888-7777",
"statusId": 1,
"isCollector": false,
"createdAt": "2026-07-21T13:20:00.000Z",
"updatedAt": "2026-07-21T13:20:00.000Z",
"status": {
"id": 1,
"name": "active"
},
"council": {
"id": 4,
"type": "CRM",
"code": "12345",
"uf": "PE"
},
"invitationPending": false,
"invitationExpired": false
}
400 Validação
Algum campo não atende às regras (senha fraca, e-mail inválido, nome com menos de 5 caracteres, rolesIds vazio) ou uma role não existe na clínica:
{
"message": "Role \"org-inexistente\" não encontrada",
"error": "Bad Request",
"statusCode": 400
}
409 Já cadastrado
E-mail já em uso nesta clínica (ativo ou com convite pendente).
{
"message": "Esse email já está cadastrado",
"error": "Conflict",
"statusCode": 409
}
403 Sem permissão
{
"message": "Permissões insuficientes",
"error": "Forbidden",
"statusCode": 403
}
503 Serviço de login indisponível
{
"message": "Não foi possível falar com o serviço de login. Tente novamente em instantes.",
"error": "Service Unavailable",
"statusCode": 503
}