N3S
Связаться

← Все статьи · CRM · 12 ноября 2026 г. · 4 мин чтения

REST API Битрикс24: с чего начать разработчику

REST API Битрикс24: с чего начать разработчику

REST API Битрикс24 устроен просто: метод вызывается по HTTPS, ответ приходит в JSON. Сложности начинаются на второй неделе, когда интеграция упирается в лимиты, теряет события и перестаёт работать после окончания подписки. Ниже то, что стоит знать до первого запроса, по официальной документации на ноябрь 2026 года.

Что нужно до первого запроса

REST API доступен только на коммерческих тарифах: на бесплатном методы отвечают ошибкой ACCESS_DENIED. Кроме тарифа, для работы вебхуков, локальных приложений и интеграций в российской зоне нужна подписка «BitrixGPT + Маркетплейс»: после окончания её пробного периода вебхуки и локальные приложения перестают работать. Пробный период 15 дней включается один раз на портал. Это первое, что проверяется у клиента, прежде чем писать код.

Второе: кто вправе создавать вебхуки. По умолчанию их могут создавать все сотрудники, администратор ограничивает это в настройках безопасности. Для интеграции заводится отдельный технический сотрудник с минимальными правами, потому что права вебхука равны правам его создателя, умноженным на выбранные области доступа.

Четыре способа авторизации

Входящий вебхук. Самый быстрый старт: ссылка вида «домен/rest/ID сотрудника/секретный код/метод». Работает только на одном портале, от имени создателя, с выбранными областями доступа. Подходит для серверных скриптов: выгрузки, синхронизации, уведомлений. Не подходит для методов, которым нужен контекст приложения, например встраивания виджетов.

Исходящий вебхук. Битрикс24 отправляет POST на ваш адрес при событии, например при изменении сделки. В теле только идентификатор изменённой записи, данные нужно дочитать отдельным методом. Адрес должен быть публичным с нормальным сертификатом. Главное свойство: доставка без повторов. Если ваш сервер не ответил, событие потеряно, поэтому обработчик должен отвечать мгновенно и класть событие в свою очередь.

Локальное приложение. Регистрируется на портале, использует OAuth 2.0, получает события, в том числе офлайн, и может встраивать интерфейс. Нужно, когда интеграция должна работать от имени разных сотрудников или показывать что-то внутри Битрикс24.

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

Первый запрос и ответ

Параметры передаются GET или POST, для вложенных структур POST с JSON. Ответ содержит поле с результатом и блок времени выполнения. При ошибке вместо результата приходит код и описание. Запрос в облаке выполняется не дольше 60 секунд.

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

Списки и пагинация

Списочные методы отдают не больше 50 записей на страницу. Следующая страница запрашивается параметром начала выборки, который берётся из поля «next» ответа. По умолчанию каждый запрос считает общее число записей, и на больших таблицах это дорого: в примере из документации на 2,4 миллиона лидов запрос с подсчётом занял почти 50 секунд, без подсчёта 0,1 секунды. Поэтому для выгрузок используется приём: подсчёт отключается значением минус один, сортировка по идентификатору, фильтр «больше последнего полученного идентификатора».

Batch

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

Лимиты

Интенсивность. Счётчик запросов работает по принципу дырявого ведра: на обычных тарифах он уменьшается на два в секунду, а при накоплении 50 запросов следующий получает статус 503 и код QUERY_LIMIT_EXCEEDED. На тарифе Энтерпрайз пять в секунду и порог 250. Лимит считается на портал, а несколько интеграций с одного адреса делят его между собой.

Ресурсоёмкость. В облаке считается накопленное время выполнения каждого метода по десятиминутным корзинам. При превышении метод блокируется со статусом 429 и кодом OPERATION_TIME_LIMIT, остальные методы продолжают работать. Время сброса корзины приходит в ответе, повторять раньше бессмысленно.

Ручная блокировка. За нагрузку, которую создаёт, например, подсчёт всех дел CRM каждые пять минут, портал получает код OVERLOAD_LIMIT, и снимает его только поддержка. Статистика запросов по каждому приложению и вебхуку доступна администратору за последние 14 дней.

Токены приложений

Токен доступа живёт час, токен обновления 180 дней. Обновлять по расписанию не нужно: сигналом служит ошибка expired_token, после которой запрашивается новая пара, и новый токен обновления сохраняется вместо старого. Секрет приложения передаётся только на сервер авторизации Битрикс24, никогда в браузерный код.

REST 3.0

Новая версия работает параллельно со старой по адресу с добавкой «api», принимает только JSON, возвращает списки в едином формате, поддерживает связанные объекты через точку в выборке и ключ идемпотентности для безопасных повторов. Пока в ней задачи, CRM, каталог и часть других разделов. Старые методы CRM помечены как остановленные в развитии, поэтому новые интеграции стоит писать с учётом 3.0.

Семь ошибок

  1. Секретный код вебхука в клиентском коде или открытом репозитории: Битрикс24 блокирует такие вебхуки, признак ошибка INVALID_CREDENTIALS.
  2. Параллельные серии запросов с одного адреса вместо пакетов: QUERY_LIMIT_EXCEEDED в первый же день.
  3. Выгрузка больших таблиц с подсчётом общего числа записей.
  4. Обновление токена перед каждым вызовом и потеря нового токена обновления.
  5. Неверная область доступа или имя метода: для задач область «task», для групп «sonet_group».
  6. Обработчик событий на локальном адресе или медленный обработчик: события теряются без повторов.
  7. Расчёт на то, что подписка не нужна. После окончания пробного периода интеграция останавливается.

С чего начать

Технический сотрудник с минимальными правами, входящий вебхук с областями доступа только под задачу, пакеты для массовых операций, очередь для событий, журнал всех вызовов с кодами ответов. С этим набором интеграция переживает и лимиты, и обновления портала. Как мы строим обмен Битрикс24 с 1С, сайтами и внешними сервисами, описано на странице «Интеграции Битрикс24» и в статье об интеграции с 1С, а когда вместо своей разработки стоит взять готовое приложение, в статье о приложениях из Маркетплейса.

Источники

Есть тема для статьи или задача? Расскажите.

Обсудить проект →