Descrição

Retorna uma lista paginada de usuários filtrados por nome (primeiro ou sobrenome) ou e-mail. É necessário informar ao menos 2 caracteres no parâmetro de busca. Opcionalmente, permite filtrar por role_name para retornar apenas usuários com um papel específico (ex: role_name=Practitioner para Practitioners). Os resultados são retornados paginados com controle de página e limite. Retorna 12 registros por página por padrão. Os dados são filtrados automaticamente baseado no role do usuário autenticado.

Cabeçalhos

Parâmetros de Consulta

Sucesso - 200

{
    "success": true,
    "message": "Users retrieved successfully.",
    "page": 1,
    "limit": 12,
    "total": 45,
    "data": [{
        "user_id": 1,
        "first_name": "Jhon",
        "last_name": "Doe",
        "email": "jhon@email.com",
        "avatarUrl": "https://cdn.meuapp.com/avatar/joana.png",
        "created_at": "2025-04-23 09:45:00",
        "role": {
            "role_id": "3",
            "role_name": "Individual"
        },
        "practitioner_name": "Jane Smith",
        "available_assessments": 5
    }]
}

Erro - 401 (Token inválido)

{
    "status": 401,
    "error": "Invalid or expired token."
}

Erro - 403 (Sem permissão)

{
    "status": 403,
    "error": "You are not allowed to search users."
}

Erro - 422 (Nome inválido)

{
    "status": 422,
    "error": "Please provide at least 2 characters to search."
}

Erro - 404 (Nenhum usuário encontrado)

{
    "status": 404,
    "error": "No users found with the provided name."
}

Códigos de Resposta

• 200 - Usuários encontrados com sucesso
• 401 - Token inválido ou expirado
• 403 - Sem permissão para buscar usuários
• 422 - Parâmetro "name" inválido ou ausente
• 404 - Nenhum usuário encontrado

Controle de Acesso por Role

• Individual: Bloqueado (não pode buscar outros usuários)
• Practitioner/Master Practitioner/Institutional: Busca apenas seus próprios dados e usuários vinculados (parent_id)
• Admin/Super Admin: Busca todos os usuários do sistema

Observações

• É necessário estar autenticado para acessar este endpoint.
• O parâmetro name é obrigatório e deve ter no mínimo 2 caracteres.
• A busca é realizada nos campos: first_name, last_name e email.
• Os dados são filtrados automaticamente baseado no role do usuário autenticado.
• Usuários do tipo Individual não têm permissão para acessar este endpoint.
• A paginação padrão retorna 12 registros por página.
• O campo available_assessments mostra a quantidade de avaliações pendentes do usuário.
• Os filtros name e role_name podem ser combinados com a paginação.
• Os resultados são ordenados por data de criação (mais recentes primeiro).