В середине сентября 2026 года Битрикс24 заметно расширил REST API. 16 сентября в документации появилось описание пакетных запросов batch 3.0 с передачей результатов между подзапросами, а 17 сентября появилась группа методов biconnector.table.* для BI-Конструктора. Обе даты зафиксированы в журнале изменений REST API Битрикс24.
Звучит как новость для программистов, и формально это так. Но последствия у неё вполне бизнесовые: часть болячек, из-за которых компании годами живут с дублями сделок, медленными выгрузками и ручными отчётами в Excel, теперь лечится на уровне платформы, а не костылями подрядчика.
Что именно изменилось 16 и 17 сентября 2026 года
Изменения касаются двух разных участков API, и связывает их общая линия: Битрикс24 достраивает новую версию интерфейса, REST 3.0. Запись от 16 сентября описывает, как выполнять пакет запросов в REST 3.0: подзапросы идут последовательно, а результат одного можно подставить в параметры следующего через конструкции $ref и $refArray. Запись от 17 сентября добавляет методы biconnector.table.*: создание таблицы, обновление описания, получение по идентификатору, список с фильтром, удаление, обновление состава колонок и описание полей.
Для компании, у которой Битрикс24 уже связан с сайтом, учётной системой и рекламными кабинетами, это два разных сигнала. Первый в том, что интеграции станут быстрее и предсказуемее. Второй в том, что аналитику в портале можно наполнять внешними данными программно, без того чтобы каждый раз звать разработчика к интерфейсу.
Ни один из старых методов при этом не отключили. В документации прямо сказано, что обе версии REST работают параллельно и планов выключить прежние вызовы нет. Так что паниковать и срочно всё переписывать не нужно, но понимать, куда движется платформа, стоит уже сейчас.
Чем REST 3.0 отличается от привычного REST
REST 3.0 — это новая версия программного интерфейса Битрикс24 с единым форматом ответа, выборкой связанных данных одним запросом и защитой от повторов. Она живёт по другому адресу: вместо /rest/{id}/{вебхук}/{метод} используется /rest/api/{id}/{вебхук}/{метод}. Разница в одном сегменте /api/, и именно он определяет, какая версия обработает вызов. Забыли его, и сработает старый интерфейс.
Главное практическое отличие тут в предсказуемости. Раньше разные модули возвращали данные по-своему, и каждая интеграция обрастала обработчиками под конкретный метод. Теперь успешный ответ всегда содержит result и time, а ошибка содержит code, message и, при необходимости, блок validation с деталями по полям.
| Что сравниваем | Прежний REST | REST 3.0 |
|---|---|---|
| Адрес вызова | /rest/{id}/{вебхук}/{метод} |
/rest/api/{id}/{вебхук}/{метод} |
| Формат ответа | Различается по модулям | Единый для всех методов |
| Связанные данные | Отдельными запросами | Точечная нотация в select |
| Защита от дублей | На стороне интеграции | Заголовок Idempotency-Key |
| Описание методов | Статичная документация | OpenAPI по вашему порталу |
| Покрытие методов | Полное | Переведены не все |
Последняя строка таблицы важнее остальных, когда планируешь работы. На новую версию переведены не все методы, и актуальный перечень выдаёт сама платформа: метод rest.documentation.openapi возвращает спецификацию с составом методов, параметров и схем именно для вашего портала. Это удобнее любых сторонних списков, потому что учитывает установленные приложения и права.
Подробности по адресам, форматам и ограничениям собраны в обзоре REST 3.0 в документации Битрикс24.
Как Idempotency-Key убирает дубли заявок
Idempotency-Key — это заголовок запроса с уникальным идентификатором операции, по которому Битрикс24 отличает повтор от новой команды. Если запрос с таким ключом уже отработал успешно, портал не создаёт вторую сущность, а возвращает сохранённый ответ и помечает его заголовком Idempotent-Replayed: true. Кеш успешного ответа живёт сутки.
Дубли лидов и сделок остаются одной из самых частых жалоб, с которыми к нам приходят на сопровождение. Механика почти всегда одинаковая: форма на сайте отправила данные, ответ не дошёл из-за таймаута, скрипт повторил попытку, и в CRM легли две одинаковые заявки. Дальше два менеджера перезванивают одному человеку, воронка врёт, а конверсия считается по завышенной базе.
До появления идемпотентности эту задачу решали на стороне интеграции: хранили журнал отправок, сверяли телефон и почту, дедуплицировали ночным скриптом. Работало, но требовало кода и присмотра. Теперь достаточно генерировать ключ на стороне отправителя, и повтор перестаёт быть проблемой на уровне протокола.
Отдельно отметим момент, который легко упустить: ключ должен быть привязан к смыслу операции, а не к попытке. Если генерировать новый идентификатор на каждый ретрай, защита не сработает вовсе. На проектах B2BPRO.KZ мы чаще всего привязываем ключ к идентификатору записи в источнике: номеру заявки на сайте, идентификатору документа в учётной системе, номеру диалога в мессенджере.
Сколько запросов помещается в один пакет и зачем это нужно
Один пакет batch вмещает не более 50 подзапросов. Всё, что сверх лимита, возвращает ошибку ERROR_BATCH_LENGTH_EXCEEDED, причём для каждого лишнего запроса отдельно. Вкладывать batch в batch нельзя: вложенность запрещена явно.
Пакетные запросы существовали и раньше, но в REST 3.0 у них другой формат и более аккуратная передача данных между шагами. Логика та же: вместо пятидесяти отдельных обращений к порталу интеграция делает одно. Для выгрузки справочника номенклатуры или синхронизации остатков разница получается кратной по времени и по нагрузке на портал.
Параметр halt определяет поведение при ошибке. По умолчанию halt = 0: выполняются все подзапросы, а ошибки копятся в result_error. При halt = 1 выполнение останавливается на первой ошибке, и следующие команды не отрабатывают.
Выбор между двумя режимами — это бизнес-решение, а не техническая мелочь. Вот как он выглядит на ночной синхронизации остатков склада:
- Если в пакете идут независимые обновления карточек товаров, логичен режим без остановки: одна сбойная карточка не должна блокировать остальные 49.
- Если пакет создаёт сделку, затем товарные позиции к ней, затем задачу ответственному, нужна остановка на первой ошибке. Иначе в CRM останется сделка без позиций, и её придётся вычищать руками.
- Если пакет переносит деньги, документы или статусы, к остановке добавляют идемпотентный ключ, чтобы повторный прогон не удвоил результат.
Полное описание правил передачи результатов между подзапросами и ограничений пакета собрано в справке Битрикс24 о пакетных запросах batch.
Что дают методы BI-Конструктора
Методы biconnector.* позволяют программно подключать внешние источники данных к аналитике Битрикс24 и описывать их структуру. Модуль biconnector отвечает за подключение внешних источников и их адаптацию для раздела «Рабочее место аналитика». То есть за то, чтобы в отчёты попадали не только данные CRM, но и цифры из соседних систем.
Устроено это тремя уровнями:
- Коннекторы (
biconnector.connector.*) описывают правила интеграции с внешней системой. Коннектор хранит четыре обязательных адреса: проверка подключения, список таблиц, описание таблицы и получение данных. Один коннектор обслуживает несколько источников. - Источники (
biconnector.source.*) — это рабочие подключения, созданные на базе коннектора. В них лежат параметры авторизации, а связь с коннектором идёт черезconnectorId. - Таблицы (
biconnector.table.*) описывают структуру данных для аналитики. С источником они связаны черезsourceId, и из одного источника можно собрать несколько таблиц.
Именно третий уровень и открыли 17 сентября. Раньше за работу с наборами данных отвечала группа biconnector.dataset.*; она признана устаревшей. Пять методов из семи меняют только название, но dataset.add и dataset.delete ведут себя иначе, и это стоит проверить, если у вас уже есть интеграция на старых вызовах.
Ещё одна деталь, о которую спотыкаются при первой настройке: для выполнения этих методов пользователю нужны сразу два права: «Доступ к BI-конструктору» и «Доступ к рабочему месту аналитика». Одного мало. Разграничение описано в документации методов biconnector.
Что это меняет для компаний в Казахстане
Практический эффект сильнее всего чувствуют компании, у которых данные живут в нескольких системах сразу. В Казахстане это почти норма: продажи в Битрикс24, склад и деньги в учётной системе, переписка в мессенджерах, реклама в двух-трёх кабинетах, а отчёт собственнику собирается в таблице по понедельникам.
С открытым API BI-Конструктора этот отчёт можно собирать автоматически, внутри портала. Схема получается такой: внешняя система отдаёт данные по описанным адресам, коннектор и источник настраиваются один раз, таблицы создаются и обновляются вызовами biconnector.table.*, а дальше цифры доступны в аналитике наравне с данными CRM. Ручная сверка выгрузок из этого процесса уходит.
Второй эффект касается стоимости сопровождения. Интеграция, построенная на предсказуемом формате ответа и идемпотентных вызовах, реже ломается и быстрее чинится. Разница заметна не в первый месяц, а через полгода, когда перестаёт копиться очередь мелких правок. Если вы планируете внедрение и настройку Битрикс24 или переделку уже работающих интеграций, закладывать новую версию API в техзадание разумно именно сейчас, пока код пишется с нуля.
Третий момент касается тех, кто ведёт учёт в тенге и сдаёт отчётность по местным правилам. Данные по счетам, ЭСФ и документообороту чаще всего лежат вне Битрикс24. Возможность подтягивать их в аналитику портала без промежуточных файлов нужна не ради красоты дашборда, а ради того, чтобы руководитель видит выручку и дебиторку в одном окне и в одной валюте.
Как перевести интеграцию на REST 3.0
Переход делается частями, а не одним движением. Разумный порядок действий такой:
- Запросите
rest.documentation.openapiна своём портале и посмотрите, какие из используемых вами методов уже доступны в новой версии. - Соберите список текущих интеграций: сайт, учётная система, телефония, мессенджеры, самописные скрипты. Для каждой зафиксируйте, какие методы она вызывает и как часто.
- Начните с тех сценариев, где болит сильнее всего. Обычно это создание лидов и сделок из внешних источников. Добавьте
Idempotency-Keyи проверьте поведение при повторе. - Переведите массовые операции на пакетные запросы, соблюдая лимит в 50 подзапросов и осознанно выбрав режим
halt. - Уберите лишние обращения за связанными данными: там, где раньше шёл второй запрос за карточкой ответственного, используйте точечную нотацию в
select. - Прогоните всё на тестовом портале и только потом переносите на рабочий.
Отдельно про последний пункт. Тестировать интеграции на боевом портале плохо в любой версии API, но с пакетными запросами цена ошибки выше: один неверный пакет создаёт до пятидесяти лишних записей за раз.
Типичные ошибки при переходе
Самая частая ошибка: забыть сегмент /api/ в адресе и удивляться, почему ответ выглядит по-старому. Вызов уходит в прежнюю версию, отрабатывает штатно, и обнаруживается это позже, когда обработчик ответа не находит ожидаемых полей.
Вторая: переписывать всё сразу. Обе версии работают параллельно, и смысла в тотальной миграции нет. Переводите то, что даёт выигрыш: массовые операции, точки, где возникают дубли, места с лишними запросами.
Третья: игнорировать права доступа при работе с BI-Конструктором. Метод возвращает отказ, разработчик ищет проблему в коде, а дело в том, что у пользователя вебхука нет одного из двух необходимых прав.
Четвёртая: считать, что идемпотентность решает проблему дублей целиком. Она защищает от повторной отправки одной и той же операции, но не от ситуации, когда клиент дважды заполнил форму или написал вам и в WhatsApp, и в Telegram. Дедупликация по контактным данным всё равно нужна.
Пятая: вкладывать пакет в пакет. Запрет прямой, но соблазн велик, когда логика сложная. Разбивайте на последовательные пакеты и передавайте результаты между ними на стороне своего кода.
Как это выглядит на практике
Проще всего понять выигрыш на конкретном сценарии. Возьмём иллюстративный пример: оптовую компанию из Алматы, которая продаёт оборудование и ведёт сделки в Битрикс24, а склад и взаиморасчёты в отдельной учётной системе.
До перехода картина обычная. Ночью скрипт обходит справочник товаров и по одному обновляет карточки в портале: около тысячи обращений подряд, каждое со своим временем ответа. Утром менеджер открывает сделку и не видит остатка, приходится смотреть во второй системе. Отчёт по марже собирает финансист: выгружает продажи из портала, остатки и себестоимость из учётной системы, сводит в таблице. На это уходит день в неделю.
После перехода тот же процесс выглядит иначе. Обновление справочника идёт пакетами по 50 позиций, и обращений к порталу становится в полсотни раз меньше, и ночное окно перестаёт растягиваться. Создание сделок из заявок сайта помечается идемпотентным ключом, и повторная отправка при обрыве связи больше не порождает вторую сделку. Себестоимость и остатки подключаются к аналитике как внешний источник через коннектор, а таблицы под них создаются и обновляются вызовами biconnector.table.*. Отчёт по марже перестаёт быть ручной работой и становится обычным дашбордом в портале.
Оговорка: это иллюстрация, а не описание готовой коробочной функции. Внешняя система должна отдавать данные по четырём адресам, которых требует коннектор, и кто-то должен эти адреса реализовать. Если учётная система такого интерфейса не имеет, между ней и порталом всё равно понадобится прослойка.
Кому это можно не читать дальше документации
Не всем компаниям стоит вообще трогать эту тему. Если Битрикс24 у вас используется как CRM без внешних интеграций, а отчётность собирается штатными инструментами портала, новости про REST 3.0 на вашу работу не влияют совсем. Версия API — это инструмент разработчика, а не функция интерфейса, и в самом портале вы никаких изменений не увидите.
Тема становится актуальной в трёх случаях. Первый: у вас есть самописная интеграция, которую периодически приходится чинить. Второй: операции с порталом идут массово, будь то выгрузки, синхронизации или импорт номенклатуры. Третий: руководителю нужны в аналитике цифры, которых в Битрикс24 физически нет, и сейчас они попадают туда через файлы.
Во всех остальных ситуациях достаточно знать, что платформа развивается, и вернуться к вопросу, когда появится конкретная задача. Гнаться за новой версией API ради самой версии значит тратить бюджет без измеримого результата.
Частые вопросы
Нужно ли срочно переписывать существующие интеграции на REST 3.0?
Нет, срочности нет. В документации Битрикс24 указано, что обе версии REST работают одновременно, прежние методы остаются рабочими и планов их отключить не объявлено. Разумная стратегия в том, чтобы переводить сценарии постепенно, начиная с тех, где новая версия даёт конкретный выигрыш: массовые операции, защита от дублей, лишние запросы за связанными данными.
Сколько запросов можно отправить одним пакетом?
Не более 50 подзапросов в одном пакете. Если отправить больше, каждый запрос сверх лимита вернёт ошибку ERROR_BATCH_LENGTH_EXCEEDED. Вкладывать один пакет в другой нельзя, вложенность batch запрещена. Для операций большего объёма пакеты отправляют последовательно, передавая нужные значения между ними на стороне интеграции.
Как понять, какие методы уже доступны в REST 3.0?
Вызовите метод rest.documentation.openapi на своём портале. Он возвращает автоматически сгенерированную спецификацию с перечнем доступных методов, параметров и схем именно для вашего Битрикс24. Это надёжнее любых сторонних списков, потому что учитывает конкретную конфигурацию портала, установленные приложения и права пользователя, от имени которого идёт вызов.
Что нужно, чтобы работать с методами BI-Конструктора?
Пользователю, от имени которого выполняются вызовы, нужны сразу два права: «Доступ к BI-конструктору» и «Доступ к рабочему месту аналитика». Одного из них недостаточно, метод вернёт отказ. Дальше настраивается коннектор с четырьмя адресами внешней системы, на его основе создаётся источник с параметрами авторизации, и уже к источнику привязываются таблицы.
Заменяют ли новые методы biconnector.table прежние dataset?
Да, группа biconnector.dataset считается устаревшей, и новые интеграции стоит строить на biconnector.table. Пять методов из семи меняют только название, поэтому перенос в большинстве случаев механический. Исключение составляют dataset.add и dataset.delete: они ведут себя иначе, чем их аналоги в новой группе, и эти два места нужно проверить отдельно.
Поможет ли Idempotency-Key, если заявки дублируются из-за самих клиентов?
Нет. Заголовок защищает только от повторной отправки одной и той же операции, например когда скрипт делает ретрай после таймаута. Если человек дважды заполнил форму или обратился в двух мессенджерах, это разные операции с разными ключами. Такие случаи закрываются правилами дедупликации по телефону и почте на стороне CRM.