REST: чек-листы и комментарии задач

Чек-листы и комментарии дополняют задачу деталями: подзадачами внутри пункта и историей обсуждения. В REST Битрикс24 за них отвечают отдельные семейства — task.checklistitem.* и task.commentitem.*.

Два семейства вокруг задачи

Задача (tasks.task) — контейнер, но вся детализация внутри неё живёт в дочерних сущностях. Чек-лист — это список пунктов с отметкой выполнения, комментарии — лента сообщений. Оба семейства относятся к скоупу task и всегда работают в привязке к идентификатору задачи.

• task.checklistitem.* — CRUD и действия над пунктами чек-листа;
• task.commentitem.* — CRUD над комментариями.

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

Метод task.checklistitem.add принимает ID задачи и объект полей. Минимум — заголовок пункта:

POST /rest/1/xxxx/task.checklistitem.add.json
{"TASKID":142,"FIELDS":{"TITLE":"Согласовать смету","SORT_INDEX":10,"IS_COMPLETE":"N"}}

Полезные поля пункта:

Метод вернёт ID нового пункта, который пригодится для дальнейших операций.

Управление пунктами

Над созданным пунктом доступен набор действий:

• task.checklistitem.get — получить один пункт (TASKID, ITEMID);
• task.checklistitem.getlist — все пункты задачи;
• task.checklistitem.update — изменить поля;
• task.checklistitem.delete — удалить;
• task.checklistitem.complete / renew — отметить выполненным или снять отметку;
• task.checklistitem.movesort — переставить пункт (задать AFTER_ITEM_ID);
• task.checklistitem.isactionallowed — проверить, разрешено ли действие текущему пользователю.

Отметку выполнения лучше ставить именно через complete, а не через update с IS_COMPLETE=Y — так корректно фиксируется автор и время действия.

Комментарии: task.commentitem.add

Комментарий добавляется к задаче методом task.commentitem.add. Обязательный параметр — текст сообщения:

POST /rest/1/xxxx/task.commentitem.add.json
{"TASKID":142,"FIELDS":{"POST_MESSAGE":"Смета готова, приложил файл.","AUTHOR_ID":17}}

Текст в POST_MESSAGE поддерживает BB-код: [B], [URL], упоминания [USER=17]Имя[/USER]. Если AUTHOR_ID не указан, автором станет пользователь вызова.

Чтение и правка комментариев

Остальные методы семейства предсказуемы:

• task.commentitem.getlist — лента комментариев задачи, с сортировкой по дате;
• task.commentitem.get — один комментарий (TASKID, ITEMID);
• task.commentitem.update — редактировать текст;
• task.commentitem.delete — удалить.

Через getlist удобно строить синхронизацию обсуждений: например, переносить сообщения из внешнего хелпдеска в задачу и обратно. Для регулярной выгрузки комбинируйте вызовы в batch, чтобы уложиться в лимиты API.

Типовые сценарии автоматизации

Связка чек-листов и комментариев закрывает частые задачи интеграций:

1. Шаблоны работ. При создании задачи из внешней CRM автоматически наполняем чек-лист стандартными пунктами процесса.
2. Прогресс во внешней системе. Считаем долю выполненных пунктов через getlist и отражаем процент готовности на портале клиента.
3. Синхронизация переписки. Сообщения из мессенджера или почты складываем в комментарии задачи, сохраняя единую историю.

Итог

Чек-листы (task.checklistitem.*) и комментарии (task.commentitem.*) — это детализация и история задачи. Работайте через профильные действия (complete, renew), храните карту внешних идентификаторов и группируйте вызовы в batch.

Мы собираем такие сценарии в надёжные интеграции: шаблоны работ, синхронизацию обсуждений и отражение прогресса во внешних кабинетах — с логированием и защитой от дублей. Поможем спроектировать обмен и поддерживать его в рабочем состоянии.