Definir Valores de Campos Personalizados

Atualizar valores de campos personalizados em registros usando parâmetros específicos para cada tipo de campo

Definir Valores de Campos Personalizados

Campos personalizados estendem a estrutura padrão de registros do Blue com dados específicos do negócio. Este endpoint permite que você defina ou atualize valores para qualquer campo personalizado em um registro. Cada tipo de campo requer parâmetros específicos para garantir a integridade dos dados e a validação adequada.

Exemplo Básico

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

Exemplo Avançado

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	Obrigatório	Descrição
`todoId`	String!	✅ Sim	O ID do registro a ser atualizado
`customFieldId`	String!	✅ Sim	O ID do campo personalizado
`text`	String	Não	Para TEXT_SINGLE, TEXT_MULTI, PHONE, EMAIL, URL
`number`	Float	Não	Para NUMBER, PERCENT, RATING
`currency`	String	Não	Código da moeda para o tipo CURRENCY (ex: "USD")
`checked`	Boolean	Não	Para campos CHECKBOX
`startDate`	DateTime	Não	Data de início para campos DATE
`endDate`	DateTime	Não	Data de término para campos de intervalo DATE
`timezone`	String	Não	Fuso horário para campos DATE (ex: "America/New_York")
`latitude`	Float	Não	Latitude para campos LOCATION
`longitude`	Float	Não	Longitude para campos LOCATION
`regionCode`	String	Não	Código da região para campos PHONE
`countryCodes`	[String!]	Não	Códigos de países ISO para campos COUNTRY
`customFieldOptionId`	String	Não	ID da opção para campos SELECT_SINGLE
`customFieldOptionIds`	[String!]	Não	IDs das opções para campos SELECT_MULTI
`customFieldReferenceTodoIds`	[String!]	Não	IDs dos registros para campos REFERENCE

Exemplos 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 Seleção

# 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 Data

# 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 Localização

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

Campos de Moeda

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

Campos de Arquivo

Campos de arquivo usam mutações 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"
  })
}

Definindo Valores Durante a Criação de Registros

Você pode definir valores de campos personalizados ao criar um novo 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 Resposta

A mutação retorna um booleano indicando sucesso:

Campo	Tipo	Descrição
`setTodoCustomField`	Boolean!	Verdadeiro se a operação foi bem-sucedida

Permissões Necessárias

Os usuários devem ter permissão para editar tanto o registro quanto o campo personalizado específico:

Papel	Pode Definir Valores de Campo
`OWNER`	✅ Sim
`ADMIN`	✅ Sim
`MEMBER`	✅ Sim (a menos que restrito por papel personalizado)
`CLIENT`	✅ Sim (a menos que restrito por papel personalizado)

Para usuários com papéis de projeto personalizados, o sistema realiza uma verificação em dois níveis:

Primeiro, verifica se o usuário tem acesso ao nível do projeto
Em seguida, verifica se o campo específico está marcado como editable na configuração do papel personalizado deles

Isso significa que um usuário pode ter acesso geral ao projeto, mas ainda estar restrito de editar certos campos com base em seu papel personalizado.

Respostas de Erro

Campo Personalizado Não Encontrado

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

Acesso Não 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

Comportamento Upsert: A mutação cria um novo valor de campo se nenhum existir, ou atualiza o valor existente
Segurança de Tipo: Forneça apenas parâmetros que correspondam ao tipo de campo (ex: não envie text para um campo NUMBER)
Efeitos Colaterais: Definir valores aciona:
- Recalculos de campos de fórmula
- Regras de automação
- Notificações de webhook
- Entradas de log de atividade
- Atualizações de gráfico
Comportamentos Especiais:
- Campos CURRENCY lidam automaticamente com cálculos de conversão
- Campos REFERENCE atualizam relacionamentos bidirecionais
- Campos FORMULA são somente leitura e não podem ser definidos diretamente (são calculados automaticamente)
- Campos LOOKUP são somente leitura e não podem ser definidos diretamente (eles puxam dados de registros referenciados)
- Campos BUTTON acionam eventos de automação quando "clicados"
Validação: A API valida que:
- O registro existe no projeto
- O campo personalizado existe no mesmo projeto
- O usuário tem permissões de edição
- O valor corresponde aos requisitos do tipo de campo

Referência de Formato de Valor

Tipo de Campo	Parâmetro	Formato	Exemplo
`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 - Obter campos personalizados disponíveis
Criar Campo Personalizado - Adicionar novos campos personalizados
Obter Detalhes do Registro - Recuperar registros com valores de campos personalizados
Atualizar Registros em Massa - Atualizar múltiplos registros ao mesmo tempo