Listar todos los Campos Personalizados

Recuperar una lista paginada de campos personalizados para un proyecto o en múltiples proyectos con opciones de filtrado y ordenamiento

Listar todos los Campos Personalizados

Los campos personalizados te permiten extender la estructura estándar de registros de Blue con campos de datos adicionales específicos para las necesidades de tu negocio. Este endpoint recupera los campos personalizados disponibles en tus proyectos, con filtrado por tipo de campo y soporte de paginación.

Ejemplo Básico

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

Ejemplo Avanzado

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	Requerido	Descripción
`projectId`	String	No	Filtrar por ID de proyecto específico
`types`	[CustomFieldType!]	No	Filtrar por tipos de campos personalizados

Valores de CustomFieldSort

Valor	Descripción
`name_ASC`	Ordenar por nombre ascendente (A-Z)
`name_DESC`	Ordenar por nombre descendente (Z-A)
`createdAt_ASC`	Ordenar por fecha de creación (más antiguo primero)
`createdAt_DESC`	Ordenar por fecha de creación (más reciente primero)
`position_ASC`	Ordenar por posición (predeterminado)
`position_DESC`	Ordenar por posición descendente

Valores de CustomFieldType

Valor	Descripción
`TEXT_SINGLE`	Entrada de texto de una sola línea
`TEXT_MULTI`	Área de texto de varias líneas
`SELECT_SINGLE`	Desplegable de selección única
`SELECT_MULTI`	Desplegable de selección múltiple
`CHECKBOX`	Campo de casilla de verificación booleano
`RATING`	Calificación por estrellas (1-5 o rango personalizado)
`PHONE`	Número de teléfono con validación
`NUMBER`	Entrada numérica
`CURRENCY`	Monto en moneda
`PERCENT`	Valor porcentual
`EMAIL`	Dirección de correo electrónico con validación
`URL`	URL web con validación
`UNIQUE_ID`	Identificador único autogenerado
`LOCATION`	Ubicación geográfica (lat/lng)
`FILE`	Adjuntar archivo
`DATE`	Selector de fecha
`COUNTRY`	Selector de país
`FORMULA`	Campo calculado basado en otros campos
`REFERENCE`	Enlace a registros en otro proyecto
`LOOKUP`	Extraer datos de registros referenciados
`TIME_DURATION`	Campo de seguimiento de tiempo
`BUTTON`	Campo de botón accionable
`CURRENCY_CONVERSION`	Campo de conversión de moneda

Parámetros de Paginación

Parámetro	Tipo	Requerido	Descripción
`skip`	Int	No	Número de elementos a omitir (predeterminado: 0)
`take`	Int	No	Número de elementos a devolver (predeterminado: 20, máximo: 500)

Campos de Respuesta

CustomField

Campo	Tipo	Descripción
`id`	String!	Identificador único
`uid`	String!	ID amigable único
`name`	String!	Nombre de visualización del campo
`type`	CustomFieldType!	Tipo del campo personalizado
`position`	Float!	Posición de orden de clasificación
`description`	String	Descripción opcional del campo
`min`	Float	Valor mínimo (NÚMERO, CALIFICACIÓN, PORCENTAJE)
`max`	Float	Valor máximo (NÚMERO, CALIFICACIÓN, PORCENTAJE)
`currency`	String	Código de moneda (tipo MONEDA)
`prefix`	String	Prefijo para la generación de UNIQUE_ID
`isDueDate`	Boolean	Si el campo de FECHA representa una fecha de vencimiento
`formula`	JSON	Configuración de fórmula (tipo FÓRMULA)
`editable`	Boolean	Si el usuario actual puede editar este campo
`metadata`	JSON	Configuración adicional del campo
`customFieldOptions`	[CustomFieldOption!]	Opciones disponibles para tipos SELECT

CustomFieldOption

Campo	Tipo	Descripción
`id`	String!	Identificador único
`title`	String!	Texto de visualización para la opción
`color`	String!	Código de color hexadecimal
`position`	Float!	Posición de orden de clasificación

PageInfo

Campo	Tipo	Descripción
`totalItems`	Int	Número total de campos personalizados
`hasNextPage`	Boolean!	Si existen más páginas
`hasPreviousPage`	Boolean!	Si existen páginas anteriores
`endCursor`	String	Cursor para paginación (obsoleto - usar paginación basada en desplazamiento)

Permisos Requeridos

Los campos personalizados son accesibles según tu rol en el proyecto. Si tienes un rol personalizado con acceso restringido a campos, solo se devolverán los campos marcados como editables para tu rol.

Rol	Puede Listar Campos Personalizados
`OWNER`	✅ Sí (todos los campos)
`ADMIN`	✅ Sí (todos los campos)
`MEMBER`	✅ Sí (según permisos de rol)
`CLIENT`	✅ Sí (según permisos de rol)

Respuestas de Error

Proyecto No 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

Los campos personalizados están limitados a proyectos: debes especificar un projectId en el filtro
El parámetro take está limitado a 500 elementos por solicitud por razones de rendimiento
Los campos se devuelven según los permisos del usuario: los roles personalizados pueden tener acceso restringido
El orden de clasificación predeterminado es por position ascendente, que refleja el orden mostrado en la interfaz de usuario
Esta consulta admite filtrado de un solo proyecto: para consultas de múltiples proyectos, utiliza la interfaz anidada CustomFieldQueries
Algunos tipos de campos (como FÓRMULA y REFERENCIA) pueden incluir estructuras de datos anidadas adicionales
El campo editable indica si el usuario actual puede modificar los valores de este campo personalizado

Endpoints Relacionados

Crear un Campo Personalizado - Agregar nuevos campos personalizados a un proyecto
Actualizar un Campo Personalizado - Modificar las propiedades de un campo personalizado existente
Eliminar un Campo Personalizado - Eliminar un campo personalizado de un proyecto
Establecer Valor de Campo Personalizado - Establecer valores en registros