REST: task.checklistitem

Группа методов task.checklistitem.* отвечает за пункты чек-листов внутри задач Битрикс24. Через неё можно программно добавлять, отмечать выполненными, переупорядочивать и удалять элементы — например, разворачивать типовой чек-лист при создании задачи из шаблона. Разберём все методы, параметры и порядок работы.

Состав группы task.checklistitem.*

Чек-лист привязан к конкретной задаче, поэтому все методы первым аргументом принимают TASKID. Полный набор операций:

Добавление пункта

Метод task.checklistitem.add принимает ID задачи и объект с полями пункта. Основное поле — TITLE.

POST https://portal.bitrix24.ru/rest/1/xxxx/task.checklistitem.add.json

{ "TASKID": 512, "FIELDS": { "TITLE": "Согласовать смету", "SORT_INDEX": 10 } }

Поле SORT_INDEX задаёт позицию в списке. Для построения вложенного чек-листа используется PARENT_ID — ссылка на пункт-раздел. Метод возвращает ID нового элемента.

Отметки выполнения

Статус пункта переключается двумя парными методами:

• task.checklistitem.complete — ставит пункт в «выполнено»;
• task.checklistitem.renew — возвращает в «не выполнено».

Оба принимают TASKID и ITEMID:

{ "TASKID": 512, "ITEMID": 3401 }

Изменять текст выполненного пункта можно через task.checklistitem.update, передав новое значение TITLE в объекте FIELDS. Статус выполнения при этом сохраняется.

Порядок и вложенность пунктов

За визуальный порядок отвечает метод task.checklistitem.moveafteritem. Он перемещает пункт сразу за указанным:

{ "TASKID": 512, "ITEMID": 3401, "AFTERITEMID": 3405 }

Если AFTERITEMID равен 0, пункт становится первым в списке. Для древовидных чек-листов важно помнить о двух уровнях:

1. Пункт-раздел создаётся без PARENT_ID;
2. Вложенные пункты ссылаются на его ID через PARENT_ID.

Проверка прав перед действием

Метод task.checklistitem.isactionallowed возвращает, разрешено ли текущему пользователю выполнить операцию над пунктом. Он принимает TASKID, ITEMID и код действия ACTION.

Возможные действия соответствуют константам: добавление, изменение, удаление, отметка выполнения. Это полезно, когда интерфейс внешней системы должен показывать или скрывать кнопки в зависимости от роли пользователя.

На практике проверку прав чаще делают неявно — просто обрабатывая ошибку доступа от основного метода, — но явный вызов isactionallowed позволяет построить корректный UI без «слепых» попыток.

Чтение чек-листа

Метод task.checklistitem.getlist возвращает все пункты задачи с их статусами, порядком и вложенностью. Каждый элемент содержит ключевые поля:

• ID — идентификатор пункта;
• TITLE — текст;
• IS_COMPLETE — Y/N, отметка выполнения;
• SORT_INDEX — позиция;
• PARENT_ID — родитель для вложенных.

Для отображения прогресса достаточно посчитать долю пунктов с IS_COMPLETE = Y. При двусторонней синхронизации сохраняйте пары «внешний ID — ID пункта Битрикс24», чтобы надёжно сопоставлять элементы между системами.

Итог

Методы task.checklistitem.* дают полный контроль над чек-листами задач: добавление, правка, отметки выполнения, порядок, вложенность и проверка прав. Главное при интеграции — не пересоздавать пункты, а сопоставлять их по внешнему ключу, аккуратно управлять SORT_INDEX и обрабатывать ошибки доступа.

Мы автоматизируем сценарии, где задачи и их чек-листы разворачиваются из шаблонов, заявок или данных 1С без ручного ввода. Настроим корректную двустороннюю синхронизацию статусов, чтобы прогресс по задачам отражался и в Битрикс24, и во внешней системе.