API и вебхук Битрикс24 для ИИ-агента: права, лимиты, подписка

Подписка: что нужно знать до настройки

По справке Маркетплейса Битрикс24 от 09.11.2026 доступ к REST API, вебхукам, локальным приложениям и MCP в облаке зоны .RU работает по подписке «BitrixGPT + Маркетплейс»; пробно доступ включается через «Включить демо» (справка). Старые заметки в блогах пишут, что входящие вебхуки бесплатны, но для облака .RU это не подтверждено и устарело.

Цены по данным на 11.11.2026, на весь портал в месяц без НДС: Базовый (5 пользователей) 1 000 ₽, со скидкой 500 ₽; Стандартный (50) 3 000 ₽ и 1 500 ₽; Профессиональный (100) 6 000 ₽ и 3 000 ₽; Энтерпрайз от 250 пользователей по акции от 6 800 ₽. Скидка 50% действует при заказе до 31.12.2026. Проверяйте актуальные цифры на странице Маркета. Разбор по тарифам есть в статье «Сколько стоит ИИ в Битрикс24».

Как создать вебхук с минимальными правами

1. Создайте отдельного пользователя для интеграции или выберите сотрудника с понятным уровнем доступа. Не используйте учётку директора: агент увидит всё, что видит она.
2. Откройте раздел разработчика и добавьте входящий вебхук.
3. Отметьте только нужные скоупы. Для сводки по воронке хватит CRM, задач и структуры компании (user, department), для звонков добавьте телефонию. Учтите: скоуп открывает раздел целиком, отдельной галочки «только чтение» у него нет. Поэтому чтение от записи отделяют двумя способами: права пользователя-владельца в самом Битрикс24 и переключатели на стороне агента.
4. Сохраните ссылку и проверьте вызов на безопасном методе: например, получите список сделок за последние сутки.
5. Запишите, кто владелец вебхука и когда его пересматривать. Ссылку можно пересоздать, если она могла утечь.

Лимиты облака

По документации (apidocs, пример ответа от 14.05.2026) для облака действуют такие ограничения:

• счётчик запросов: на Энтерпрайзе порог 250, после него скорость снижается до 5 запросов в секунду, на остальных тарифах порог 50 и 2 запроса в секунду;
• при превышении возвращается ошибка 503 QUERY_LIMIT_EXCEEDED;
• в один batch помещается до 50 вызовов;
• тайм-аут запроса 60 секунд;
• для ресурсоёмких методов возможна ошибка 429 OPERATION_TIME_LIMIT.

Ограничение «600 запросов в час на всех» из справки от 30.10.2026 относится к коробочной версии, в облаке его нет (справка). Для ИИ-агента практический вывод такой: запрашивать данные пачками, не обходить все карточки по одной и ставить сводку на ночь или раннее утро, когда портал свободен.

Что агент может читать

REST API Битрикс24 охватывает CRM (лиды, сделки, контакты, компании, дела, стадии), задачи, календарь, структуру, учёт времени, телефонию, чаты и открытые линии (справочник). Для звонков метод voximplant.statistic.get отдаёт до 50 записей на страницу со ссылкой на запись (CALL_RECORD_URL) и связью с делом CRM. Получение текста расшифровки отдельным методом мы не подтверждаем, поэтому расшифровку звонков считаем сценарием для пилота. Одно практическое замечание: если просить обычную языковую модель «написать вызов API» без документации, она выдумывает методы. В бенчмарке на Habr от 30.07.2025 модель верно решила 76 задач из 150, около половины (модель устарела, но вывод применим). Поэтому у агента должен быть фиксированный список проверенных методов, а не свободная генерация запросов.

Как это работает в VibeLab

Адрес вебхука вставляется в подключение на странице «Подключения», а для каждого ИИ-сотрудника есть отдельные переключатели «Читать» и «Писать». Без разрешения инструмент отказывает. Сотрудник читает лиды, сделки, контакты, компании, дела и комментарии таймлайна, воронки и историю стадий, задачи, пользователей, статистику звонков и поиск дублей. Запись (создать сделку, обновить, перенести стадию, добавить заметку, создать задачу, прикрепить файл) доступна только при «Писать», а в режиме «С согласованием» выполняется после подтверждения человеком. Работа идёт по расписанию и по запросу, на каждую задачу ведётся журнал. Чем MCP Server Битрикс24 отличается от вебхука, разобрано в статье «MCP Битрикс24»; про безопасность — здесь.

Типичные ошибки при настройке

Чаще всего проблемы возникают не с лимитами, а с правами и дисциплиной. Первая ошибка: вебхук создан под учётной записью директора, и агент получает доступ ко всему. Вторая: ссылку вставили в общий чат или документ, и теперь она есть у десятка людей. Третья: ссылку не пересматривали после ухода сотрудника-владельца, а она осталась рабочей.

Четвёртая ошибка связана с нагрузкой. Если агент обходит карточки по одной, он упрётся в порог запросов, а сам портал станет медленнее для менеджеров. Правильная схема другая: фильтр по стадии и дате, выборка нужных полей и batch до 50 вызовов. Пятая: включили право записи «на всякий случай». Если агенту не нужно менять CRM для сегодняшней задачи, право записи не нужно.

Хороший рабочий минимум выглядит так: отдельный пользователь с узкими правами, только нужные скоупы, право «Читать» у агента, ссылка в хранилище секретов, дата следующего пересмотра в календаре админа. Это занимает десять минут и закрывает основные риски.

Вебхук или OAuth-приложение

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

Как начать в VibeLab

Создайте вебхук по списку выше, подключите его на странице «Подключения», оставьте только «Читать» и поставьте одну задачу, например список сделок без активности. Сравните с ручным списком: сколько нашёл сотрудник, что пропустил, сколько минут это заняло. Первый месяц бесплатно, карта не нужна. Полный порядок на один вечер описан в статье «Как подключить VibeLab к Битрикс24 за вечер».