REST: tasks.task.add и обновление

Методы tasks.task.add и tasks.task.update — основа программного управления задачами в Битрикс24. Через них внешняя система ставит задачи менеджерам, меняет статусы, сроки и исполнителей. Разберём структуру поля fields, обязательные параметры и подводные камни при массовой постановке задач.

tasks.task.add: минимальный запрос

Метод tasks.task.add принимает единственный параметр — объект fields с полями задачи. Обязательны всего два: TITLE (название) и RESPONSIBLE_ID (ID исполнителя).

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

{ "fields": { "TITLE": "Подготовить КП", "RESPONSIBLE_ID": 4, "DEADLINE": "2026-07-22T18:00:00+03:00", "DESCRIPTION": "Смета по проекту X" } }

В ответе — объект task с полным набором полей созданной задачи, включая присвоенный id. Обратите внимание: в ответах современного метода ключи приходят в нижнем регистре (id, title), а в запросе fields поля пишутся в верхнем регистре.

Основные поля задачи

Полный перечень полей возвращает метод tasks.task.getFields — им удобно свериться перед интеграцией. Наиболее востребованные:

Привязка к CRM задаётся префиксами: "UF_CRM_TASK": ["D_15", "L_7"] — где D_ сделка, L_ лид, C_ контакт, CO_ компания.

tasks.task.update: изменение задачи

Метод tasks.task.update принимает taskId и объект fields только с изменяемыми полями. Передавать всю задачу целиком не нужно.

{ "taskId": 512, "fields": { "DEADLINE": "2026-07-25T18:00:00+03:00", "RESPONSIBLE_ID": 9 } }

Смена исполнителя, перенос дедлайна, добавление наблюдателей — всё через один метод. Для управления жизненным циклом статуса есть отдельные удобные методы:

• tasks.task.start — взять в работу;
• tasks.task.complete — завершить;
• tasks.task.renew — вернуть в работу;
• tasks.task.defer — отложить;
• tasks.task.delegate — делегировать другому исполнителю.

Сроки, даты и часовые пояса

Все даты в задачах — DEADLINE, START_DATE_PLAN, END_DATE_PLAN — принимаются в формате ISO 8601 с указанием смещения пояса, например 2026-07-22T18:00:00+03:00.

Планируемые трудозатраты задаются в секундах через TIME_ESTIMATE. Флаг ALLOW_TIME_TRACKING со значением Y включает учёт рабочего времени по задаче.

Связанные сущности при создании

За один вызов tasks.task.add можно не только создать задачу, но и подготовить сопутствующие данные, хотя чек-листы и файлы обычно добавляют отдельными вызовами. Практичная последовательность интеграции:

1. Создать задачу через tasks.task.add, получить id;
2. Добавить пункты чек-листа методом task.checklistitem.add;
3. Прикрепить файлы через tasks.task.files.attach (файл заранее загружается в диск);
4. При необходимости оставить комментарий task.commentitem.add.

Такой порядок гарантирует, что все дочерние сущности привязаны к уже существующему ID и не потеряются при ошибке на любом из шагов.

Типичные ошибки и лимиты

При массовой постановке задач учитывайте ограничения REST и логику прав доступа.

• Права. Ставить задачу можно только тем пользователям, к которым у аккаунта интеграции есть доступ; иначе вернётся ошибка доступа.
• Несуществующий RESPONSIBLE_ID. Метод вернёт ошибку — предварительно проверяйте пользователей через user.get.
• Лимит частоты. REST ограничивает число запросов в секунду; при пакетной загрузке используйте batch — до 50 команд в одном запросе.

Пакетная постановка через batch радикально снижает число обращений и ускоряет импорт. Ответы каждой команды доступны по её ключу в result.

Итог

Связка tasks.task.add и tasks.task.update покрывает создание и любое изменение задач: исполнители, сроки, приоритеты, привязка к CRM и проектам. Для смены статусов предпочтительны специализированные методы, для массовой загрузки — batch. Главные риски — часовые пояса в датах и права доступа аккаунта интеграции.

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