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

Чек-лист задачи

Пункты чек-листа задачи — вложенный ресурс задачи. У каждого пункта есть название, статус выполнения, признак важности, порядок сортировки, участники и (опционально) родительский пункт для вложенных чек-листов. Базовый путь — /v1/tasks/:taskId/checklist. Все операции адресуются идентификатором задачи :taskId.

Битрикс24 API: task.checklistitem.* Скоуп: task

Почему отдельный ресурс. Битрикс24 не принимает поле CHECKLIST внутри POST /v1/tasks (tasks.task.add) — чек-лист нельзя создать вместе с задачей. Единственный поддерживаемый способ управлять пунктами — это методы семейства task.checklistitem.*, которые и оборачивает данный ресурс. Сначала создайте задачу, затем добавляйте пункты по одному.

Список пунктов чек-листа

GET /v1/tasks/:taskId/checklist

Возвращает все пункты чек-листа задачи, включая вложенные (дочерние) пункты.

Параметры

Параметр Тип Обяз. Описание
taskId (path) integer да ID задачи
sort (query) string нет Сортировка в формате поле:направление, например sortIndex:asc. Поля: id, parentId, createdBy, title, sortIndex, isComplete, isImportant, toggledBy, toggledDate. Направление — asc / desc (по умолчанию asc). Без параметра Битрикс24 сортирует по id по убыванию
start (query) integer нет Смещение в выборке. Битрикс24 отдаёт страницами по 50 пунктов — для следующей страницы передайте start=50, затем 100 и так далее

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/tasks/3943/checklist?sort=sortIndex:asc" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/tasks/3943/checklist?sort=sortIndex:asc" \
  -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/3943/checklist?sort=sortIndex:asc",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const { data } = await res.json();

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

javascript 
const res = await fetch(
  "https://vibecode.bitrix24.tech/v1/tasks/3943/checklist?sort=sortIndex:asc",
  {
    headers: {
      "X-Api-Key": "YOUR_APP_KEY",
      "Authorization": "Bearer USER_SESSION_TOKEN",
    },
  }
);
const { data } = await res.json();

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив пунктов чек-листа
data[].id string ID пункта
data[].taskId string ID родительской задачи
data[].parentId integer / string ID родительского пункта. 0 — пункт верхнего уровня (сам является чек-листом)
data[].title string Текст пункта
data[].sortIndex string Индекс сортировки
data[].isComplete string Статус выполнения — "Y" / "N"
data[].isImportant string Признак важности — "Y" / "N"
data[].createdBy string Автор пункта
data[].toggledBy string | null Кто последним менял статус выполнения
data[].toggledDate string Когда статус менялся последний раз. Пустая строка, если не менялся
data[].members array Участники пункта — объекты { id, type, name, personalPhoto, personalGender, image, isCollaber }
data[].attachments array Прикреплённые файлы
meta.total number Общее число пунктов в выборке

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": "211",
      "taskId": "3943",
      "parentId": 0,
      "createdBy": "1317",
      "title": "Документы",
      "sortIndex": "1",
      "isComplete": "N",
      "isImportant": "N",
      "toggledBy": null,
      "toggledDate": "",
      "members": [],
      "attachments": []
    },
    {
      "id": "213",
      "taskId": "3943",
      "parentId": "211",
      "createdBy": "1317",
      "title": "Собрать и проверить документы",
      "sortIndex": "100",
      "isComplete": "N",
      "isImportant": "Y",
      "toggledBy": null,
      "toggledDate": "",
      "members": [
        {
          "id": "1317",
          "type": "A",
          "name": "Иван Петров",
          "personalPhoto": "35959",
          "personalGender": "",
          "image": "https://example.bitrix24.ru/...",
          "isCollaber": false
        }
      ],
      "attachments": []
    }
  ],
  "meta": { "total": 2 }
}

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

422 — задача не найдена или недоступна:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "TASKS_ERROR_EXCEPTION_#8; Action failed; 8/TE/ACTION_FAILED_TO_BE_PROCESSED",
    "b24Code": "ERROR_CORE"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS taskId не положительное целое, либо неизвестное поле сортировки
422 BITRIX_ERROR Задача с указанным taskId не существует или недоступна ключу — Битрикс24 бросил исключение. Существующая задача без пунктов отвечает 200 с пустым массивом
403 SCOPE_DENIED API-ключ не имеет скоупа task
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

  • parentId: 0 — пункт верхнего уровня, сам являющийся чек-листом. Дочерние пункты ссылаются на его id через свой parentId.
  • Числовые значения и флаги — строки. id, taskId, sortIndex приходят строками. isComplete / isImportant — строками "Y"/"N", не булевыми значениями.

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