Batch: пакетные запросы

batch — служебный метод REST API Битрикс24, который упаковывает до 50 обычных вызовов в один HTTP-запрос. Он экономит время на сетевых задержках и позволяет связывать команды между собой, подставляя результат одной в параметры другой.

Зачем нужен batch

Каждый вызов REST — это отдельный HTTP-запрос с TLS-рукопожатием, аутентификацией и разбором ответа. Когда интеграции нужно, например, создать сделку, добавить к ней товарные позиции и прикрепить дело, три последовательных запроса тратят три сетевых круга. Метод batch отправляет их одним пакетом, и портал выполняет команды по порядку на своей стороне.

Основные выгоды:

• Меньше сетевых задержек. Один round-trip вместо N.
• Экономия на лимите частоты. Сам вызов batch — это один запрос для ограничения «2 запроса в секунду», хотя внутри может быть до 50 команд.
• Связывание команд. Результат предыдущей команды доступен в параметрах следующей.

Синтаксис вызова

Метод принимает два параметра: halt (останавливать ли пакет при первой ошибке) и cmd — ассоциативный массив команд, где ключ — произвольное имя команды, а значение — строка вида метод?параметры в формате query string.

Пример тела запроса на POST /rest/1/xxxxx/batch.json:

{ "halt": 0, "cmd": { "deal": "crm.deal.add?fields[TITLE]=Заявка&fields[TYPE_ID]=SALE", "contacts": "crm.contact.list?filter[TYPE_ID]=CLIENT&select[]=ID&select[]=NAME" } }

Параметры внутри строки команды кодируются так же, как обычная query string: вложенные массивы — через квадратные скобки (fields[TITLE], select[0]). На стороне клиента удобно собирать их через http_build_query() в PHP или аналог.

Разбор ответа

Ответ batch зеркалит структуру запроса. Внутри result лежат подмассивы, где ключи — имена ваших команд:

Обрабатывая ответ, всегда проверяйте result.result_error: при halt=0 одни команды могут отработать, а другие — упасть, и общий HTTP-статус останется 200.

Ссылки между командами

Ключевая возможность batch — подстановка результата одной команды в параметры следующей через выражение $result[имя_команды]. Команды выполняются в порядке следования в массиве cmd.

Создаём сделку и сразу добавляем к ней дело, используя ID новой сделки:

"cmd": { "new_deal": "crm.deal.add?fields[TITLE]=Тест", "activity": "crm.activity.add?fields[OWNER_ID]=$result[new_deal]&fields[OWNER_TYPE_ID]=2&fields[TYPE_ID]=4" }

Можно обращаться и к элементам массива-результата: $result[contacts][0][ID] возьмёт ID первого контакта из списка. Это удобно для сценариев «найти — и сразу использовать».

Параметр halt и стратегия ошибок

Параметр halt определяет поведение при ошибке в одной из команд:

• halt=1 — при первой же ошибке пакет останавливается, оставшиеся команды не выполняются. Подходит для транзакционных цепочек, где шаги зависят друг от друга.
• halt=0 — выполняются все команды независимо, ошибки собираются в result_error. Подходит для массовых независимых операций (например, обновить 50 контактов).

Учтите: batch не транзакция. Даже при halt=1 уже выполненные команды не откатываются. Если нужна атомарность, придётся продумывать компенсирующие действия вручную.

Лимит 50 и массовые операции

Один batch содержит не более 50 команд. Для обработки больших объёмов пакеты выстраивают в цикл: разбиваете набор на порции по 50 и отправляете последовательно, соблюдая частотный лимит.

1. Разбейте входные данные на чанки по 50 элементов.
2. Соберите cmd для каждого чанка.
3. Отправьте batch, разберите result_error.
4. Сделайте паузу, чтобы не упереться в лимит частоты, и повторите.

Частый приём — сочетать batch с пагинацией: первой командой запросить crm.deal.list, а последующими — обработать полученные записи. Но помните, что список внутри команды всё равно вернёт максимум одну страницу (50 записей), поэтому глубокую выборку организуют внешним циклом по start.

Полный пример сценария

Разберём типичную задачу: найти компанию по названию, создать сделку с привязкой к ней и сразу поставить задачу ответственному. Три зависимых шага укладываются в один batch с halt=1, потому что каждый следующий шаг опирается на результат предыдущего.

{ "halt": 1, "cmd": { "company": "crm.company.list?filter[%TITLE]=Ромашка&select[]=ID", "deal": "crm.deal.add?fields[TITLE]=Поставка&fields[COMPANY_ID]=$result[company][0][ID]", "task": "tasks.task.add?fields[TITLE]=Согласовать&fields[UF_CRM_TASK][0]=D_$result[deal]&fields[RESPONSIBLE_ID]=1" } }

Что здесь происходит по шагам:

1. Команда company ищет компанию по подстроке названия и возвращает список с ID.
2. Команда deal берёт ID первой найденной компании через $result[company][0][ID] и создаёт сделку.
3. Команда task привязывает задачу к новой сделке через префикс D_ и ID из $result[deal].

При halt=1, если компания не найдена и $result[company][0][ID] окажется пустым, стоит заранее решить: создавать сделку без привязки или прерывать сценарий. Такие развилки закладывают в логику клиента, разбирая result_error после ответа.

Итог

Batch — базовый инструмент оптимизации интеграций с Битрикс24: он сокращает число HTTP-запросов, связывает команды через $result и даёт контроль над обработкой ошибок через halt. Помните про потолок в 50 команд, про расход операционного лимита каждой вложенной командой и про то, что пакет не откатывается как транзакция.

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