Campos personalizados

Os campos personalizados têm duas partes:

1. Definições — um catálogo no nível do espaço de trabalho (GET /custom_fields) que descreve cada campo: seu id, name e kind.
2. Valores — presentes em uma tarefa, no seu array custom_fields[], quando você cria (POST /tasks), atualiza (PATCH /tasks/{id}) ou lê (GET /tasks/{id}) uma tarefa.

Você lê a definição para descobrir o kind de um campo e, em seguida, envia o campo de valor correspondente na tarefa.

De onde vêm os campos e quais uma tarefa pode ter

Os campos personalizados são definidos uma única vez no nível do espaço de trabalho e depois vinculados a projetos individuais por meio das configurações de projeto no aplicativo web do Bordio. A API é somente leitura aqui: você não pode criar um campo, editar suas opções ou vinculá-lo a um projeto pela API — os administradores do espaço de trabalho fazem isso na interface web.

O que isso significa quando você trabalha com tarefas:

• Uma tarefa só pode conter valores para campos personalizados que estejam vinculados ao seu projeto.
• O conjunto exato de campos que você pode definir em uma determinada tarefa é o que GET /custom_fields?project_id=<o project_id da tarefa> retorna. Trate essa lista como a fonte da verdade para “quais campos posso atualizar nesta tarefa”.
• Definir um valor para um campo que não está vinculado ao projeto da tarefa é rejeitado com 422.
• Uma tarefa sem projeto (nível do espaço de trabalho) não pode ter campos personalizados de forma alguma — veja project_required abaixo.

Portanto, o fluxo de trabalho é sempre o mesmo: leia os campos do projeto e, em seguida, defina valores apenas para esses campos nas tarefas desse projeto. Se alguém adicionar ou remover um campo do projeto no aplicativo web, essa alteração será refletida em GET /custom_fields?project_id=... na próxima vez que você fizer a leitura.

A definição

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 informa qual campo de valor usar em uma tarefa (veja a tabela).
• allow_multiple está presente apenas para dropdown e people.
• options está presente apenas para dropdown.
• Passe ?project_id=proj_... para obter os campos disponíveis nesse projeto. Sem isso, você obtém o catálogo completo do espaço de trabalho. Um campo deve estar disponível no projeto de uma tarefa para ser definido nessa tarefa.

Dica

Os endpoints de listagem de definições suportam cache via ETag / If-None-Match — armazene o catálogo em cache e revalide de forma econômica. Veja Cache e requisições condicionais.

Como os valores existem em uma tarefa

Em uma tarefa, cada valor é um item em custom_fields[]:

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

• Na leitura (GET /tasks/{id}) cada item carrega kind e exatamente um campo de valor preenchido. Campos sem valor são omitidos do array por completo.
• Na escrita (POST / PATCH) envie custom_field_id + o único campo de valor que corresponde ao kind do campo. Você não precisa enviar kind — ele é obtido da definição (se você enviá-lo, será ignorado).

custom_fields no PATCH substitui todo o array

PATCH /tasks/{id} com um array custom_fields substitui todos os valores de campos personalizados da tarefa. Qualquer campo que você não incluir será limpo. Isto não é um merge por campo.

• Omitir custom_fields por completo → todos os valores de campos personalizados permanecem inalterados.
• Enviar custom_fields: [...] → esse array passa a ser o conjunto completo de valores da tarefa; tudo o que estiver ausente é removido.

Portanto, para alterar um campo mantendo os outros, envie o conjunto completo que você quer que a tarefa tenha ao final.

Os valores de campos personalizados exigem que a tarefa pertença a um projeto. Defini-los em uma tarefa de nível do espaço de trabalho (sem project_id) falha com 422 validation_error (project_required).

Formato de valor por kind

kind	Campo de valor	Formato
text	text_value	string (≤ 10000 caracteres)
number	number_value	número
percent	percent_value	número, onde 75 significa 75%
currency	currency_value	objeto { "currency": <ISO-4217>, "value": <número> }
date	date_value	data e hora ISO-8601, ou YYYY-MM-DD para apenas data
checkbox	checkbox_value	booleano
email	email_value	string (≤ 320)
phone	phone_value	string (≤ 40)
url	url_value	string (≤ 2048)
dropdown	dropdown_value	array de ids de opção (cf_option_...)
people	people_value	array de ids de usuário (user_...)

As seções abaixo mostram o payload de escrita e o formato de leitura para cada kind.

text, email, phone, url

Strings simples. Diferem apenas no seu comprimento máximo e na sua finalidade (email/phone/url não têm o formato validado pela API — armazena o que você enviar).

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

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

number

Qualquer número (inteiro ou decimal). Sem unidade.

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

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

percent

Um valor percent é um número simples que representa a própria porcentagem — 75 significa 75%, não 0.75. Decimais são permitidos (33.5 → 33,5%).

// escrita — define o progresso em 75%
{ "custom_field_id": "cf_prog", "percent_value": 75 }

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

Dica

Não envie 0.75 esperando 75% — isso armazena 0,75%. Envie o número da porcentagem legível por humanos.

currency

Um valor currency é um objeto, não um número:

{ "currency": "<código ISO-4217>", "value": <número> }

• currency — um código ISO-4217 como USD, EUR, GBP (obrigatório).
• value — o valor numérico (opcional; omita-o para registrar uma moeda sem um valor).

// escrita — define o orçamento em 1990,50 USD
{
  "custom_field_id": "cf_budget",
  "currency_value": { "currency": "USD", "value": 1990.5 }
}

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

date

Data e hora ISO-8601, ou YYYY-MM-DD para uma data sem hora. Na leitura, um valor apenas de data retorna como YYYY-MM-DD; uma data e hora retorna como um timestamp ISO-8601 completo.

// escrita — apenas data
{ "custom_field_id": "cf_due", "date_value": "2026-07-01" }
// escrita — data e hora
{ "custom_field_id": "cf_due", "date_value": "2026-07-01T09:00:00.000Z" }

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

checkbox

Um booleano.

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

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

dropdown

Um array de ids de opção (cf_option_...) extraídos das options do campo em sua definição. Envie um array de um único elemento, a menos que a definição tenha allow_multiple: true.

// escrita — seleção única
{ "custom_field_id": "cf_release", "dropdown_value": ["cf_option_x1"] }
// escrita — seleção múltipla (apenas se allow_multiple)
{ "custom_field_id": "cf_release", "dropdown_value": ["cf_option_x1", "cf_option_x2"] }

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

Cada id de opção deve pertencer a esse campo, caso contrário a requisição falha com 422 validation_error (custom_field_invalid_option).

people

Um array de ids de usuário (user_...). Cada um deve ser um membro do espaço de trabalho. Um único elemento, a menos que a definição tenha allow_multiple: true.

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

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

Exemplo prático: definir vários campos em uma tarefa

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"] }
    ]
  }'

Lendo a tarefa de volta:

// 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"] }
    ]
  }
}

Limpar valores

Como custom_fields é substituído na escrita, deixe um campo de fora do array para limpá-lo — mas lembre-se de que você deve incluir todos os outros campos que deseja manter.

// a tarefa atualmente tem cf_prog, cf_budget, cf_release.
// Este PATCH mantém cf_prog e cf_budget, e limpa 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 limpar todos os campos personalizados, envie "custom_fields": [].

Erros de validação

Situação	HTTP	code
Campos personalizados definidos em uma tarefa sem projeto	422	project_required
Id de opção de dropdown não definido nesse campo	422	custom_field_invalid_option
Campo não disponível no projeto da tarefa	422	validation_error
Valor people referenciando um não membro	422	validation_error

Todos carregam o envelope de erro padrão — veja Erros.