REST API Битрикс24 предоставляет мощный инструмент для работы с задачами через HTTP-запросы. В этой статье мы разберем основные методы для получения и фильтрации задач, а также важные нюансы, которые помогут вам избежать ошибок.
Основные методы:
tasks.task.list: Получение списка задач с возможностью фильтрации и сортировки.tasks.task.get: Получение одной задачи по ID.tasks.task.getFields: Получение информации о полях задач (типы, названия, допустимые значения).
1. tasks.task.list: Получение списка задач
Этот метод позволяет получить список задач с гибкой настройкой фильтрации, сортировки и выбора полей.
Формат запроса:
GET сайт/rest/xxx/xxx/tasks.task.list.json?{параметры}Параметры запроса:
order: Массив для сортировки. Например,order[ID]=ASCдля сортировки по ID по возрастанию, илиorder[CREATED_DATE]=DESCдля сортировки по дате создания по убыванию. Доступные поля для сортировки можно получить черезtasks.task.getFields.filter: Массив для фильтрации. Здесь доступно множество вариантов:- По ID:
filter[>ID]=100(ID больше 100),filter[=ID]=50(ID равно 50),filter[<ID]=200(ID меньше 200),filter[>=ID]=150(ID больше или равно 150),filter[<=ID]=250(ID меньше или равно 250),filter[!ID]=300(ID не равно 300). - По названию:
filter[%TITLE]=тест(название содержит «тест»),filter[!%TITLE]=отчет(название не содержит «отчет»). - По статусу:
filter[STATUS]=2(статус равен 2 — «В работе»). Список статусов можно получить черезtasks.task.getFields. Используйтеfilter[REAL_STATUS], чтобы отфильтровать по реальному статусу задачи, исключая метастатусы (например, «Просрочена»). - По дате создания:
filter[>=CREATED_DATE]=2023-11-01T00:00:00%2B03:00(дата создания больше или равна 1 ноября 2023 года в часовом поясе +3). Важно: используйте формат ISO 8601 и указывайте часовой пояс. - По дате изменения:
filter[<CHANGED_DATE]=2023-11-15T00:00:00%2B03:00(дата изменения меньше 15 ноября 2023 года в часовом поясе +3). - По группе:
filter[GROUP_ID]=5(задачи из группы с ID 5). - По ответственному:
filter[RESPONSIBLE_ID]=1(задачи, где ответственный — пользователь с ID 1). - По участию:
filter[MEMBER]=3(задачи, где пользователь с ID 3 участвует в любом качестве).filter[DOER]=7— задачи, где пользователь с ID 7 — ответственный или соисполнитель. - По тэгам:
filter[TAG]=проект_альфа(задачи с тегом «проект_альфа»). Можно указывать несколько тегов через запятую. ::SUBFILTER-PARAMS: Позволяет фильтровать по специальным параметрам.filter[::SUBFILTER-PARAMS][FAVORITE]=Y(задачи в избранном),filter[::SUBFILTER-PARAMS][VIEWED]=1(просмотренные). Можно фильтровать задачи без дедлайна:filter[::SUBFILTER-PARAMS][DEADLINE]=(пустое значение означает «без дедлайна»).
- По ID:
select: Массив для выбора полей. Например,select[0]=IDиselect[1]=TITLEвернут только ID и название задачи.select[0]=*вернет все поля. Важно: всегда указывайтеselect, даже если нужны все поля, так как список полей по умолчанию может меняться.start: Сколько записей пропустить. Используется для пагинации. Значение должно быть кратно 50.start=-1отключает подсчет общего количества задач, что полезно для больших списков.limit: Максимальное количество записей в ответе. По умолчанию 50.
Пример запроса:
GET сайт/rest/xxx/xxx/tasks.task.list.json?filter[GROUP_ID]=1&filter[>STATUS]=1&order[ID]=DESC&select[0]=*&start=0Этот запрос вернет первые 50 задач из группы с ID 1, у которых статус больше 1, отсортированные по ID по убыванию.
2. tasks.task.get: Получение одной задачи
Этот метод позволяет получить одну задачу по ее ID.
Формат запроса:
GET сайт/rest/xxx/xxx/tasks.task.get.json?taskId={ID задачи}&select[0]=*Параметры запроса:
taskId: ID задачи.select: Массив для выбора полей.select[0]=*вернет все поля.
Пример запроса:
сайт/rest/xxx/xxx/tasks.task.get.json?taskId=123&select[0]=*3. tasks.task.getFields: Получение информации о полях
Этот метод возвращает информацию о доступных полях задач, их типах, названиях и допустимых значениях. Это очень полезно для построения фильтров и выбора полей в запросах.
Формат запроса:
GET сайт/rest/xxx/xxx/tasks.task.getFields.jsonРабота с датами:
При фильтрации по датам используйте формат ISO 8601 (YYYY-MM-DDTHH:MM:SS±HH:MM) с обязательным указанием часового пояса. Например, 2023-11-20T10:00:00+03:00. Специальные символы в URL нужно экранировать. Например, + заменяется на %2B.
Работа с большими списками:
REST API Битрикс24 возвращает данные постранично. Для работы с большими списками используйте параметры start и limit. start=-1 отключает подсчет общего количества, что снижает нагрузку на сервер. Получайте данные порциями по 50 записей, увеличивая start с каждым запросом.
Обработка ошибок:
REST API Битрикс24 возвращает ответы в формате JSON. В случае ошибки, в ответе будет поле error с кодом и описанием ошибки. Всегда проверяйте наличие этого поля.
Дополнительные возможности:
- Пользовательские поля: Можно фильтровать и выбирать пользовательские поля задач (UF_*).
- Связанные сущности: Можно получать информацию о связанных сущностях (например, о создателе или ответственном) через
select.
С помощью этих методов и рекомендаций вы сможете эффективно работать с задачами в Битрикс24 через REST API. Не забывайте изучать документацию для получения полной информации о возможностях API.
4. Работа с пользовательскими полями (UF_*)
Вы можете фильтровать и выбирать пользовательские поля задач (UF_*) в REST запросах. Для этого используйте имя пользовательского поля в параметрах filter и select.
Пример:
сайт/rest/xxx/xxx/tasks.task.list.json?filter[UF_CRM_TASK]=123&select[0]=*&select[1]=UF_CRM_TASKЭтот запрос вернет все задачи, у которых в пользовательском поле UF_CRM_TASK указано значение 123, и включит само поле UF_CRM_TASK в ответ.
Важно:
- Тип данных пользовательского поля должен соответствовать типу значения в фильтре. Например, для числового поля используйте числовое значение в фильтре, для строкового — строковое.
- Для получения списка пользовательских полей и их типов используйте метод
tasks.task.getFields.
5. Дополнительные фильтры (::SUBFILTER-…)
Битрикс24 REST API предоставляет специальные фильтры, начинающиеся с ::SUBFILTER-. Мы уже рассмотрели ::SUBFILTER-PARAMS выше. Есть и другие:
::SUBFILTER-ROLEID: Фильтрация по роли пользователя в задаче. Например,filter[::SUBFILTER-ROLEID][=CREATED_BY]=1вернет задачи, созданные пользователем с ID 1. Другие роли:=RESPONSIBLE_ID(ответственный),=ACCOMPLICE(соисполнитель),=AUDITOR(наблюдатель).::SUBFILTER-PROBLEM: Фильтрация по «проблемам» с задачей. Например,filter[::SUBFILTER-PROBLEM][VIEWED]=0вернет непросмотренные задачи. Другой пример:filter[::SUBFILTER-PROBLEM][STATUS]=-1вернет просроченные задачи.::SUBFILTER-BINDINGS: Этот подфильтр используется для расширенного поиска задач. С помощью него можно отбирать задачи по привязкам к CRM, почте, календарю и другим сущностям.
6. Получение данных о связанных сущностях
Вы можете получать информацию о связанных с задачей сущностях (например, о создателе или ответственном) непосредственно в запросе tasks.task.list, не делая дополнительных запросов. Для этого используйте select с указанием полей связанной сущности.
Пример:
сайт/rest/xxx/xxx/tasks.task.list.json?select[0]=*&select[1]=CREATED_BY_USER.NAME&select[2]=RESPONSIBLE.WORK_POSITIONЭтот запрос вернет все поля задачи, а также имя создателя (CREATED_BY_USER.NAME) и должность ответственного (RESPONSIBLE.WORK_POSITION). Для получения полного списка доступных полей связанных сущностей, снова используйте tasks.task.getFields.
7. Формат ответа
Ответ tasks.task.list содержит следующие поля:
result: Массив с результатами.tasks: Массив задач. Каждая задача — ассоциативный массив с выбранными полями.
total: Общее количество задач, удовлетворяющих фильтру (еслиstartне равен -1). Обратите внимание:totalможет отсутствовать в ответе при использовании постраничной навигации соstart=-1. В таком случае для получения общего количества задач необходимо выполнить отдельный запрос.next: Значениеstartдля следующей страницы результатов (если есть еще задачи). Как иtotal,nextможет отсутствовать при использованииstart=-1. Для корректной пагинации в таком случае используйте свой счетчикstartна клиенте и увеличивайте его наlimitс каждым запросом, пока не перестанете получать данные.
8. Пример комплексного запроса
сайт/rest/xxx/xxx/tasks.task.list?filter[GROUP_ID]=10&filter[::SUBFILTER-ROLEID][=RESPONSIBLE_ID]=5&filter[>CREATED_DATE]=2023-10-01T00:00:00%2B03:00&select[0]=*&select[1]=CREATED_BY_USER.NAME&order[DEADLINE]=ASC&start=0Этот запрос вернет первые 50 задач из группы 10, где ответственный — пользователь 5, созданные после 1 октября 2023 года (в часовом поясе +3), отсортированные по дедлайну по возрастанию. В ответе будут все поля задачи, а также имя создателя.
Заключение
Мы рассмотрели основные методы и параметры REST API Битрикс24 для работы с задачами. Используя эти знания, вы сможете создавать гибкие запросы для получения и фильтрации задач, интегрировать Битрикс24 с другими системами и автоматизировать свою работу. Не забывайте про документацию API и возможности тестирования запросов в интерфейсе Битрикс24.
