tasks.task — основное семейство REST-методов Битрикс24 для работы с задачами. Через него приложение или вебхук создаёт задачи, читает их списками, меняет статусы и управляет полным жизненным циклом без доступа к интерфейсу портала.
Что такое семейство tasks.task
Метод входит в скоуп task и работает поверх нового ядра задач Битрикс24. В отличие от старых процедур task.item.*, семейство tasks.task.* возвращает данные в едином формате и поддерживает выборку конкретных полей через параметр select.
Все вызовы идут по общей схеме REST. Для вебхука адрес выглядит так:
https://portal.bitrix24.ru/rest/1/xxxxxxxx/tasks.task.list.json
Для приложения — https://portal.bitrix24.ru/rest/tasks.task.add.json?auth=ACCESS_TOKEN. Тело передаётся в формате JSON или как обычные POST-поля.
Список методов семейства
Семейство покрывает и CRUD, и действия над задачей. Основные методы:
| Метод | Назначение |
|---|---|
tasks.task.add | создать задачу |
tasks.task.get | получить одну задачу по ID |
tasks.task.list | выборка списком с фильтром и сортировкой |
tasks.task.update | изменить поля задачи |
tasks.task.delete | удалить задачу |
tasks.task.complete | завершить |
tasks.task.start / pause / defer | управление ходом выполнения |
tasks.task.delegate | делегировать ответственного |
tasks.task.getFields | список доступных полей задачи |
tasks.task.counters.get | счётчики (просрочено, новые и т.п.) |
Прежде чем строить фильтры, полезно вызвать tasks.task.getFields — метод вернёт актуальный набор полей именно вашего портала, включая пользовательские (UF_).
Создание задачи: tasks.task.add
Все свойства новой задачи передаются внутри объекта fields. Минимально обязательны заголовок и ответственный:
POST /rest/1/xxxx/tasks.task.add.json
{"fields":{"TITLE":"Подготовить КП","RESPONSIBLE_ID":17,"DEADLINE":"2026-07-20T18:00:00","PRIORITY":2,"GROUP_ID":5}}
Часто используемые поля:
TITLE— название (обязательно);RESPONSIBLE_ID— ID ответственного (обязательно);DESCRIPTION— описание, поддерживает BB-код;DEADLINE— крайний срок в формате ISO 8601;ACCOMPLICESиAUDITORS— массивы ID соисполнителей и наблюдателей;GROUP_ID— привязка к рабочей группе или проекту;PARENT_ID— родительская задача,DEPENDS_ON— зависимости для диаграммы Ганта.
В ответе возвращается объект task с присвоенным id. Обратите внимание: в ответах tasks.task.* ключи полей приходят в нижнем регистре (id, responsibleId), тогда как на вход поля принимаются в верхнем.
Выборка списком, select и пагинация
tasks.task.list принимает order, filter, select и start. Пример: активные задачи ответственного, отсортированные по дедлайну:
{"order":{"DEADLINE":"asc"},"filter":{"RESPONSIBLE_ID":17,"<REAL_STATUS":5},"select":["ID","TITLE","DEADLINE","STATUS"]}
В фильтрах доступны префиксы операторов: >, <, >=, ! (не равно), % (подстрока). Метод возвращает не более 50 задач за вызов; далее листаем через start, ориентируясь на поле next в ответе.
total не нужен, передавайте start: -1 — это отключает подсчёт общего количества и ускоряет тяжёлые выборки.Статусы и жизненный цикл
Статус хранится в поле STATUS (и вычисляемом REAL_STATUS). Значения:
| Код | Статус |
|---|---|
| 2 | Ждёт выполнения |
| 3 | Выполняется |
| 4 | Ждёт контроля (условно завершена) |
| 5 | Завершена |
| 6 | Отложена |
| 7 | Отклонена |
Менять статус напрямую через update не следует: используйте действия. tasks.task.start переводит в «Выполняется», tasks.task.complete — завершает, tasks.task.defer — откладывает, tasks.task.approve и tasks.task.disapprove — принимают или возвращают на доработку задачи с контролем. Такой подход корректно инициирует уведомления и проверки прав.
Пакетная обработка и производительность
При массовой синхронизации задач применяйте метод batch: до 50 команд в одном HTTP-запросе, с возможностью ссылаться на результат предыдущей команды через $result[...].
{"halt":0,"cmd":{"t1":"tasks.task.add?fields[TITLE]=A&fields[RESPONSIBLE_ID]=1","t2":"tasks.task.add?fields[TITLE]=B&fields[RESPONSIBLE_ID]=1"}}
start: -1 — главные инструменты, чтобы не упереться в QUERY_LIMIT_EXCEEDED при выгрузке тысяч задач.Итог
Семейство tasks.task.* закрывает весь жизненный цикл задачи: создание, чтение с гибкими фильтрами и select, обновление и корректные переходы статусов через методы-действия. Ключ к устойчивой интеграции — вызывать getFields перед фильтрацией, использовать batch и уважать лимиты API.
Если нужно связать задачи Битрикс24 с внешней системой, учётной программой или собственным сервисом, мы проектируем такие интеграции под ключ — с обработкой ошибок, очередями и мониторингом. Помогаем и с архитектурой обмена, и с поддержкой уже работающих решений.
Частые вопросы
Чем tasks.task отличается от старого task.item?
tasks.task — актуальное семейство на новом ядре задач. Оно поддерживает выбор полей через select, единый формат ответа и методы-действия. task.item.* считается устаревшим и в новых интеграциях не рекомендуется.
Как задать несколько соисполнителей?
Передайте массив ID в поле ACCOMPLICES, например fields[ACCOMPLICES][]=5 и fields[ACCOMPLICES][]=8. Наблюдатели указываются так же в поле AUDITORS.
Почему поля в ответе в нижнем регистре?
Методы tasks.task.* возвращают объект задачи с ключами в нижнем регистре (id, responsibleId), а на вход принимают поля в верхнем регистре. Это нормальное поведение, учитывайте его при разборе ответа.
Как получить только просроченные задачи?
Отфильтруйте по дедлайну и статусу: filter с условием меньше текущей даты по DEADLINE и REAL_STATUS меньше 5, чтобы исключить завершённые. Либо используйте tasks.task.counters.get для готовых счётчиков.
Можно ли создать задачу от имени другого сотрудника?
Поле CREATED_BY задаёт постановщика, но фактические права проверяются по токену вызова. Вебхук работает с правами создавшего его пользователя, поэтому для постановки за других нужен пользователь с достаточными правами.
Как менять статус задачи корректно?
Не пишите STATUS напрямую через update. Используйте действия: start, pause, complete, defer, approve, disapprove. Так срабатывают уведомления и бизнес-логика проверки.
Сколько задач возвращает tasks.task.list за раз?
Максимум 50 элементов. Для следующей страницы передавайте параметр start со значением из поля next предыдущего ответа.
Какой скоуп нужен для работы с задачами?
Скоуп task. Его нужно указать при создании приложения или отметить в правах вебхука, иначе методы вернут ошибку доступа.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.