Поля задачи

GET /v1/tasks/fields

Возвращает схему полей задачи: типы, флаги «только чтение», признак nullable, понятные человеку label и description, перечисления значений для status, priority, mark и durationType, а для полей, которые портал отдаёт динамически, — словарь допустимых значений values и значение по умолчанию default.

Имена полей здесь те же, что в ответах списка и карточки, а типы соответствуют приходящим значениям: объявленное number приходит числом, boolean — значениями true/false.

Примеры

curl — личный ключ

curl "https://vibecode.bitrix24.tech/v1/tasks/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

curl "https://vibecode.bitrix24.tech/v1/tasks/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)
console.log('Значения status:', data.fields.status.enum)

JavaScript — OAuth-приложение

const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Все поля задачи описаны в camelCase — теми же именами, под которыми они приходят в ответе. Сырых имён верхним регистром в схеме больше нет. Исключения два и они ожидаемы: пользовательские поля портала (UF_*) и CHECKLIST — их состав зависит от портала, поэтому они приходят динамически (см. Динамические поля портала).

Столбец «Битрикс24» — имя, под которым поле принимается в filter, sort и select. Столбец «null» — приходит ли поле пустым.

Исключение — realStatus: это служебное имя только для фильтрации и сортировки, помеченное notReturned: true. Явный select=realStatus возвращает предупреждение UNKNOWN_SELECT_FIELD, а отдельного значения в ответе не будет. Для чтения фактического статуса используйте select=status.

Подписи полей label и description приходят на русском языке, а те, что платформа берёт напрямую с портала, — на языке портала. Заголовками запроса язык не переключается. У значений enum подпись label английская, русская — в labelRu.

Расшифровка status — поле fields.status.enum:

Расшифровка priority — поле fields.priority.enum:

Пользовательские поля (UF_*) принимаются при создании/обновлении и в фильтрах в обоих написаниях — ufCrmTask и UF_CRM_TASK (camelCase конвертируется автоматически). Важно: UF_CRM_TASK (привязка к CRM) принимает массив идентификаторов привязок — ["D_123"] (сделка), ["C_45"] (контакт), ["CO_7"] (компания), ["L_9"] (лид). Строка вместо массива ("D_123") молча игнорируется Битрикс24 — значение не сохранится (проверено на живом портале).

Поля-файлы принимают массив строк вида n<id>, где id — идентификатор файла из ответа POST /v1/files/upload. Стандартное поле-файл у задачи одно — ufTaskWebdavFiles, к нему добавляются пользовательские поля типа «файл», заведённые администратором портала. Пример значения — ["n9759"]. Значение другого вида — число, строка без префикса, одиночная строка вместо массива — отклоняется с 400 INVALID_DISK_ATTACHMENT_VALUE, вложение при этом не создаётся.

Запись заменяет весь список вложений задачи, пустой массив [] снимает все вложения. Очистка пустым массивом работает на POST /v1/tasks и PATCH /v1/tasks/:id; в батч-запросе (POST /v1/batch, POST /v1/tasks/batch) пустой массив на провод не уходит и вложения остаются на месте, поэтому очистку отправляйте одиночным запросом. На чтении поле возвращает не те номера, которые передавались на записи: приходят идентификаторы вложений, они меняются при каждой перезаписи поля и не совпадают с идентификаторами файлов на Диске. Чтобы обратиться к самому файлу, храните id из ответа загрузки.

Динамические поля портала

Кроме объявленных полей выше GET /v1/tasks/fields отдаёт то, что зависит от конкретного портала и потому не может быть описано заранее:

• пользовательские поля (UF_* / uf*) — их набор задаёт администратор портала.
• CHECKLIST — пункты чек-листа, здесь только для чтения. Управление — GET/POST /v1/tasks/{taskId}/checklist.

У таких полей type приходит от портала, а вместе с ним — словарь допустимых значений values и значение по умолчанию default:

{
  "CHECKLIST": {
    "type": "enum",
    "readonly": false,
    "label": "Чек-лист",
    "description": "Пункты чек-листа задачи. Здесь только для чтения — пункты создаются и меняются через эндпоинты чек-листа задачи.",
    "values": [
      { "value": "Y", "label": "Да" },
      { "value": "N", "label": "Нет" }
    ],
    "default": "N"
  }
}

label у элементов словаря приходит от портала и локализован его настройками. Там, где портал отдаёт только коды без подписей, label у элемента отсутствует.

Шесть полей индивидуальны, а не общие для задачи. favorite, isMuted, isPinned, newCommentsCount, notViewed и viewedDate описывают отношение к задаче того пользователя, от имени которого работает ключ, — другой ключ на том же портале увидит здесь другие значения. Не кэшируйте их как свойство задачи.

Опечатка monts в durationType — со стороны Битрикс24. Мы передаём словарь как есть, потому что портал принимает именно это написание. «Исправленное» months он не поймёт.

values и items — разные ключи и разные форматы. values — нормализованный словарь выше. items — сырой перечислимый справочник Битрикс24 у полей типа enumeration, он приходит как есть: [{ "ID": "1", "VALUE": "Первый" }]. Гарантия — на уровне ключа: у каждого из них всегда своя форма. Читайте тот, который вам нужен, по имени, а не «первый попавшийся словарь» — на сегодняшних порталах у одного поля бывает только один из двух, но одновременное присутствие мы не запрещаем.

Нульность. Поля, которые реально приходят пустыми, помечены в схеме признаком nullable: true и колонкой «null» в таблице выше — сегодня их 27. Типобезопасным клиентам (TS) объявляйте такие поля как T | null. Пустые accomplices и auditors приходят как [] — это списки. Пустые tags, group, accomplicesData и auditorsData приходят как {} — это словари.

Списки и карточки различаются составом ключей. Это свойство Битрикс24, а не нашей обёртки, поэтому такие поля намеренно не описаны в схеме: subStatus приходит только в списке, а action, checklist, checkListTree и checkListCanAdd — только в карточке. Они по-прежнему возвращаются в ответе.

Пример ответа

Показаны несколько полей для примера. Полный ответ содержит все объявленные поля, а также пользовательские поля портала.

{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "title": { "type": "string", "readonly": false },
      "description": { "type": "string", "readonly": false },
      "responsibleId": { "type": "number", "readonly": false },
      "createdBy": { "type": "number", "readonly": false },
      "status": {
        "type": "number",
        "readonly": false,
        "enum": [
          { "value": 1, "label": "New", "labelRu": "Новая" },
          { "value": 2, "label": "Pending", "labelRu": "Ждёт выполнения" },
          { "value": 3, "label": "In Progress", "labelRu": "Выполняется" },
          { "value": 4, "label": "Awaiting Control", "labelRu": "Ожидает контроля" },
          { "value": 5, "label": "Completed", "labelRu": "Завершена" },
          { "value": 6, "label": "Deferred", "labelRu": "Отложена" },
          { "value": 7, "label": "Declined", "labelRu": "Отклонена" }
        ]
      },
      "priority": {
        "type": "number",
        "readonly": false,
        "enum": [
          { "value": 0, "label": "Low", "labelRu": "Низкий" },
          { "value": 1, "label": "Normal", "labelRu": "Обычный" },
          { "value": 2, "label": "High", "labelRu": "Высокий" }
        ]
      },
      "deadline": { "type": "datetime", "readonly": false },
      "createdDate": { "type": "datetime", "readonly": false },
      "changedDate": { "type": "datetime", "readonly": false }
    }
  }
}

Пример ответа при ошибке

403 — нет скоупа:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'tasks' scope"
  }
}

Ошибки

Полный список общих ошибок API — Ошибки.

Смотрите также

• Создать задачу
• Обновить задачу
• Список задач
• Поиск задач
• Агрегация задач
• Entity API