Интеграции по API: что важно настроить
Интеграции по API — это то, что превращает Битрикс24 из готовой CRM в платформу, связанную с остальными системами компании. Сайт, 1С, телефония, мессенджеры, внешние AI-сервисы — всё это общается с Битрикс24 через REST API. Если интеграция настроена правильно, данные синхронизируются, задачи создаются, уведомления приходят. Если неправильно — данные теряются, запросы падают с ошибками, а менеджеры не понимают, почему информация не обновляется.
В 2026 году в REST API Битрикс24 произошли важные изменения. Появилась поддержка REST 3.0 с новыми методами CRM, batch-запросы для REST 3.0, отложенное выполнение групповых запросов для больших объёмов данных, идемпотентность запросов . Но главное — изменились правила доступа: с 1 сентября 2026 года на тарифах Essentials (стандартная версия) REST API стал недоступен, а неограниченный доступ остался только на Vibe+. Это значит, что компании, которые используют интеграции, должны либо перейти на Vibe+, либо пересмотреть архитектуру интеграций.
В этой статье — полное руководство по интеграциям через REST API: как создать вебхук, какие лимиты действуют, как обрабатывать ошибки, как использовать batch для сокращения числа запросов и какие рекомендации по производительности помогут избежать проблем. Если нужна кастомизация Битрикс24 под ваш процесс — поможем.
Вебхуки: вход и исходящие
Вебхук — это простой способ авторизации для вызова REST API без создания полноценного приложения. В Битрикс24 есть два типа вебхуков.
Входящий вебхук
Входящий вебхук — это URL с токеном, который позволяет внешним системам вызывать методы Битрикс24. Например, ваш сайт может отправлять заявки в CRM через входящий вебхук, не создавая приложение.
Создать входящий вебхук может администратор: Разработчикам → Другое → Входящий вебхук. Вы выбираете права (скоупы), которые будут доступны вебхуку, и получаете URL вида https://your-bitrix24.ru/rest/1/xxxxx/.
Исходящий вебхук
Исходящий вебхук — это механизм, при котором Битрикс24 отправляет события на ваш сервер. Вы регистрируете обработчик, и при наступлении события (например, создание сделки) Битрикс24 отправляет POST-запрос на указанный URL.
Исходящие вебхуки настраиваются в том же разделе. Вы указываете URL обработчика и выбираете события, на которые хотите подписаться.
💡 Важно
В 2026 году в настройках модуля REST разделены права на создание собственных входящих вебхуков и входящих вебхуков для всех пользователей . Это значит, что не каждый сотрудник может создать вебхук с полными правами. Проверьте настройки, если интеграция не работает.
Лимиты API
Битрикс24 ограничивает интенсивность запросов, чтобы один активный клиент не влиял на работу остальных. Лимиты зависят от тарифа.
Лимит интенсивности
Работает по принципу Leaky Bucket. Каждый запрос увеличивает счётчик. Когда счётчик превышает порог, следующий запрос блокируется с ошибкой QUERY_LIMIT_EXCEEDED. Счётчик уменьшается с определённой скоростью.
| Тариф | Скорость уменьшения счётчика (Y) | Лимит до блокировки (X) |
|---|---|---|
| Энтерпрайз | 5 запросов/сек | 250 |
| Прочие | 2 запроса/сек | 50 |
Это значит, что на обычном тарифе можно стабильно отправлять не более 2 запросов в секунду. Кратковременно можно больше, но не постоянно. Если несколько приложений работают с одного IP, они используют общий лимит.
Лимит времени выполнения
Один запрос должен выполниться не дольше 60 секунд. Если дольше — он прерывается по таймауту. Это важно для тяжёлых запросов с большими выборками или сложными фильтрами.
Лимит накопленного времени
Битрикс24 учитывает не только количество запросов, но и накопленное время выполнения метода за последние 10 минут. Если метод вызывается слишком часто и долго, он может быть заблокирован с ошибкой OPERATION_TIME_LIMIT .
Обработка ошибок
Ошибки в REST API приходят в теле ответа, а не только в HTTP-статусе. Это важно для правильной обработки.
Как распознать ошибку
| Что в теле ответа | Что значит | Что делать |
|---|---|---|
Есть result, result_error пустой | Вызов выполнен | Разобрать данные |
Есть error и error_description | Вызов не выполнен | Разобрать ошибку |
result.result_error непустой | Пакет batch принят, но часть подзапросов упала | Разобрать по ключам команд |
Поле error может быть пустым — тогда причину показывает только error_description. Например, запрос несуществующей сделки вернёт статус 400 и тело {"error": "", "error_description": "Not found"}.
Ключевые коды ошибок
- QUERY_LIMIT_EXCEEDED. Превышен лимит интенсивности. Нужно повторить с задержкой (экспоненциальная задержка);
- OPERATION_TIME_LIMIT. Превышено накопленное время выполнения метода. Нужно разбить операции на более мелкие или делать паузы;
- ACCESS_DENIED. Недостаточно прав. Проверьте скоупы вебхука или приложения;
- NOT_FOUND. Объект не найден. Проверьте ID;
- INVALID_PARAMS. Неверные параметры. Проверьте формат полей.
Batch-запросы
Batch позволяет отправить до 50 вызовов методов в одном HTTP-запросе. Это сокращает количество запросов и помогает уложиться в лимит интенсивности .
Как это работает
Вы формируете массив команд, каждая с своим ключом. Битрикс24 выполняет их последовательно и возвращает результат по каждому ключу. Если один подзапрос упал, остальные всё равно выполняются, а ошибка возвращается в result_error.
Ограничения
- До 50 вызовов. Больше — ошибка;
- Batch не уменьшает ресурсоёмкость. Он сокращает число HTTP-запросов, но каждый метод внутри всё равно выполняется и тратит время ;
- В REST 3.0 batch работает иначе. Появилась поддержка
$refи$refArrayдля передачи результатов между подзапросами.
Рекомендации по производительности
Чтобы интеграция не упиралась в лимиты и не теряла данные, следуйте нескольким правилам.
Сокращайте число запросов
- Кэшируйте данные. Списки полей, справочники, настройки меняются редко. Храните их у себя;
- Используйте batch. До 50 вызовов в одном запросе;
- Запрашивайте только нужные поля. Параметр
selectсокращает объём ответа; - Отключайте подсчёт общего количества. Передавайте
start = -1и переходите к следующей странице по ID .
Снижайте ресурсоёмкость
- Разбивайте массовые операции. Несколько мелких запросов безопаснее одного тяжёлого;
- Упрощайте фильтры. Сложные фильтры увеличивают время выполнения;
- Следите за
durationв ответе. Полеtime.durationпоказывает время запроса .
Обрабатывайте события правильно
Если ваша интеграция подписана на события (например, OnCRMDealUpdate), обработчик должен отвечать быстро. Битрикс24 не отправляет событие повторно, если обработчик не ответил или вернул ошибку. Часть событий будет потеряна .
Решение: принимайте события во входящую очередь на своей стороне, сразу отвечайте Битрикс24, а обработку выполняйте асинхронно.
REST 3.0
В 2026 году Битрикс24 развивает REST 3.0 — новую версию API с улучшенной производительностью и новыми методами.
Что изменилось
- Новый адрес. Методы REST 3.0 вызываются по адресу
/rest/api/, а не/rest/; - Поля в camelCase. Вместо
TITLE—title, вместоSTAGE_ID—stageId; - Обязательный select. Без параметра
selectметодыgetиlistвозвращают толькоid; - Новые методы CRM. Методы сделок, лидов, контактов, компаний и предложений переехали в REST 3.0. Для смарт-процессов и счетов изменились имена методов;
- Идемпотентность. Добавлена поддержка идемпотентных запросов ;
- Batch 3.0. Поддержка
$refиrefArrayдля передачи данных между подзапросами.
💡 Важно
Методы предыдущей версии и REST 3.0 работают одновременно и меняют одни и те же данные. Интеграцию можно переводить по частям: часть методов вызывать по старому адресу, часть — по новому.
Тарифы и доступ к API
С 1 сентября 2026 года Битрикс24 ввёл новую линейку тарифов. Это напрямую влияет на интеграции.
| Версия тарифа | REST API | Market | AI и MCP |
|---|---|---|---|
| Essentials | Недоступен | Ограничен | Ограничен |
| Vibe+ | Без ограничений | Без ограничений | Без ограничений |
Если у вас был годовой абонемент, купленный до 1 сентября 2026 года, вы сохраняете неограниченный доступ до конца оплаченного периода. Для месячных и квартальных подписок переходный период действовал до 30 ноября 2026 года.
Это значит, что компании, которые зависят от интеграций, должны либо перейти на Vibe+, либо искать альтернативы (например, использовать только входящие вебхуки для простых сценариев, если они доступны на тарифе).
Типичные ошибки
1. Нет обработки лимитов
Интеграция отправляет запросы без задержек и упирается в QUERY_LIMIT_EXCEEDED. Нужна экспоненциальная задержка и batch.
2. Обработчик событий отвечает медленно
Битрикс24 не ждёт и не повторяет. События теряются. Нужна очередь на стороне приложения.
3. Нет проверки ошибок в теле ответа
Интеграция смотрит только на HTTP-статус. Ошибка приходит с кодом 200, но с полем error. Данные не обрабатываются.
4. Тяжёлые запросы без разбивки
Один запрос на 10 000 записей упирается в таймаут 60 секунд. Нужна постраничная выборка.
5. Не учтены изменения тарифов
Интеграция работала на старом тарифе, а после перехода на Essentials REST API стал недоступен. Нужно планировать переход на Vibe+.
Наши рекомендации
Что вы получаете, заказывая настройку у нас
- Настройку вебхуков — входящих и исходящих;
- Обработку лимитов — с задержками и batch;
- Обработку ошибок — с проверкой тела ответа;
- Оптимизацию запросов — постраничная выборка, select, кэширование;
- Переход на REST 3.0 — если нужно;
- Обучение — как поддерживать интеграцию.
📌 Итоговый вывод
Интеграции по API — это не «настроил и забыл». Это система, которая требует внимания к лимитам, ошибкам и изменениям.
Что нужно знать:
- Вебхуки: входящие для вызова API, исходящие для получения событий ;
- Лимиты: 2 запроса/сек на обычных тарифах, 5 запросов/сек на Энтерпрайзе; таймаут 60 секунд;
- Ошибки: проверяйте тело ответа, а не только HTTP-статус; ключевые коды —
QUERY_LIMIT_EXCEEDED,OPERATION_TIME_LIMIT; - Batch: до 50 вызовов в одном запросе, сокращает интенсивность, но не ресурсоёмкость ;
- Производительность: кэширование, select, постраничная выборка, очередь для событий ;
- REST 3.0: новый адрес
/rest/api/, camelCase, обязательный select; - Тарифы: с 1 сентября 2026 REST API недоступен на Essentials, только на Vibe+;
- Ошибки: нет обработки лимитов, медленный обработчик, нет проверки тела, тяжёлые запросы, не учтены тарифы.
Также рекомендуем: Кастомизация, Кастомные роботы, Виджеты, все статьи.