lists.element.get в Битрикс24: как читать данные из универсальных списков

lists.element.get в Битрикс24 - метод REST API, которым я читаю данные из универсальных списков: заявки, реестры, кастомные каталоги, всё, что заказчик когда-то сделал через модуль «Списки» вместо полноценного инфоблока или CRM. На практике с ним сталкиваюсь при интеграциях: нужно вытащить строки списка в n8n, отдать данные в Telegram-бота на aiogram или синхронизировать с внешней базой заказчика. Разберу параметры метода, как найти нужный IBLOCK_ID и на что обычно натыкаются при первом запросе.

Что такое универсальные списки и зачем нужен lists.element.get

Модуль «Универсальные списки» в Битрикс24 - упрощённая версия инфоблоков, доступная без модуля «Информационные блоки». Заказчики заводят там реестры договоров, заявки на доставку, списки объектов недвижимости, чек-листы для отдела продаж. С точки зрения REST API список тоже инфоблок, просто с типом IBLOCK_TYPE_ID равным lists, и элементы списка читаются отдельным методом lists.element.get, а не общими методами для CRM-сущностей.

Метод отдаёт массив элементов списка вместе со значениями пользовательских полей. Использую его в трёх сценариях на практике: выгрузка данных для отчёта во внешнюю систему, синхронизация справочника между Битрикс24 и сайтом на Tilda или WordPress, и связка с n8n, когда нужно раз в час забирать новые строки и класть их в другую CRM или таблицу. Если список нужно не просто прочитать, а завязать на бизнес-процессы, уведомления в мессенджер и внешние сервисы, обычно проще сразу заказать автоматизацию процессов и интеграций, чем дособирать логику самостоятельно поверх голого REST API.

Как узнать IBLOCK_ID нужного списка

Прежде чем звать lists.element.get, нужен числовой ID конкретного списка, в интерфейсе Битрикс24 он не виден напрямую. Получаю его через lists.get с указанием типа инфоблока:

curl -X POST 
  https://yourportal.bitrix24.ru/rest/1/webhook_code/lists.get 
  -H "Content-Type: application/json" 
  -d '{"IBLOCK_TYPE_ID":"lists"}'

Метод возвращает массив со всеми списками нужного типа, у каждого элемента есть поле ID, это и есть искомый IBLOCK_ID. Для стандартных пользовательских списков IBLOCK_TYPE_ID почти всегда lists, для списков, созданных через бизнес-процессы или CRM-сущности, тип может отличаться, это стоит проверить отдельным запросом lists.get без фильтра по типу.

Синтаксис и параметры метода lists.element.get

У метода шесть параметров, три из них нужны почти всегда, три - для фильтрации выборки.

Для расшифровки кодов свойств вроде PROPERTY_45 в человекочитаемые названия отдельно вызываю lists.field.get с теми же IBLOCK_TYPE_ID и IBLOCK_ID, метод возвращает список полей с их кодами, типами и подписями. Без этого шага разобрать ответ lists.element.get на глаз почти нереально, особенно если в списке двадцать пользовательских полей.

Пример запроса и разбор ответа

Рабочий запрос через входящий вебхук выглядит так:

curl -X POST 
  https://yourportal.bitrix24.ru/rest/1/webhook_code/lists.element.get 
  -H "Content-Type: application/json" 
  -d '{
    "IBLOCK_TYPE_ID": "lists",
    "IBLOCK_ID": "7",
    "FILTER": {"PROPERTY_47": "В обработке"},
    "SORT": "ID",
    "ORDER": "DESC"
  }'

Ответ приходит в таком виде:

{
  "result": [
    {
      "ID": "142",
      "NAME": "Заявка №142",
      "CREATED_BY": "1",
      "DATE_CREATE": "01.09.2026 10:14:00",
      "PROPERTY_VALUES": {
        "45": "Иван Петров",
        "46": "+79261234567",
        "47": "В обработке"
      }
    }
  ],
  "time": { "start": 1756713240, "finish": 1756713240 }
}

Каждый элемент содержит стандартные поля инфоблочного элемента (ID, NAME, CREATED_BY, DATE_CREATE) и блок PROPERTY_VALUES, где ключи - это ID свойств из lists.field.get, а значения - то, что реально ввёл пользователь в форму списка. Если свойство множественное, например список тегов или несколько телефонов, значение приходит массивом, а не строкой, это часто ломает наивный парсинг на стороне интеграции, когда код ожидает строку и падает на первом же элементе с несколькими значениями.

Фильтрация, сортировка и постраничная выгрузка

FILTER принимает те же операторы, что и в обычных инфоблоках:

• точное совпадение - код поля без префикса;
• больше или меньше значения - символы больше и меньше перед кодом поля;
• поиск по подстроке - символ процента перед значением;
• отрицание условия - восклицательный знак перед кодом поля.

Чаще всего работаю с фильтром по дате создания и по значению статуса, если в списке есть поле-справочник со статусами заявки, например при выгрузке заявок на доставку через СДЭК, заведённых менеджерами вручную в список, а не в CRM.

SORT и ORDER задают поле и направление сортировки строкой, а не массивом, как в новых методах CRM, это единственная REST API-ветка в Битрикс24, где формат сортировки остался старым. Пагинация встроена автоматически: сервер отдаёт не больше 50 элементов за раз и в поле next присылает смещение для следующей страницы, я передаю его в параметр start при повторном запросе и повторяю, пока next не пропадёт из ответа.

Для списков на несколько тысяч строк разумнее не гонять запросы по одному, а собирать их в общий batch метод Битрикс24, до 50 команд за один HTTP-вызов. Это заметно снижает число обращений и бережёт дневной лимит, особенно если выгрузка запущена по расписанию в n8n.

Права доступа, лимиты и типичные ошибки

Самая частая ошибка на старте - ACCESS DENIED, хотя вебхук вроде рабочий: у входящего вебхука не включён скоуп lists, его нужно добавить отдельно в настройках, доступ к CRM или диску прав на списки не даёт. Вторая по частоте проблема - путаница между IBLOCK_ID списка и ID элемента CRM-сущности, это разные пространства идентификаторов, даже если оба выглядят как обычное целое число.

На облачном Битрикс24 действует лимит примерно 2 запроса в секунду на приложение. При постраничной выгрузке тысяч строк в лоб, без пауз между запросами, легко упереться в ограничение и получить обрезанные данные без явной ошибки в ответе. Здесь и выручает batch из предыдущего раздела вместе с небольшой паузой между пачками запросов.

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

Частые вопросы

Чем lists.element.get отличается от entity.item.get?

entity.item.get работает с CRM-сущностями (Smart Process Automation), а lists.element.get - именно с модулем «Универсальные списки». Ответы похожи по структуре, но это разные API с разными правами доступа и разным набором методов для чтения полей.

Можно ли получить один конкретный элемент, а не всю выборку?

Да, для этого передаю параметр ELEMENT_ID с числовым ID нужного элемента, остальные параметры фильтрации в этом случае можно не указывать. Метод вернёт массив из одного элемента либо пустой результат, если элемент удалён или указанный ID не существует.

Как узнать коды свойств списка без обращения к разработчику Битрикс24?

Через метод lists.field.get с теми же IBLOCK_TYPE_ID и IBLOCK_ID, что и в lists.element.get. Он возвращает все поля списка с их внутренними кодами и подписями, которые видит пользователь в интерфейсе, дальше эти коды используются и в FILTER, и при разборе PROPERTY_VALUES.

Почему запрос возвращает пустой result при существующих элементах в списке?

Обычно причина в неверном IBLOCK_ID, перепутанном со списком другого типа, в фильтре, который случайно не совпадает ни с одним значением, либо в правах доступа: у пользователя, от чьего имени работает вебхук, может не быть прав на просмотр конкретного списка в самом Битрикс24, а REST API эти права наследует напрямую.