Membros de unidade — API

Lista os usuários com algum papel efetivo numa unidade — combinando quem recebeu o papel diretamente naquela unidade com quem o recebeu de forma tenant-wide (e por isso também atua ali) — junto com o(s) papel(éis) de cada um. É a rota pensada para telas de "gerenciar equipe da unidade".

Funcionamento

A rota tem dois modos de leitura, escolhidos pela presença de filtro:

• Sem filtro (search e source ausentes): lê a página diretamente por uma consulta paginada no banco (findEffectiveUnitMemberAssignmentsPage) — mais barata para a listagem padrão.
• Com filtro (search e/ou source informados): carrega todos os candidatos efetivos da unidade, filtra em memória por nome/e-mail/nome do papel e/ou pela origem do vínculo (unit/tenant), e só então pagina o resultado filtrado.

Em ambos os modos, o perfil de cada membro vem do diretório de usuários (FindIdentityUserDirectoryService), que decide se o e-mail e outros campos sensíveis aparecem conforme a permissão do ator — não do membro listado.

include_sensitive: true só tem efeito se o ator possuir user:read-sensitive no tenant da unidade; caso contrário a busca por e-mail sensível não é usada (a rota não erra, apenas não aplica esse campo na busca).

Endpoints

Método	Rota	Descrição
GET	/v1/units/:unitId/members	Lista membros efetivos de uma unidade, com seus papéis

Versão: v1

Swagger: listIdentityUnitMembers · Rota (Dev): http://localhost:3000/v1/units/{unitId}/members

Permissões

Rota	Guards	Permissão exigida (escopo unit)
GET /units/:unitId/members	IdentityOAuthAccessTokenGuard, AuthorizationGuard	role:read e user:read (match: all)

Headers

Header	Obrigatório	Descrição
Authorization	Sim	Bearer <access_token>

Path parameters

Nome	Tipo	Obrigatório	Descrição
unitId	uuid	Sim	Unidade cujos membros estão sendo listados

Query parameters

Nome	Tipo	Obrigatório	Default	Descrição
include_sensitive	boolean	Não	false	Inclui e-mail e outros campos sensíveis do perfil, se o ator tiver user:read-sensitive
source	unit | tenant	Não	—	Restringe aos vínculos originados diretamente na unidade, ou aos tenant-wide
search	string	Não	—	Busca por nome exibido, e-mail normalizado, ou nome/nome de exibição do papel (até 160 caracteres)
limit	integer	Não	20	Itens por página (1–100)
page	integer	Não	1	Página (mínimo 1)

Body

Nenhum (rota GET).

Response

200 — IdentityUnitMemberPageResponse:

json
{
  "data": {
    "items": [
      {
        "user": { "id": "77aa...uuid", "display_name": "Dra. Ana Souza", "email": null },
        "assignments": [
          {
            "id": "3c9e...uuid",
            "role_id": "0198f1a2-...",
            "role_name": "doctor",
            "role_display_name": "Doctor",
            "role_type": "system",
            "unit_id": "9b3c...uuid",
            "is_effective": true
          }
        ]
      }
    ],
    "limit": 20,
    "page": 1,
    "total": 8
  }
}

Mapa de campos

Campo	Tipo	Descrição
user.email	string | null	null se o ator não tem user:read-sensitive, mesmo com include_sensitive: true
assignments[].unit_id	uuid | null	null se a atribuição listada é tenant-wide, ainda que apareça como membro efetivo desta unidade
assignments[].role_type	string	system ou tenant_custom

Erros

Classe de erro	errorCode	Status	Quando ocorre
(validação de query/UUID)	BAD_REQUEST / IDENTITY_UNIT_MEMBER_FILTER_INVALID / INVALID_UUID	400	unitId inválido, paginação fora dos limites, filtro malformado
UnauthenticatedError	—	401	access token ausente/inválido/expirado
ForbiddenAction (guard)	—	403	ator sem role:read+user:read na unidade, ou unidade inativa/inexistente

Regras de negócio

ID	Regra	Comportamento esperado
RN-01	Membro efetivo inclui quem recebeu o papel na unidade e quem o recebeu no tenant inteiro	ambos aparecem na mesma listagem; source filtra entre os dois
RN-02	Campo sensível do perfil depende da permissão do ator, não da presença do parâmetro	include_sensitive: true sem user:read-sensitive não expõe o e-mail
RN-03	Busca textual alcança nome do usuário, e-mail normalizado e nome do papel	um termo que bate só com o nome do papel também retorna o membro

Compliance

Órgão / norma	Exigência	Como a rota atende
LGPD	Minimização de dado pessoal	e-mail só aparece para quem tem user:read-sensitive, independentemente do parâmetro pedido pelo client

Variáveis de ambiente

Nenhuma variável de ambiente é consumida diretamente por esta rota.

Tempo médio de resposta

A confirmar — responsável: time de Identity; data: 24/09/2026. Sem medição publicada.

Requisitos não funcionais

Requisito	Definição
Idempotência	Sim (leitura pura)
Paginação	Sim (1–100, default 20)
Rate limit	Não identificado
Cache	Não identificado
Auditoria	Não — rota de leitura, sem evento de auditoria

Relacionado

• 📂 Módulo: Authorization
• 🔁 Ver também: Atribuição de papéis (conceder/revogar os vínculos listados aqui)