Для AI-агентов: markdown этой страницы — /docs-content/entities/tasks/checklist-actions/tree.md индекс документации — /llms.txt

Сохранить чек-лист задачи

POST /v1/tasks/:taskId/checklist/tree

Сохраняет весь чек-лист задачи одним вызовом: переданный плоский массив пунктов заменяет текущий чек-лист. Поля пунктов пишутся в верхнем регистре.

Параметры

Параметр Тип Обяз. Описание
ПараметрtaskId (path) Типnumber Обяз.да ОписаниеID задачи, целое положительное число. Список: GET /v1/tasks

Поля запроса (body)

Поле Тип Обяз. Описание
Полеitems Типarray Обяз.да ОписаниеВсе пункты чек-листа одним плоским массивом. Пункт, которого нет в массиве, удаляется. Пустой массив удаляет весь чек-лист. Порядок пунктов с одним родителем в массиве задаёт их sortIndex
Полеitems[].ID Типnumber Обяз.нет ОписаниеID существующего пункта. Список: GET /v1/tasks/:taskId/checklist. С ID пункт сохраняется под прежним ID. Без него пункт создаётся заново с новым ID, а прежний удаляется
Полеitems[].NODE_ID Типstring Обяз.нет ОписаниеКлюч пункта внутри запроса, например root-1. На него ссылаются подпункты в PARENT_NODE_ID, под ним пункт приходит в ответе. Задавайте каждому пункту свой NODE_ID: из нескольких новых пунктов без него сохраняется только последний, остальные пропадают без ошибки
Полеitems[].PARENT_NODE_ID Типstring | number Обяз.нет ОписаниеNODE_ID родительского пункта. 0 или без поля — пункт верхнего уровня, его TITLE становится названием чек-листа
Полеitems[].TITLE Типstring Обяз.да ОписаниеТекст пункта. Нужен каждому пункту, в том числе пункту с ID
Полеitems[].IS_COMPLETE Типboolean Обяз.нет Описаниеtrue — пункт выполнен. Без поля новый пункт сохраняется невыполненным. Строка "Y" вместо true сохраняет пункт невыполненным, ошибки при этом нет
Полеitems[].IS_IMPORTANT Типboolean Обяз.нет Описаниеtrue — пункт важный. Без поля — false: у пункта с ID прежняя отметка важности снимается
Полеparameters Типobject Обяз.нет ОписаниеДополнительные параметры сохранения. На результат не влияют

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/tasks/4218/checklist/tree" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "NODE_ID": "root-1", "PARENT_NODE_ID": 0, "TITLE": "Подготовка к запуску", "IS_COMPLETE": false, "IS_IMPORTANT": false },
      { "NODE_ID": "child-1", "PARENT_NODE_ID": "root-1", "TITLE": "Проверить сборку", "IS_COMPLETE": false, "IS_IMPORTANT": true },
      { "NODE_ID": "child-2", "PARENT_NODE_ID": "root-1", "TITLE": "Обновить описание", "IS_COMPLETE": false, "IS_IMPORTANT": false }
    ]
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/tasks/4218/checklist/tree" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "NODE_ID": "root-1", "PARENT_NODE_ID": 0, "TITLE": "Подготовка к запуску", "IS_COMPLETE": false, "IS_IMPORTANT": false },
      { "NODE_ID": "child-1", "PARENT_NODE_ID": "root-1", "TITLE": "Проверить сборку", "IS_COMPLETE": false, "IS_IMPORTANT": true },
      { "NODE_ID": "child-2", "PARENT_NODE_ID": "root-1", "TITLE": "Обновить описание", "IS_COMPLETE": false, "IS_IMPORTANT": false }
    ]
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/4218/checklist/tree', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { NODE_ID: 'root-1', PARENT_NODE_ID: 0, TITLE: 'Подготовка к запуску', IS_COMPLETE: false, IS_IMPORTANT: false },
      { NODE_ID: 'child-1', PARENT_NODE_ID: 'root-1', TITLE: 'Проверить сборку', IS_COMPLETE: false, IS_IMPORTANT: true },
      { NODE_ID: 'child-2', PARENT_NODE_ID: 'root-1', TITLE: 'Обновить описание', IS_COMPLETE: false, IS_IMPORTANT: false },
    ],
  }),
})

const { data } = await res.json()
const saved = data?.checkListItem?.traversedItems ?? {}
for (const [nodeId, item] of Object.entries(saved)) {
  console.log(nodeId, '→ ID пункта', item.id)
}

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/4218/checklist/tree', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { NODE_ID: 'root-1', PARENT_NODE_ID: 0, TITLE: 'Подготовка к запуску', IS_COMPLETE: false, IS_IMPORTANT: false },
      { NODE_ID: 'child-1', PARENT_NODE_ID: 'root-1', TITLE: 'Проверить сборку', IS_COMPLETE: false, IS_IMPORTANT: true },
      { NODE_ID: 'child-2', PARENT_NODE_ID: 'root-1', TITLE: 'Обновить описание', IS_COMPLETE: false, IS_IMPORTANT: false },
    ],
  }),
})

const { data } = await res.json()
const saved = data?.checkListItem?.traversedItems ?? {}

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue, если запрос выполнен
Полеdata.checkListItem Типobject | null ОписаниеСохранённый чек-лист. null, если передан пустой items
Полеdata.checkListItem.traversedItems Типobject ОписаниеСохранённые пункты. Ключ — NODE_ID пункта из запроса, у пункта без NODE_ID — "0"
Полеdata.checkListItem.traversedItems.<NODE_ID>.id Типnumber ОписаниеID пункта. Пункт без ID в запросе получает новый ID
Полеdata.checkListItem.traversedItems.<NODE_ID>.copiedId Типnumber | null ОписаниеID пункта-оригинала, если пункт скопирован. Метод возвращает null
Полеdata.checkListItem.traversedItems.<NODE_ID>.entityId Типnumber ОписаниеID задачи из пути
Полеdata.checkListItem.traversedItems.<NODE_ID>.userId Типnumber ОписаниеID сотрудника, от имени которого сделан вызов
Полеdata.checkListItem.traversedItems.<NODE_ID>.createdBy Типnumber | null ОписаниеID автора пункта. У пункта, сохранённого по ID, — null, автора такого пункта отдаёт GET /v1/tasks/:taskId/checklist
Полеdata.checkListItem.traversedItems.<NODE_ID>.parentId Типnumber ОписаниеID родительского пункта. 0 — пункт верхнего уровня
Полеdata.checkListItem.traversedItems.<NODE_ID>.title Типstring ОписаниеТекст пункта
Полеdata.checkListItem.traversedItems.<NODE_ID>.sortIndex Типnumber ОписаниеМесто пункта среди пунктов с тем же родителем: чем меньше число, тем выше пункт
Полеdata.checkListItem.traversedItems.<NODE_ID>.displaySortIndex Типstring ОписаниеНомер пункта для показа. Метод возвращает пустую строку
Полеdata.checkListItem.traversedItems.<NODE_ID>.isComplete Типboolean ОписаниеВыполнен ли пункт
Полеdata.checkListItem.traversedItems.<NODE_ID>.isImportant Типboolean ОписаниеВажный ли пункт
Полеdata.checkListItem.traversedItems.<NODE_ID>.completedCount Типnumber ОписаниеЧисло выполненных подпунктов. Метод возвращает 0, даже если подпункт выполнен
Полеdata.checkListItem.traversedItems.<NODE_ID>.members Типarray ОписаниеУчастники пункта. Без участников — пустой массив
Полеdata.checkListItem.traversedItems.<NODE_ID>.attachments Типarray | object ОписаниеВложения пункта. Без вложений — пустой массив
Полеdata.checkListItem.traversedItems.<NODE_ID>.nodeId Типstring | null ОписаниеNODE_ID пункта из запроса. У пункта без NODE_ID — null
Полеdata.checkListItem.taskId Типnull ОписаниеВсегда null. ID задачи — в entityId пунктов

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

Чек-лист сохранён:

JSON 
{
  "success": true,
  "data": {
    "checkListItem": {
      "traversedItems": {
        "root-1": {
          "id": 268,
          "copiedId": null,
          "entityId": 4218,
          "userId": 1295,
          "createdBy": 1295,
          "parentId": 0,
          "title": "Подготовка к запуску",
          "sortIndex": 0,
          "displaySortIndex": "",
          "isComplete": false,
          "isImportant": false,
          "completedCount": 0,
          "members": [],
          "attachments": [],
          "nodeId": "root-1"
        },
        "child-1": {
          "id": 270,
          "copiedId": null,
          "entityId": 4218,
          "userId": 1295,
          "createdBy": 1295,
          "parentId": 268,
          "title": "Проверить сборку",
          "sortIndex": 0,
          "displaySortIndex": "",
          "isComplete": false,
          "isImportant": true,
          "completedCount": 0,
          "members": [],
          "attachments": [],
          "nodeId": "child-1"
        },
        "child-2": {
          "id": 272,
          "copiedId": null,
          "entityId": 4218,
          "userId": 1295,
          "createdBy": 1295,
          "parentId": 268,
          "title": "Обновить описание",
          "sortIndex": 1,
          "displaySortIndex": "",
          "isComplete": false,
          "isImportant": false,
          "completedCount": 0,
          "members": [],
          "attachments": [],
          "nodeId": "child-2"
        }
      },
      "taskId": null
    }
  }
}

Передан пустой items, чек-лист задачи удалён:

JSON 
{
  "success": true,
  "data": {
    "checkListItem": null
  }
}

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

422 — у нового пункта нет TITLE:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Указано некорректное значение [] для поля [TITLE] в элементе [, ]",
    "b24Code": "0"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеtaskId — не целое положительное число. Сообщение taskId must be a positive integer
HTTP400 КодINVALID_PARAMS ОписаниеТело — не JSON-объект, например массив. Сообщение JSON object body is required
HTTP400 КодINVALID_PARAMS ОписаниеНет поля items, или items — не массив. Сообщение items must be an array
HTTP400 КодINVALID_PARAMS Описаниеparameters — не объект. Сообщение parameters must be an object
HTTP401 КодMISSING_API_KEY ОписаниеНе передан X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет токенов Битрикс24
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа task
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч в режиме «только чтение». В error.details.switchUrl — адрес раздела, где режим меняется
HTTP415 КодFST_ERR_CTP_INVALID_MEDIA_TYPE ОписаниеТело с Content-Type, который API не разбирает, например application/xml
HTTP422 КодBITRIX_ERROR ОписаниеУ пункта нет TITLE, в том числе у пункта с ID. Сообщение на русском портале — Указано некорректное значение [] для поля [TITLE] в элементе [283, ], где 283 — ID пункта. У нового пункта место ID в сообщении пустое: [, ]
HTTP422 КодBITRIX_ERROR ОписаниеСотрудник, от имени которого идёт вызов, не имеет доступа к задаче. Тот же ответ этот сотрудник получает на taskId несуществующей задачи. Сообщение на русском портале — Доступ к задаче запрещен, на портале .com — Access to task was denied. Спецификация API объявляет на этот случай 404 TASK_NOT_FOUND, но на проверенных порталах приходит этот ответ
HTTP429 КодRATE_LIMITED ОписаниеПревышена частота запросов. Действующий потолок — в заголовке x-ratelimit-limit

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

Известные особенности

Ошибка не откатывает уже сохранённое. Ответ 422 не значит, что чек-лист остался прежним. Запрос с новым названием пункта с ID и новым пунктом без TITLE возвращает 422, а название пункта всё равно меняется. Пункты, которых не было в запросе, при этом не удаляются. После ошибки проверяйте итог через GET /v1/tasks/:taskId/checklist.

Несуществующий taskId не всегда даёт ошибку. Ответ зависит от сотрудника, от имени которого идёт вызов: одному приходит 422 BITRIX_ERROR, другому — 200. Во втором случае пункты сохраняются с entityId, равным переданному taskId, и не видны ни в одной задаче. Перед сохранением проверьте задачу через GET /v1/tasks/:id.

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