Establecer Valores de Campos Personalizados

Actualizar los valores de campos personalizados en registros utilizando parámetros específicos para cada tipo de campo

Establecer Valores de Campos Personalizados

Los campos personalizados amplían la estructura estándar de registros de Blue con datos específicos del negocio. Este endpoint te permite establecer o actualizar valores para cualquier campo personalizado en un registro. Cada tipo de campo requiere parámetros específicos para garantizar la integridad de los datos y la validación adecuada.

Ejemplo Básico

mutation SetTextFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_xyz789"
    text: "Project specification document"
  })
}

Ejemplo Avanzado

mutation SetMultipleFieldTypes {
  # Set a date range field
  dateField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_date_001"
    startDate: "2024-01-15T09:00:00Z"
    endDate: "2024-01-31T17:00:00Z"
    timezone: "America/New_York"
  })
  
  # Set a multi-select field
  selectField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_select_002"
    customFieldOptionIds: ["option_high", "option_urgent", "option_client"]
  })
  
  # Set a location field
  locationField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_location_003"
    latitude: 40.7128
    longitude: -74.0060
  })
}

Parámetros de Entrada

SetTodoCustomFieldInput

Parámetro	Tipo	Requerido	Descripción
`todoId`	String!	✅ Sí	El ID del registro a actualizar
`customFieldId`	String!	✅ Sí	El ID del campo personalizado
`text`	String	No	Para TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL
`number`	Float	No	Para NUMBER, PERCENT, RATING
`currency`	String	No	Código de moneda para el tipo CURRENCY (por ejemplo, "USD")
`checked`	Boolean	No	Para campos CHECKBOX
`startDate`	DateTime	No	Fecha de inicio para campos DATE
`endDate`	DateTime	No	Fecha de finalización para campos de rango DATE
`timezone`	String	No	Zona horaria para campos DATE (por ejemplo, "America/New_York")
`latitude`	Float	No	Latitud para campos LOCATION
`longitude`	Float	No	Longitud para campos LOCATION
`regionCode`	String	No	Código de región para campos PHONE
`countryCodes`	[String!]	No	Códigos de país ISO para campos COUNTRY
`customFieldOptionId`	String	No	ID de opción para campos SELECT_SINGLE
`customFieldOptionIds`	[String!]	No	IDs de opción para campos SELECT_MULTI
`customFieldReferenceTodoIds`	[String!]	No	IDs de registros para campos REFERENCE

Ejemplos de Tipos de Campo

Campos de Texto

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_description"
    text: "Detailed project requirements and specifications"
  })
}

Campos Numéricos

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_budget"
    number: 15000.50
  })
}

Campos de Selección

# Single Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_priority"
    customFieldOptionId: "option_high"
  })
}

# Multi Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_tags"
    customFieldOptionIds: ["option_frontend", "option_urgent", "option_v2"]
  })
}

Campos de Fecha

# Single Date
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_deadline"
    startDate: "2024-12-31T23:59:59Z"
  })
}

# Date Range
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_project_timeline"
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-03-31T23:59:59Z"
    timezone: "UTC"
  })
}

Campos de Ubicación

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_office_location"
    latitude: 37.7749
    longitude: -122.4194
  })
}

Campos de Moneda

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_invoice_amount"
    number: 5000
    currency: "USD"
  })
}

Campos de Archivo

Los campos de archivo utilizan mutaciones separadas:

# Add a file
mutation {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

# Remove a file
mutation {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

Estableciendo Valores Durante la Creación de Registros

Puedes establecer valores de campos personalizados al crear un nuevo registro:

mutation {
  createTodo(input: {
    todoListId: "list_project_123"
    title: "New Feature Development"
    customFields: [
      {
        customFieldId: "field_priority"
        value: "high"
      },
      {
        customFieldId: "field_estimate"
        value: "8"
      }
    ]
  }) {
    id
    customFields {
      customField {
        name
      }
      value
    }
  }
}

Campos de Respuesta

La mutación devuelve un booleano que indica el éxito:

Campo	Tipo	Descripción
`setTodoCustomField`	Boolean!	Verdadero si la operación tuvo éxito

Permisos Requeridos

Los usuarios deben tener permiso para editar tanto el registro como el campo personalizado específico:

Rol	Puede Establecer Valores de Campo
`OWNER`	✅ Sí
`ADMIN`	✅ Sí
`MEMBER`	✅ Sí (a menos que esté restringido por un rol personalizado)
`CLIENT`	✅ Sí (a menos que esté restringido por un rol personalizado)

Para los usuarios con roles personalizados de proyecto, el sistema realiza una verificación de dos niveles:

Primero, verifica que el usuario tenga acceso a nivel de proyecto
Luego, verifica si el campo específico está marcado como editable en su configuración de rol personalizado

Esto significa que un usuario puede tener acceso general al proyecto, pero aún estar restringido para editar ciertos campos según su rol personalizado.

Respuestas de Error

Campo Personalizado No Encontrado

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Acceso No Autorizado

{
  "errors": [{
    "message": "You are not authorized.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Valor de Campo Inválido

{
  "errors": [{
    "message": "Invalid value for field type NUMBER",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Notas Importantes

Comportamiento de Upsert: La mutación crea un nuevo valor de campo si no existe, o actualiza el valor existente
Seguridad de Tipo: Solo proporciona parámetros que coincidan con el tipo de campo (por ejemplo, no envíes text para un campo NUMBER)
Efectos Secundarios: Establecer valores desencadena:
- Recalculaciones de campos de fórmula
- Reglas de automatización
- Notificaciones de webhook
- Entradas de registro de actividad
- Actualizaciones de gráficos
Comportamientos Especiales:
- Los campos CURRENCY manejan automáticamente los cálculos de conversión
- Los campos REFERENCE actualizan relaciones bidireccionales
- Los campos FORMULA son de solo lectura y no se pueden establecer directamente (se calculan automáticamente)
- Los campos LOOKUP son de solo lectura y no se pueden establecer directamente (extraen datos de registros referenciados)
- Los campos BUTTON desencadenan eventos de automatización cuando se "hacen clic"
Validación: La API valida que:
- El registro existe en el proyecto
- El campo personalizado existe en el mismo proyecto
- El usuario tiene permisos de edición
- El valor coincide con los requisitos del tipo de campo

Referencia de Formato de Valor

Tipo de Campo	Parámetro	Formato	Ejemplo
`TEXT_SINGLE`	`text`	String	`"Project Alpha"`
`TEXT_MULTI`	`text`	String with newlines	`"Line 1\nLine 2"`
`NUMBER`	`number`	Float	`42.5`
`CURRENCY`	`number` + `currency`	Float + ISO code	`1000.00` + `"USD"`
`PERCENT`	`number`	Float (0-100)	`75`
`RATING`	`number`	Float (within min/max)	`4.5`
`CHECKBOX`	`checked`	Boolean	`true`
`DATE`	`startDate`	ISO 8601 DateTime	`"2024-01-15T00:00:00Z"`
`DATE` (range)	`startDate` + `endDate`	ISO 8601 DateTimes	See example above
`SELECT_SINGLE`	`customFieldOptionId`	Option ID	`"option_123"`
`SELECT_MULTI`	`customFieldOptionIds`	Array of Option IDs	`["opt_1", "opt_2"]`
`PHONE`	`text`	String	`"+1-555-123-4567"`
`EMAIL`	`text`	String	`"user@example.com"`
`URL`	`text`	String	`"https://example.com"`
`LOCATION`	`latitude` + `longitude`	Floats	`40.7128, -74.0060`
`COUNTRY`	`countryCodes`	ISO 3166 codes	`["US", "CA"]`
`REFERENCE`	`customFieldReferenceTodoIds`	Array of record IDs	`["todo_1", "todo_2"]`
`FORMULA`	N/A	Read-only - calculated automatically	N/A
`LOOKUP`	N/A	Read-only - pulls from references	N/A

Endpoints Relacionados

Listar Campos Personalizados - Obtener campos personalizados disponibles
Crear Campo Personalizado - Agregar nuevos campos personalizados
Obtener Detalles del Registro - Recuperar registros con valores de campos personalizados
Actualizar Registros en Masa - Actualizar múltiples registros a la vez