REST: универсальные списки (lists)

Scope lists открывает доступ к универсальным спискам Битрикс24 — гибким справочникам на базе инфоблоков. Через REST создают списки, описывают поля, добавляют и фильтруют элементы. Это удобный способ хранить структурированные данные интеграции прямо на портале.

Что такое универсальные списки

Универсальные списки — это настраиваемые справочники и реестры: контрагенты, заявки, оборудование, номенклатура. Технически они опираются на инфоблоки, но управляются отдельным набором методов lists.*.

Ключевой параметр почти во всех вызовах — IBLOCK_TYPE_ID. Он определяет, где живёт список:

Создание списка

Список заводят методом lists.add. Обязательны IBLOCK_TYPE_ID, IBLOCK_CODE и FIELDS с названием:

lists.add(IBLOCK_TYPE_ID: "lists", IBLOCK_CODE: "suppliers", FIELDS: {NAME: "Поставщики", DESCRIPTION: "Реестр поставщиков"})

Ответ вернёт IBLOCK_ID — числовой идентификатор, который затем используется во всех операциях с полями и элементами. Прочие методы уровня списка:

• lists.get — получить список/списки по фильтру;
• lists.update — изменить настройки;
• lists.delete — удалить список целиком.

Параметр IBLOCK_CODE задаёт символьный код, по которому к списку удобно обращаться из кода интеграции, не завися от числового IBLOCK_ID, который на разных порталах будет разным. Это ключевой приём при переносе решения между тестовым и боевым порталами: код списка вы фиксируете заранее, а ID получаете динамически через lists.get. Для списков в рабочих группах дополнительно передают SOCNET_GROUP_ID, иначе список создастся не в той области видимости.

Поля списка

После создания списка описывают его поля — от строки до привязки к сотруднику. Метод lists.field.add:

lists.field.add(IBLOCK_TYPE_ID: "lists", IBLOCK_ID: 61, FIELDS: {NAME: "ИНН", TYPE: "S", IS_REQUIRED: "Y"})

Типы полей узнают через lists.field.type.get. Основные:

• S — строка, N — число, L — список значений;
• S:Date — дата, F — файл;
• S:employee — привязка к сотруднику, E — привязка к элементам другого инфоблока.

Элементы списка

Данные складываются в элементы. Добавление — lists.element.add, где в FIELDS смешивают системные и пользовательские поля:

lists.element.add(IBLOCK_TYPE_ID: "lists", IBLOCK_ID: 61, ELEMENT_CODE: "sup-001", FIELDS: {NAME: "ООО Ромашка", PROPERTY_123: "7701234567"})

• lists.element.get — выборка с FILTER, SELECT и сортировкой;
• lists.element.update — обновить элемент по ELEMENT_ID;
• lists.element.delete — удалить элемент.

При импорте из внешней системы удобно задавать собственный ELEMENT_CODE — так вы получаете стабильный внешний ключ и при повторной загрузке обновляете существующий элемент, а не плодите дубли. Логика «upsert» строится так: сначала lists.element.get с фильтром по коду, и если элемент найден — update, иначе add. Множественные значения свойства передают массивом, а привязку к элементам другого инфоблока (тип E) — идентификаторами связанных элементов.

Фильтрация и постраничность

Выборка lists.element.get поддерживает привычный синтаксис фильтров Битрикс24 с префиксами операторов:

lists.element.get(IBLOCK_TYPE_ID: "lists", IBLOCK_ID: 61, FILTER: {"%NAME": "Ромашка"}, ELEMENT_ORDER: {ID: "DESC"})

Фильтровать можно и по пользовательским свойствам, указывая их коды: FILTER: {"PROPERTY_123": "7701234567"}. Через SELECT ограничивают набор возвращаемых полей — это заметно ускоряет выборку на больших списках, ведь по умолчанию тянутся все свойства. Для отчётов и выгрузок комбинация точного фильтра, узкого SELECT и постраничного обхода даёт предсказуемую производительность даже на десятках тысяч элементов.

Списки с бизнес-процессами

Если задать IBLOCK_TYPE_ID = "bitrix_processes", список превращается в «Процессы» — к его элементам можно привязывать бизнес-процессы. Это связка scope lists и bizproc:

1. создаём список типа bitrix_processes;
2. элемент адресуется в БП как DOCUMENT_ID = ["lists","BizprocDocument","ID"];
3. процесс запускают через bizproc.workflow.start или автозапуском на создание элемента.

Так универсальные списки становятся полноценным реестром заявок с маршрутами согласования.

Практический пример: реестр заявок на закупку. Элемент создаётся при поступлении заявки из внешней формы, автозапуск процесса отправляет её на согласование руководителю, а по завершении процесс меняет статус элемента через действие в дизайнере. Всё это управляется двумя scope — lists для данных и bizproc для маршрута. Такой реестр читается и наружу: внешний портал показывает статус заявки, выбирая элементы через lists.element.get.

Итог

Scope lists — это гибкое хранилище структурированных данных прямо на портале: создаёте список, описываете поля любых типов, наполняете и фильтруете элементы. В связке с bizproc списки превращаются в реестры с бизнес-процессами. Главное — помнить про IBLOCK_TYPE_ID, коды полей PROPERTY_* и постраничную выборку.

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