## Поля задачи

`GET /v1/tasks/fields`

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

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

## Примеры

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

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

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

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

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

```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-приложение

```javascript
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`.

| Поле | Битрикс24 | Тип | RO | null | Описание |
|------|----------|-----|:--:|:--:|---------|
| `id` | `ID` | number | да |  | Идентификатор задачи |
| `title` | `TITLE` | string | |  | Название задачи |
| `description` | `DESCRIPTION` | string | | да | Описание (поддерживает BB-код) |
| `responsibleId` | `RESPONSIBLE_ID` | number | |  | Ответственный. Список: `GET /v1/users` |
| `createdBy` | `CREATED_BY` | number | |  | Постановщик. По умолчанию — пользователь ключа. Задаётся и при создании, и в PATCH — Битрикс24 применяет значение в пределах прав вызывающего пользователя. Передавайте только существующего сотрудника, иначе задача перестанет управляться через API (см. [PATCH /v1/tasks/:id](./update.md)). Список: `GET /v1/users` |
| `status` | `STATUS` | number | |  | Статус задачи. Допустимые значения в `fields.status.enum`. **`filter[status]` — виртуальный (мета-)фильтр**: Битрикс24 понимает здесь `−1` (просрочена), `−2` (не просмотрена), `−3` (почти просрочена), а не число из поля `status` ответа — поэтому `filter[status]=2` НЕ вернёт все задачи со статусом `2`. Для фильтра по фактическому статусу используйте `realStatus` |
| `realStatus` | `REAL_STATUS` | number | да |  | Реальный (фактически сохранённый) статус задачи — совпадает со значением поля `status` в ответе. Только для `filter`/`sort`: `?filter[realStatus]=2`, `?sort=realStatus` — в отличие от виртуального `filter[status]`, фильтрует по хранимому статусу. Значения те же, что у `status` (см. `fields.status.enum`). В теле ответа отдельно не возвращается (реальный статус уже есть в `status`) — в схеме это помечено признаком `notReturned`. Менять статус — через `status` |
| `priority` | `PRIORITY` | number | |  | Приоритет задачи. Допустимые значения в `fields.priority.enum` |
| `groupId` | `GROUP_ID` | number | |  | Рабочая группа. Список: `GET /v1/workgroups` |
| `parentId` | `PARENT_ID` | number | | да | Родительская задача. Список: `GET /v1/tasks` |
| `deadline` | `DEADLINE` | datetime | | да | Крайний срок (ISO 8601) |
| `dateStart` | `DATE_START` | datetime | да | да | Фактическая дата начала работы над задачей. Фильтруется: `?filter[>=dateStart]=2026-05-01T00:00:00` |
| `startDatePlan` | `START_DATE_PLAN` | datetime | | да | Плановая дата начала |
| `endDatePlan` | `END_DATE_PLAN` | datetime | | да | Плановая дата окончания |
| `timeEstimate` | `TIME_ESTIMATE` | number | |  | Оценка трудозатрат в секундах |
| `timeSpentInLogs` | `TIME_SPENT_IN_LOGS` | number | да | да | Фактически затраченное время в секундах — сумма записей учёта времени, см. [Учёт времени задач](./time.md). Пока таких записей нет, приходит `null`. Выбирается через `?select=timeSpentInLogs`, сортируется через `?sort=-timeSpentInLogs`. Фильтр по этому полю **молча игнорируется** — запрос вернёт тот же набор, что и без него. Сумму по выборке даёт [агрегация](./aggregate.md) |
| `tags` | `TAGS` | object |  | | Метки задачи. Словарь с ключом по идентификатору метки: `{ "<id>": { "id": <id>, "title": "<метка>" } }`. Без меток — `{}`. Фильтр по одной метке: `?filter[tags]=метка` (транслируется в Битрикс24 `TAG`) |
| `accomplices` | `ACCOMPLICES` | array | |  | Соисполнители. Список: `GET /v1/users`. Фильтр по одному пользователю: `?filter[accomplices]=25` (транслируется в Битрикс24 `ACCOMPLICE`) |
| `auditors` | `AUDITORS` | array | |  | Наблюдатели. Список: `GET /v1/users`. Фильтр по одному пользователю: `?filter[auditors]=25` (транслируется в Битрикс24 `AUDITOR`) |
| `closedDate` | `CLOSED_DATE` | datetime | | да | Дата закрытия (заполняется при переводе в статус `5` или `6`). Служебное поле, но принимается на записи — см. [PATCH /v1/tasks/:id](./update.md) |
| `createdDate` | `CREATED_DATE` | datetime | |  | Дата создания. Служебное поле, но принимается на записи — см. [PATCH /v1/tasks/:id](./update.md) |
| `changedDate` | `CHANGED_DATE` | datetime | |  | Дата последнего изменения. Служебное поле, но принимается на записи — переданное значение сохраняется вместо текущего времени, см. [PATCH /v1/tasks/:id](./update.md) |
| `changedBy` | `CHANGED_BY` | number | |  | ID пользователя, последним изменившего задачу. Служебное поле, но принимается на записи — см. [PATCH /v1/tasks/:id](./update.md). Список: `GET /v1/users` |
| `closedBy` | `CLOSED_BY` | number | | да | ID пользователя, закрывшего задачу. Служебное поле, но принимается на записи — см. [PATCH /v1/tasks/:id](./update.md). Список: `GET /v1/users` |
| `statusChangedBy` | `STATUS_CHANGED_BY` | number | | да | ID пользователя, последним изменившего статус задачи. Служебное поле, но принимается на записи — см. [PATCH /v1/tasks/:id](./update.md). Список: `GET /v1/users` |
| `activityDate` | `ACTIVITY_DATE` | datetime | да |  | Дата последней активности (учитывает комментарии, в отличие от `changedDate`). Возвращается всегда и выбирается через `?select=activityDate`. Важно: не фильтруется на стороне Битрикс24 — для фильтра используйте `changedDate` |
| `mark` | `MARK` | string |  | да | Оценка задачи руководителем. Значения — в `fields.mark.enum` (`P` — положительная, `N` — отрицательная). Пока оценки нет — `null` |
| `multitask` | `MULTITASK` | boolean |  |  | У задачи несколько ответственных |
| `notViewed` | `NOT_VIEWED` | boolean | да |  | Ответственный ещё не открывал задачу. Индивидуально для пользователя ключа |
| `replicate` | `REPLICATE` | boolean |  |  | Задача — шаблон повторяемой задачи |
| `stageId` | `STAGE_ID` | number |  |  | Стадия канбана. `0`, если задача не на доске |
| `sprintId` | `SPRINT_ID` | number |  | да | Спринт Скрама |
| `backlogId` | `BACKLOG_ID` | number |  | да | Бэклог Скрама |
| `statusChangedDate` | `STATUS_CHANGED_DATE` | datetime | да |  | Когда последний раз менялся статус. Важно: не фильтруется на стороне Битрикс24 — используйте `changedDate` |
| `guid` | `GUID` | string | да |  | Глобальный идентификатор в фигурных скобках, сохраняется при экспорте и импорте. Для запросов используйте `id` |
| `xmlId` | `XML_ID` | string |  | да | Произвольный код для сопоставления с внешней системой |
| `commentsCount` | `COMMENTS_COUNT` | number | да | да | Всего комментариев к задаче |
| `serviceCommentsCount` | `SERVICE_COMMENTS_COUNT` | number | да | да | Сколько автоматических комментариев добавил сам Битрикс24 — например, о смене статуса |
| `newCommentsCount` | `NEW_COMMENTS_COUNT` | number | да |  | Непрочитанных комментариев. Индивидуально для пользователя ключа |
| `allowChangeDeadline` | `ALLOW_CHANGE_DEADLINE` | boolean |  |  | Ответственный может сам переносить `deadline` |
| `allowTimeTracking` | `ALLOW_TIME_TRACKING` | boolean |  |  | Включён учёт затраченного времени. Записи — `GET /v1/tasks/{taskId}/time` |
| `chatId` | `CHAT_ID` | number | да | да | Чат обсуждения задачи. Сообщения — `GET /v1/tasks/{taskId}/chat/messages` |
| `durationPlan` | `DURATION_PLAN` | number |  | да | Плановые трудозатраты в единицах `durationType` |
| `durationFact` | `DURATION_FACT` | number | да | да | Фактические трудозатраты в единицах `durationType` |
| `durationType` | `DURATION_TYPE` | string |  |  | Единица измерения `durationPlan` и `durationFact`. Значения — в `fields.durationType.enum` |
| `favorite` | `FAVORITE` | boolean | да |  | В избранном. Индивидуально для пользователя ключа. Управление — `POST/DELETE /v1/tasks/{taskId}/favorite` |
| `sorting` | `SORTING` | number | да | да | Вес ручной сортировки внутри списка |
| `isMuted` | `IS_MUTED` | boolean | да |  | Уведомления отключены. Индивидуально для пользователя ключа |
| `isPinned` | `IS_PINNED` | boolean | да |  | Закреплена в списке задач. Индивидуально для пользователя ключа. Управление — `POST/DELETE /v1/tasks/{taskId}/pin` |
| `isPinnedInGroup` | `IS_PINNED_IN_GROUP` | boolean | да |  | Закреплена внутри списка своей рабочей группы |
| `flowId` | `FLOW_ID` | number | да | да | Поток, в котором создана задача |
| `siteId` | `SITE_ID` | string | да |  | Сайт портала, к которому относится задача |
| `forumId` | `FORUM_ID` | number | да | да | Служебное хранилище комментариев |
| `forumTopicId` | `FORUM_TOPIC_ID` | number | да | да | Служебное хранилище комментариев |
| `exchangeId` | `EXCHANGE_ID` | number | да | да | Идентификатор в Microsoft Exchange. Заполняется только на порталах с синхронизацией |
| `exchangeModified` | `EXCHANGE_MODIFIED` | datetime | да | да | Когда задача последний раз менялась на стороне Microsoft Exchange |
| `outlookVersion` | `OUTLOOK_VERSION` | number | да |  | Счётчик ревизии синхронизации с Microsoft Outlook |
| `viewedDate` | `VIEWED_DATE` | datetime | да | да | Когда пользователь ключа последний раз открывал задачу |
| `subordinate` | `SUBORDINATE` | boolean | да |  | Задача принадлежит подчинённому пользователя ключа |
| `taskControl` | `TASK_CONTROL` | boolean |  |  | После завершения задача уходит постановщику на приёмку |
| `addInReport` | `ADD_IN_REPORT` | boolean |  |  | Задача учитывается в отчётах по эффективности |
| `matchWorkTime` | `MATCH_WORK_TIME` | boolean |  |  | Расчёт срока пропускает выходные и праздники |
| `forkedByTemplateId` | `FORKED_BY_TEMPLATE_ID` | number | да | да | Шаблон, из которого создана задача. `null` при ручном создании |
| `descriptionInBbcode` | `DESCRIPTION_IN_BBCODE` | boolean | да |  | Поле `description` содержит BB-код, а не обычный текст |
| `creator` | — | object | да |  | Карточка постановщика: имя, ссылка, аватар. Не фильтруется и не выбирается через `select` |
| `responsible` | — | object | да |  | Карточка ответственного. Не фильтруется и не выбирается через `select` |
| `accomplicesData` | — | object | да |  | Карточки соисполнителей с ключом по идентификатору пользователя. Без соисполнителей — `{}` |
| `auditorsData` | — | object | да |  | Карточки наблюдателей с ключом по идентификатору пользователя. Без наблюдателей — `{}` |
| `group` | — | object | да |  | Карточка рабочей группы: название, изображение. Без группы — `{}` |

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

| Значение | Метка | Описание |
|----------|-------|----------|
| `1` | New | Начальное состояние. Новые задачи создаются со статусом `2`. Значение `1` встречается у задач, импортированных из внешних систем или мигрированных со старых версий портала |
| `2` | Pending | Ждёт выполнения. Статус по умолчанию для новых задач |
| `3` | In Progress | Выполняется |
| `4` | Awaiting Control | Ожидает контроля. Исполнитель пометил задачу как сделанную, постановщик должен подтвердить |
| `5` | Completed | Завершена |
| `6` | Deferred | Отложена |
| `7` | Declined | Отклонена |

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

| Значение | Метка |
|----------|-------|
| `0` | Низкий |
| `1` | Обычный |
| `2` | Высокий |

**Пользовательские поля (`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`](../files/upload.md). Стандартное поле-файл у задачи одно — `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`:

```json
{
  "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` приходит только в [списке](./list.md), а `action`, `checklist`, `checkListTree` и `checkListCanAdd` — только в [карточке](./get.md). Они по-прежнему возвращаются в ответе.

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

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

```json
{
  "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 — нет скоупа:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- [Создать задачу](./create.md)
- [Обновить задачу](./update.md)
- [Список задач](./list.md)
- [Поиск задач](./search.md)
- [Агрегация задач](./aggregate.md)
- [Entity API](/docs/entity-api)