Bitrix24 упростил интеграции: в REST 3.0 появился «batch» с передачей данных между запросами

Когда CRM интегрируют с сайтом, телефонией или внутренними сервисами, чаще всего «болит» не логика, а количество обращений к API: сначала получить данные, потом уточнить поля, затем обновить карточку — и так по кругу. В REST 3.0 появилась возможность упаковать несколько вызовов в один запрос и выполнить их как единый сценарий.

Что добавили

В REST 3.0 описан метод batch, который выполняет несколько запросов за один HTTP‑вызов. Он поддерживает два режима:

• независимые вызовы — когда вы просто хотите «пачкой» получить/изменить данные;
• последовательное выполнение — когда следующий шаг использует результат предыдущего.

Почему это полезно не только разработчикам

Меньше запросов — обычно меньше задержек. Это заметно в реальных сценариях:

• быстрее открываются виджеты и формы (особенно в мобильных сетях), если интеграция не делает 5–10 последовательных обращений;
• проще собирать «мини‑процессы» вокруг задач и CRM: получить сущность → обновить → подтянуть список связанных объектов;
• меньше шансов на ошибки из‑за частично выполненной цепочки, когда часть запросов успела пройти, а часть — нет.

Как это выглядит на практике

В REST 3.0 пакет передаётся как JSON‑массив подзапросов. У каждого элемента есть:

• method — имя метода, который нужно вызвать;
• query — параметры этого метода (если параметров нет, передаётся пустой объект {});
• as (опционально) — имя результата, чтобы на него удобно ссылаться дальше.

Передача результата между шагами: $ref и $refArray

Главная «фишка» последовательного сценария — возможность подставлять данные из прошлого шага в следующий:

• $ref — передаёт одно значение по пути вида alias.field (где alias — имя из as, или индекс подзапроса).
• $refArray — собирает массив значений одного поля из списка результатов и передаёт дальше.

Например, можно сначала получить задачу, затем взять её id и обновить заголовок — без отдельного запроса на стороне клиента.

Пример сценария (упрощённо)

Ниже идея в двух словах: сначала читаем две задачи, потом обновляем одну из них, затем снова запрашиваем список — всё одним вызовом.

[
  {"method":"tasks.task.get","query":{"id":101,"select":["id","title"]},"as":"first_task"},
  {"method":"tasks.task.get","query":{"id":102,"select":["id","title"]}},
  {"method":"tasks.task.update","query":{"id":{"$ref":"first_task.id"},"fields":{"title":"Updated task"}}}
]

При этом ответы приходят массивом в порядке выполнения подзапросов: где-то будет item, где-то items, а для операций — булево result (в зависимости от того, что возвращает конкретный метод).

Что важно учесть

• Формат вызова: в REST 3.0 используется endpoint с сегментом /rest/api/... для batch.
• Старый стиль команд не подходит: формат с объектом cmd и строками вида method?param=value в REST 3.0 не поддерживается — подзапросы передаются только JSON‑массивом объектов.
• Ошибки нужно обрабатывать аккуратно: при ошибке в самом batch или во вложенном вызове возвращается объект error на верхнем уровне, поэтому стоит проверять HTTP‑статус и код ошибки.

Параллельно в обновлениях документации за 16 сентября также появились новые материалы по типам полей и работе с привязками (включая справочники CRM и инфоблоки), чтобы интеграции было проще собирать «как конструктор» из понятных блоков.

Источник: Bitrix24 REST API Docs