API de Campos Personalizados

Referencia completa de la API para gestionar campos personalizados en Blue - crea, configura y utiliza campos personalizados para extender tu estructura de datos

Descripción General

Los campos personalizados te permiten extender la estructura de registro estándar de Blue con campos de datos adicionales específicos para las necesidades de tu negocio. Proporcionan una forma poderosa de capturar datos estructurados más allá de los campos incorporados como título, descripción y fecha de vencimiento.

Los campos personalizados se definen a nivel de proyecto y pueden ser utilizados en todos los registros (tareas) dentro de ese proyecto. Cada campo tiene un tipo específico que determina sus reglas de validación, formato de entrada y comportamiento de visualización.

Operaciones Disponibles

Gestión de Campos Básicos

Operación	Descripción	Enlace
List Custom Fields	Consultar y filtrar campos personalizados	View Details →
Create Custom Field	Agregar nuevos campos personalizados a proyectos	View Details →
Delete Custom Field	Eliminar campos personalizados con limpieza adecuada	View Details →

Valores de Campos

Operación	Descripción	Enlace
Set Field Values	Establecer y actualizar valores de campos personalizados en registros	View Details →

Tipos de Campos Personalizados

Campos de Texto

Tipo	Descripción	Casos de Uso	Enlace
TEXT_SINGLE	Entrada de texto de una sola línea	Names, titles, short descriptions	View Details →
TEXT_MULTI	Área de texto de múltiples líneas	Descripciones largas, notas, comentarios	View Details →

Campos de Selección

Tipo	Descripción	Casos de Uso	Enlace
SELECT_SINGLE	Desplegable de selección única	Status, priority, category	View Details →
SELECT_MULTI	Desplegable de selección múltiple	Tags, skills, categories	View Details →
CHECKBOX	Campo de casilla de verificación booleana	Flags, approvals, confirmations	View Details →

Campos Numéricos

Tipo	Descripción	Casos de Uso	Enlace
NUMBER	Entrada numérica	Quantities, scores, measurements	View Details →
CURRENCY	Monto en moneda	Budgets, costs, pricing	View Details →
PERCENT	Valor porcentual	Completion rates, discounts	View Details →
RATING	Calificación por estrellas con escala personalizada	Performance ratings, satisfaction	View Details →
FORMULA	Campo calculado basado en otros campos	Totals, computations, aggregations	View Details →

Campos de Contacto

Tipo	Descripción	Casos de Uso	Enlace
EMAIL	Dirección de correo electrónico con validación	Información de contacto, notificaciones	View Details →
PHONE	Número de teléfono con formato internacional	Contact details, emergency contacts	View Details →
URL	URL web con validación	Links, references, resources	View Details →

Campos de Fecha y Hora

Tipo	Descripción	Casos de Uso	Enlace
DATE	Selector de fecha	Deadlines, milestones, events	View Details →
TIME_DURATION	Campo de seguimiento de tiempo	Work hours, duration estimates	View Details →

Ubicación y Geografía

Tipo	Descripción	Casos de Uso	Enlace
LOCATION	Ubicación geográfica (lat/lng)	Addresses, venues, service areas	View Details →
COUNTRY	Selector de país	Regional assignments, localization	View Details →

Archivos y Medios

Tipo	Descripción	Casos de Uso	Enlace
FILE	Adjunto de archivo	Documents, images, resources	View Details →

Campos del Sistema

Tipo	Descripción	Casos de Uso	Enlace
UNIQUE_ID	Identificador único autogenerado	Ticket numbers, order IDs	View Details →
REFERENCE	Enlace a registros en otro proyecto	Cross-project relationships	View Details →
LOOKUP	Extraer datos de registros referenciados	Aggregate data from related records	View Details →

Campos Interactivos

Tipo	Descripción	Casos de Uso	Enlace
BUTTON	Campo de botón accionable	Triggers, actions, workflows	View Details →
CURRENCY_CONVERSION	Campo de conversión de moneda	Multi-currency calculations	View Details →

Conceptos Clave

Definición de Campo

Los campos personalizados se definen a nivel de proyecto
Cada campo tiene un nombre y tipo únicos
Los campos pueden incluir reglas de validación y restricciones
Las opciones de configuración varían según el tipo de campo

Valores de Campo

Los valores se almacenan en registros individuales (tareas)
Cada registro puede tener diferentes valores para el mismo campo
Se permiten valores vacíos/nulos para campos opcionales
Los valores se validan de acuerdo con las reglas del tipo de campo

Modelo de Permisos

Los campos personalizados respetan los permisos a nivel de proyecto:

Rol	Crear Campos	Editar Campos*	Establecer Valores	Ver Valores
OWNER	✅ Sí	✅ Sí	✅ Sí	✅ Sí
ADMIN	✅ Sí	✅ Sí	✅ Sí	✅ Sí
MEMBER	❌ No	❌ No	✅ Sí	✅ Sí
CLIENT	❌ No	❌ No	✅ Limitado	✅ Limitado

*Editar Campos se refiere a modificar la configuración del campo (nombre, tipo, opciones, reglas de validación) - no a establecer valores de campo en registros

Permisos de Rol Personalizado

Los proyectos pueden tener roles personalizados con permisos específicos para los campos
Los campos pueden ser marcados como editables/no editables por rol
Los roles personalizados pueden restringir el acceso a campos específicos

Patrones Comunes

Creando un Campo Personalizado Básico

mutation CreateCustomField {
  createCustomField(input: {
    name: "Priority Level"
    type: SELECT_SINGLE
    description: "Task priority level"
    customFieldOptions: [
      { title: "Low", color: "#28a745" }
      { title: "Medium", color: "#ffc107" }
      { title: "High", color: "#fd7e14" }
      { title: "Critical", color: "#dc3545" }
    ]
  }) {
    id
    name
    type
    customFieldOptions {
      id
      title
      color
    }
  }
}

Estableciendo Valores de Campo en Registros

mutation SetFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionId: "option_789"  # For SELECT_SINGLE
  })
}

Consultando Registros con Campos Personalizados

query GetTodosWithCustomFields {
  todos(projectId: "project_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      # Type-specific value fields
      text           # TEXT_SINGLE, TEXT_MULTI, EMAIL, etc.
      number         # NUMBER, CURRENCY, PERCENT, RATING
      selectedOption # SELECT_SINGLE
      selectedOptions # SELECT_MULTI
      checked        # CHECKBOX
      date           # DATE
    }
  }
}

Creando Registros con Valores de Campo Personalizados

mutation CreateTodoWithCustomFields {
  createTodo(input: {
    title: "New task"
    todoListId: "list_123"
    customFields: [
      { customFieldId: "priority_field", value: "high_priority_option" }
      { customFieldId: "budget_field", value: "5000" }
      { customFieldId: "notes_field", value: "Additional context here" }
    ]
  }) {
    id
    title
    customFields {
      customField { name }
      value
    }
  }
}

Mejores Prácticas

Diseño de Campos

Usar nombres descriptivos - Hacer claros los propósitos de los campos
Elegir tipos apropiados - Hacer coincidir el tipo de campo con los requisitos de datos
Establecer reglas de validación - Usar valores mínimos/máximos, campos requeridos
Organizar lógicamente - Agrupar campos relacionados juntos

Consideraciones de Rendimiento

Limitar el número de campos - Demasiados campos pueden afectar el rendimiento
Usar paginación - Al consultar grandes conjuntos de datos
Indexar campos clave - Para campos utilizados en filtrado/ordenamiento
Evitar anidamientos profundos - Mantener las relaciones de campo simples

Calidad de Datos

Validar entradas - Usar tipos de campo apropiados con validación
Proporcionar valores predeterminados - Establecer valores predeterminados sensatos donde sea apropiado
Usar formatos consistentes - Estandarizar patrones de entrada de datos
Limpieza regular - Eliminar campos y opciones no utilizados

Experiencia del Usuario

Descripciones claras - Proporcionar descripciones útiles de los campos
Orden lógico - Posicionar campos en el orden natural del flujo de trabajo
Jerarquía visual - Usar colores y formato de manera efectiva
Divulgación progresiva - Mostrar campos cuando sean relevantes

Manejo de Errores

Errores comunes al trabajar con campos personalizados:

Código de Error	Descripción	Solución
`CUSTOM_FIELD_NOT_FOUND`	El campo no existe	Verify field ID and project access
`VALIDATION_ERROR`	El valor no coincide con el tipo de campo	Check format and validation rules
`UNAUTHORIZED`	Permisos insuficientes	Ensure proper role level
`CUSTOM_FIELD_VALUE_PARSE_ERROR`	Formato de valor inválido	Review field type requirements

Recursos Relacionados

API de Registros - Trabajando con registros que contienen campos personalizados
API de Proyectos - Gestionando proyectos que contienen campos personalizados
API de Automatizaciones - Automatizando flujos de trabajo con disparadores de campos personalizados
API de Gestión de Usuarios - Gestionando permisos de campos personalizados