Listar todos os Campos Personalizados

Recuperar uma lista paginada de campos personalizados para um projeto ou em vários projetos com opções de filtragem e ordenação

Listar todos os Campos Personalizados

Os campos personalizados permitem que você amplie a estrutura padrão de registros do Blue com campos de dados adicionais específicos para as necessidades do seu negócio. Este endpoint recupera campos personalizados disponíveis em seus projetos, com filtragem por tipo de campo e suporte à paginação.

Exemplo Básico

query ListCustomFields {
  customFields(
    filter: { projectId: "project_123" }
    sort: position_ASC
    take: 20
  ) {
    items {
      id
      uid
      name
      type
      position
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Exemplo Avançado

query ListCustomFieldsAdvanced {
  customFields(
    filter: {
      projectId: "project_123"
      types: [TEXT_SINGLE, NUMBER, SELECT_SINGLE]
    }
    sort: name_ASC
    skip: 20
    take: 50
  ) {
    items {
      id
      uid
      name
      type
      position
      description
      
      # Type-specific fields
      min              # For NUMBER, RATING, PERCENT
      max              # For NUMBER, RATING, PERCENT
      currency         # For CURRENCY type
      prefix           # For UNIQUE_ID type
      isDueDate        # For DATE type
      formula          # For FORMULA type
      
      # Validation settings
      editable
      metadata
      
      # For SELECT types
      customFieldOptions {
        id
        title
        color
        position
      }
    }
    pageInfo {
      totalItems
      hasNextPage
      hasPreviousPage
    }
  }
}

Parâmetros de Entrada

CustomFieldFilterInput

Parâmetro	Tipo	Obrigatório	Descrição
`projectId`	String	Não	Filtrar por ID de projeto específico
`types`	[CustomFieldType!]	Não	Filtrar por tipos de campos personalizados

Valores de CustomFieldSort

Valor	Descrição
`name_ASC`	Ordenar por nome ascendente (A-Z)
`name_DESC`	Ordenar por nome descendente (Z-A)
`createdAt_ASC`	Ordenar por data de criação (mais antigo primeiro)
`createdAt_DESC`	Ordenar por data de criação (mais recente primeiro)
`position_ASC`	Ordenar por posição (padrão)
`position_DESC`	Ordenar por posição descendente

Valores de CustomFieldType

Valor	Descrição
`TEXT_SINGLE`	Entrada de texto de linha única
`TEXT_MULTI`	Área de texto de múltiplas linhas
`SELECT_SINGLE`	Dropdown de seleção única
`SELECT_MULTI`	Dropdown de seleção múltipla
`CHECKBOX`	Campo de checkbox booleano
`RATING`	Avaliação por estrelas (1-5 ou intervalo personalizado)
`PHONE`	Número de telefone com validação
`NUMBER`	Entrada numérica
`CURRENCY`	Montante em moeda
`PERCENT`	Valor percentual
`EMAIL`	Endereço de e-mail com validação
`URL`	URL da web com validação
`UNIQUE_ID`	Identificador único gerado automaticamente
`LOCATION`	Localização geográfica (lat/lng)
`FILE`	Anexo de arquivo
`DATE`	Seletor de data
`COUNTRY`	Seletor de país
`FORMULA`	Campo calculado com base em outros campos
`REFERENCE`	Link para registros em outro projeto
`LOOKUP`	Extrair dados de registros referenciados
`TIME_DURATION`	Campo de rastreamento de tempo
`BUTTON`	Campo de botão acionável
`CURRENCY_CONVERSION`	Campo de conversão de moeda

Parâmetros de Paginação

Parâmetro	Tipo	Obrigatório	Descrição
`skip`	Int	Não	Número de itens a serem pulados (padrão: 0)
`take`	Int	Não	Número de itens a serem retornados (padrão: 20, máximo: 500)

Campos de Resposta

CustomField

Campo	Tipo	Descrição
`id`	String!	Identificador único
`uid`	String!	ID amigável único
`name`	String!	Nome de exibição do campo
`type`	CustomFieldType!	Tipo do campo personalizado
`position`	Float!	Posição da ordem de classificação
`description`	String	Descrição opcional do campo
`min`	Float	Valor mínimo (NÚMERO, AVALIAÇÃO, PORCENTAGEM)
`max`	Float	Valor máximo (NÚMERO, AVALIAÇÃO, PORCENTAGEM)
`currency`	String	Código da moeda (tipo MOEDA)
`prefix`	String	Prefixo para geração de UNIQUE_ID
`isDueDate`	Boolean	Se o campo DATA representa uma data de vencimento
`formula`	JSON	Configuração da fórmula (tipo FÓRMULA)
`editable`	Boolean	Se o usuário atual pode editar este campo
`metadata`	JSON	Configuração adicional do campo
`customFieldOptions`	[CustomFieldOption!]	Opções disponíveis para tipos SELECT

CustomFieldOption

Campo	Tipo	Descrição
`id`	String!	Identificador único
`title`	String!	Texto de exibição para a opção
`color`	String!	Código de cor hexadecimal
`position`	Float!	Posição da ordem de classificação

PageInfo

Campo	Tipo	Descrição
`totalItems`	Int	Número total de campos personalizados
`hasNextPage`	Boolean!	Se mais páginas existem
`hasPreviousPage`	Boolean!	Se páginas anteriores existem
`endCursor`	String	Cursor para paginação (obsoleto - use paginação baseada em offset)

Permissões Necessárias

Os campos personalizados são acessíveis com base na sua função de projeto. Se você tiver uma função personalizada com acesso restrito a campos, apenas os campos marcados como editáveis para sua função serão retornados.

Função	Pode Listar Campos Personalizados
`OWNER`	✅ Sim (todos os campos)
`ADMIN`	✅ Sim (todos os campos)
`MEMBER`	✅ Sim (com base nas permissões de função)
`CLIENT`	✅ Sim (com base nas permissões de função)

Respostas de Erro

Projeto Não Encontrado

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

Tipo de Campo Inválido

{
  "errors": [{
    "message": "Variable \"$filter\" got invalid value \"INVALID_TYPE\" at \"filter.types[0]\"; Value \"INVALID_TYPE\" does not exist in \"CustomFieldType\" enum.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

Notas Importantes

Os campos personalizados são limitados a projetos - você deve especificar um projectId no filtro
O parâmetro take é limitado a 500 itens por solicitação para desempenho
Os campos são retornados com base nas permissões do usuário - funções personalizadas podem ter acesso restrito
A ordem de classificação padrão é por position ascendente, que reflete a ordem mostrada na interface do usuário
Esta consulta suporta filtragem de projeto único - para consultas de múltiplos projetos, use a interface aninhada CustomFieldQueries
Alguns tipos de campo (como FÓRMULA e REFERÊNCIA) podem incluir estruturas de dados aninhadas adicionais
O campo editable indica se o usuário atual pode modificar valores para este campo personalizado

Endpoints Relacionados

Criar um Campo Personalizado - Adicionar novos campos personalizados a um projeto
Atualizar um Campo Personalizado - Modificar propriedades de campos personalizados existentes
Excluir um Campo Personalizado - Remover um campo personalizado de um projeto
Definir Valor de Campo Personalizado - Definir valores em registros