Campos personalizados

Los campos personalizados tienen dos mitades:

1. Definiciones — un catálogo a nivel de espacio de trabajo (GET /custom_fields) que describe cada campo: su id, name y kind.
2. Valores — incluidos en una tarea, en su arreglo custom_fields[], cuando creas (POST /tasks), actualizas (PATCH /tasks/{id}) o lees (GET /tasks/{id}) una tarea.

Lees la definición para conocer el kind de un campo y luego envías el campo de valor correspondiente en la tarea.

De dónde vienen los campos y cuáles puede tener una tarea

Los campos personalizados se definen una sola vez a nivel del espacio de trabajo y luego se vinculan a proyectos individuales a través de la configuración del proyecto en la aplicación web de Bordio. La API es de solo lectura aquí: no puedes crear un campo, editar sus opciones ni vincularlo a un proyecto a través de la API — los administradores del espacio de trabajo lo hacen en la interfaz web.

Qué significa esto cuando trabajas con tareas:

• Una tarea solo puede contener valores para campos personalizados que estén vinculados a su proyecto.
• El conjunto exacto de campos que puedes establecer en una tarea determinada es lo que devuelva GET /custom_fields?project_id=<el project_id de la tarea>. Trata esa lista como la fuente de verdad para “qué campos puedo actualizar en esta tarea”.
• Establecer un valor para un campo que no está vinculado al proyecto de la tarea se rechaza con 422.
• Una tarea sin proyecto (a nivel de espacio de trabajo) no puede tener campos personalizados en absoluto — consulta project_required más abajo.

Así que el flujo de trabajo siempre es el mismo: lee los campos del proyecto y luego establece valores solo para esos campos en las tareas de ese proyecto. Si alguien agrega o elimina un campo del proyecto en la aplicación web, ese cambio se refleja en GET /custom_fields?project_id=... la próxima vez que lo leas.

La definición

curl "https://api.bordio.com/public/v1/custom_fields?project_id=proj_6594a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer brd_sk_live_..."

{
  "data": [
    { "id": "cf_aaa", "name": "Story points", "kind": "number" },
    { "id": "cf_bbb", "name": "Budget", "kind": "currency" },
    { "id": "cf_ccc", "name": "Release", "kind": "dropdown", "allow_multiple": false,
      "options": [
        { "id": "cf_option_x1", "value": "v1.0" },
        { "id": "cf_option_x2", "value": "v2.0" }
      ] },
    { "id": "cf_ddd", "name": "Owners", "kind": "people", "allow_multiple": true }
  ]
}

• kind te indica qué campo de valor usar en una tarea (consulta la tabla).
• allow_multiple está presente solo para dropdown y people.
• options está presente solo para dropdown.
• Pasa ?project_id=proj_... para obtener los campos disponibles en ese proyecto. Sin él obtienes el catálogo completo del espacio de trabajo. Un campo debe estar disponible en el proyecto de una tarea para poder establecerlo en esa tarea.

Consejo

Los endpoints de listado de definiciones admiten almacenamiento en caché con ETag / If-None-Match — guarda el catálogo en caché y revalídalo de forma económica. Consulta Caché y solicitudes condicionales.

Cómo viven los valores en una tarea

En una tarea, cada valor es un elemento de custom_fields[]:

{ "custom_field_id": "cf_aaa", "kind": "number", "number_value": 8 }

• Al leer (GET /tasks/{id}) cada elemento incluye kind y exactamente un campo de valor poblado. Los campos sin valor se omiten por completo del arreglo.
• Al escribir (POST / PATCH) envía custom_field_id + el único campo de valor que coincide con el tipo del campo. No necesitas enviar kind — se toma de la definición (si lo envías, se ignora).

custom_fields en PATCH reemplaza todo el arreglo

PATCH /tasks/{id} con un arreglo custom_fields reemplaza todos los valores de campos personalizados de la tarea. Cualquier campo que no incluyas se borra. Esto no es una fusión por campo.

• Omitir custom_fields por completo → todos los valores de los campos personalizados quedan sin cambios.
• Enviar custom_fields: [...] → ese arreglo se convierte en el conjunto completo de valores de la tarea; cualquier elemento faltante se elimina.

Así que para cambiar un campo manteniendo los demás, envía el conjunto completo con el que quieres que termine la tarea.

Los valores de campos personalizados requieren que la tarea pertenezca a un proyecto. Establecerlos en una tarea a nivel de espacio de trabajo (sin project_id) falla con 422 validation_error (project_required).

Formato de valor por tipo

kind	Campo de valor	Formato
text	text_value	cadena (≤ 10000 caracteres)
number	number_value	número
percent	percent_value	número, donde 75 significa 75%
currency	currency_value	objeto { "currency": <ISO-4217>, "value": <number> }
date	date_value	fecha y hora ISO-8601, o YYYY-MM-DD para solo fecha
checkbox	checkbox_value	booleano
email	email_value	cadena (≤ 320)
phone	phone_value	cadena (≤ 40)
url	url_value	cadena (≤ 2048)
dropdown	dropdown_value	arreglo de ids de opción (cf_option_...)
people	people_value	arreglo de ids de usuario (user_...)

Las secciones siguientes muestran la carga útil de escritura y la forma de lectura para cada tipo.

text, email, phone, url

Cadenas simples. Difieren únicamente en su longitud máxima e intención (email/phone/url no son validados por formato por la API — almacena lo que envíes).

// escritura
{ "custom_field_id": "cf_txt", "text_value": "Needs design review" }
{ "custom_field_id": "cf_eml", "email_value": "ops@acme.com" }

// lectura
{ "custom_field_id": "cf_txt", "kind": "text", "text_value": "Needs design review" }

number

Cualquier número (entero o decimal). Sin unidad.

// escritura
{ "custom_field_id": "cf_pts", "number_value": 8 }

// lectura
{ "custom_field_id": "cf_pts", "kind": "number", "number_value": 8 }

percent

Un valor percent es un número simple que representa el porcentaje en sí — 75 significa 75%, no 0.75. Se permiten decimales (33.5 → 33.5%).

// escritura — establecer el progreso al 75%
{ "custom_field_id": "cf_prog", "percent_value": 75 }

// lectura
{ "custom_field_id": "cf_prog", "kind": "percent", "percent_value": 75 }

Consejo

No envíes 0.75 esperando 75% — eso almacena 0.75%. Envía el número de porcentaje legible para humanos.

currency

Un valor currency es un objeto, no un número:

{ "currency": "<ISO-4217 code>", "value": <number> }

• currency — un código ISO-4217 como USD, EUR, GBP (obligatorio).
• value — el importe numérico (opcional; omítelo para registrar una moneda sin importe).

// escritura — establecer el presupuesto en 1990.50 USD
{
  "custom_field_id": "cf_budget",
  "currency_value": { "currency": "USD", "value": 1990.5 }
}

// lectura
{
  "custom_field_id": "cf_budget",
  "kind": "currency",
  "currency_value": { "currency": "USD", "value": 1990.5 }
}

date

Fecha y hora ISO-8601, o YYYY-MM-DD para una fecha sin hora. Al leer, un valor de solo fecha vuelve como YYYY-MM-DD; una fecha y hora vuelve como una marca de tiempo ISO-8601 completa.

// escritura — solo fecha
{ "custom_field_id": "cf_due", "date_value": "2026-07-01" }
// escritura — fecha y hora
{ "custom_field_id": "cf_due", "date_value": "2026-07-01T09:00:00.000Z" }

// lectura
{ "custom_field_id": "cf_due", "kind": "date", "date_value": "2026-07-01" }

checkbox

Un booleano.

// escritura
{ "custom_field_id": "cf_billable", "checkbox_value": true }

// lectura
{ "custom_field_id": "cf_billable", "kind": "checkbox", "checkbox_value": true }

dropdown

Un arreglo de ids de opción (cf_option_...) tomados de las options del campo en su definición. Envía un arreglo de un solo elemento a menos que la definición tenga allow_multiple: true.

// escritura — selección única
{ "custom_field_id": "cf_release", "dropdown_value": ["cf_option_x1"] }
// escritura — selección múltiple (solo si allow_multiple)
{ "custom_field_id": "cf_release", "dropdown_value": ["cf_option_x1", "cf_option_x2"] }

// lectura
{ "custom_field_id": "cf_release", "kind": "dropdown", "dropdown_value": ["cf_option_x1"] }

Cada id de opción debe pertenecer a ese campo, de lo contrario la solicitud falla con 422 validation_error (custom_field_invalid_option).

people

Un arreglo de ids de usuario (user_...). Cada uno debe ser un miembro del espacio de trabajo. De un solo elemento a menos que la definición tenga allow_multiple: true.

// escritura
{ "custom_field_id": "cf_owners", "people_value": ["user_abc", "user_def"] }

// lectura
{ "custom_field_id": "cf_owners", "kind": "people", "people_value": ["user_abc", "user_def"] }

Ejemplo práctico: establecer varios campos en una tarea

curl -X PATCH https://api.bordio.com/public/v1/tasks/task_6a2918cff58b0a1d387866ee \
  -H "Authorization: Bearer brd_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": [
      { "custom_field_id": "cf_prog",   "percent_value": 75 },
      { "custom_field_id": "cf_budget", "currency_value": { "currency": "USD", "value": 1990.5 } },
      { "custom_field_id": "cf_release","dropdown_value": ["cf_option_x1"] }
    ]
  }'

Al leer la tarea de vuelta:

// GET /tasks/task_6a2918cff58b0a1d387866ee
{
  "data": {
    "id": "task_6a2918cff58b0a1d387866ee",
    "title": "Ship the API",
    "custom_fields": [
      { "custom_field_id": "cf_prog",    "kind": "percent",  "percent_value": 75 },
      { "custom_field_id": "cf_budget",  "kind": "currency", "currency_value": { "currency": "USD", "value": 1990.5 } },
      { "custom_field_id": "cf_release", "kind": "dropdown", "dropdown_value": ["cf_option_x1"] }
    ]
  }
}

Borrar valores

Como custom_fields se reemplaza al escribir, deja un campo fuera del arreglo para borrarlo — pero recuerda que debes incluir todos los demás campos que quieras conservar.

// la tarea tiene actualmente cf_prog, cf_budget, cf_release.
// Este PATCH conserva cf_prog y cf_budget, y borra cf_release:
{
  "custom_fields": [
    { "custom_field_id": "cf_prog",   "percent_value": 75 },
    { "custom_field_id": "cf_budget", "currency_value": { "currency": "USD", "value": 1990.5 } }
  ]
}

Para borrar todos los campos personalizados, envía "custom_fields": [].

Errores de validación

Situación	HTTP	código
Campos personalizados establecidos en una tarea sin proyecto	422	project_required
Id de opción de dropdown no definido en ese campo	422	custom_field_invalid_option
Campo no disponible en el proyecto de la tarea	422	validation_error
Valor de people que referencia a un no-miembro	422	validation_error

Todos llevan el sobre de error estándar — consulta Errores.