---

Listar Usuários

Blue fornece várias consultas para listar usuários em diferentes escopos - em toda a empresa, específicos de projeto ou busca de usuário individual. Essas consultas suportam paginação, filtragem e ordenação para gerenciar eficientemente grandes bases de usuários.

Exemplo Básico - Usuários da Empresa

Liste todos os usuários em uma empresa:

query ListCompanyUsers {
  companyUserList(companyId: "acme-corp") {
    users {
      id
      email
      fullName
      jobTitle
      lastActiveAt
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Exemplo Avançado - Usuários de Projeto Filtrados

Liste usuários de projeto com pesquisa e paginação:

query ListProjectUsers {
  projectUserList(
    projectId: "web-redesign"
    search: "engineer"
    first: 20
    orderBy: lastActiveAt_DESC
  ) {
    edges {
      node {
        id
        email
        fullName
        accessLevel
        customRole {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Consultas Disponíveis

companyUserList

Lista todos os usuários em uma empresa com filtragem opcional.

Parâmetros de Entrada

Parâmetro	Tipo	Necessário	Descrição
companyId	String!	✅ Sim	ID ou slug da empresa
notInProjectId	String	Não	Excluir usuários já neste projeto
search	String	Não	Pesquisar por nome ou email
first	Int	Não	Número de resultados a retornar (paginações para frente)
after	String	Não	Cursor para paginação para frente
last	Int	Não	Número de resultados a retornar (paginações para trás)
before	String	Não	Cursor para paginação para trás
skip	Int	Não	Número de resultados a pular
orderBy	UserOrderByInput	Não	Ordem de classificação (veja abaixo)

projectUserList

Lista todos os usuários em um projeto específico.

Parâmetros de Entrada

Parâmetro	Tipo	Necessário	Descrição
projectId	String!	✅ Sim	ID ou slug do projeto
search	String	Não	Pesquisar por nome ou email
first	Int	Não	Número de resultados (máx: 200)
after	String	Não	Cursor para paginação
orderBy	UserOrderByInput	Não	Ordem de classificação

user

Recupera um único usuário pelo ID.

Parâmetros de Entrada

Parâmetro	Tipo	Necessário	Descrição
id	String!	✅ Sim	ID do usuário

Opções de Ordenação

UserOrderByInput Valores

Valor	Descrição
createdAt_ASC	Ordenar por data de registro (mais antigo primeiro)
createdAt_DESC	Ordenar por data de registro (mais recente primeiro)
lastActiveAt_ASC	Ordenar por última atividade (mais antiga primeiro)
lastActiveAt_DESC	Ordenar por última atividade (mais recente primeiro)
firstName_ASC	Ordenar por primeiro nome (A-Z)
firstName_DESC	Ordenar por primeiro nome (Z-A)
lastName_ASC	Ordenar por sobrenome (A-Z)
lastName_DESC	Ordenar por sobrenome (Z-A)
email_ASC	Ordenar por endereço de email (A-Z)
email_DESC	Ordenar por endereço de email (Z-A)
username_ASC	Ordenar por nome de usuário (A-Z)
username_DESC	Ordenar por nome de usuário (Z-A)
jobTitle_ASC	Ordenar por cargo (A-Z)
jobTitle_DESC	Ordenar por cargo (Z-A)

Campos de Resposta

Objeto Usuário

Campo	Tipo	Descrição
id	String!	Identificador único do usuário
uid	String!	UID de autenticação do Firebase
username	String!	Nome de usuário escolhido pelo usuário
email	String!	Endereço de email (visível apenas para PROPRIETÁRIO/ADMIN)
firstName	String	Primeiro nome
lastName	String	Sobrenome
fullName	String	Nome completo (primeiro e último nome combinados)
jobTitle	String	Título profissional
phoneNumber	String	Número de contato
dateOfBirth	DateTime	Data de nascimento
isEmailVerified	Boolean!	Status de verificação de email
lastActiveAt	DateTime	Timestamp da última atividade
createdAt	DateTime!	Data de criação da conta
updatedAt	DateTime!	Última atualização do perfil
isOnline	Boolean!	Status online atual
timezone	String	Fuso horário do usuário
locale	String	Preferência de idioma
theme	JSON	Preferências de tema da interface do usuário
image	Image	Objeto da foto de perfil

Campos Adicionais do Usuário do Projeto

Ao listar usuários de projeto, campos adicionais estão disponíveis:

Campo	Tipo	Descrição
accessLevel	UserAccessLevel!	Papel do usuário no projeto
customRole	ProjectUserRole	Detalhes do papel personalizado, se aplicável
joinedAt	DateTime!	Quando o usuário entrou no projeto

Informações de Paginação

Campo	Tipo	Descrição
totalItems	Int!	Número total de usuários
totalPages	Int	Total de páginas (para paginação de offset)
page	Int	Número da página atual
perPage	Int	Itens por página
hasNextPage	Boolean!	Mais resultados disponíveis
hasPreviousPage	Boolean!	Resultados anteriores disponíveis
startCursor	String	Cursor do primeiro item
endCursor	String	Cursor do último item

Permissões Necessárias

Consulta	Permissão Necessária
companyUserList	Any authenticated user in the company
projectUserList	Any project member (including VIEW_ONLY)
user	Any authenticated user

Respostas de Erro

Empresa Não Encontrada

{
  "errors": [{
    "message": "Company not found",
    "extensions": {
      "code": "COMPANY_NOT_FOUND"
    }
  }]
}

Projeto Não Encontrado

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Acesso Não Autorizado

{
  "errors": [{
    "message": "You don't have access to this resource",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

Notas Importantes

• Desempenho: Use paginação para grandes listas de usuários (máx. 200 usuários por solicitação)
• Pesquisa: Pesquisas em campos de primeiro nome, sobrenome e email
• Privacidade de Email: Endereços de email são visíveis apenas para usuários com níveis de acesso de PROPRIETÁRIO ou ADMIN
• Status Online: isOnline atualiza em tempo real via conexões WebSocket
• Imagens de Perfil: Use o campo image.variants para tamanhos diferentes
• Filtragem: O parâmetro notInProjectId é útil ao construir interfaces de seleção de usuários
• Níveis de Acesso: Listas de usuários de projeto incluem informações de papel não disponíveis nas listas da empresa

Operações Relacionadas

• Visão Geral da Gestão de Usuários - Operações de gestão de usuários
• Remover Usuário - Remover usuários de projetos
• Papéis Personalizados - Gerenciar permissões de usuários