Интеграция Битрикс24: REST API и вебхуки — как связать портал с сайтом, 1С и сервисами

07.10.2026

Коротко: интеграция Битрикс24 с сайтом, 1С, телефонией или своей системой делается тремя способами: готовым приложением из Маркетплейса, вебхуком или собственным приложением на REST API. Вебхук — самый быстрый путь для типовых задач вроде «заявка с сайта в CRM»: адрес с секретным кодом, права выбираются при создании, программировать почти не нужно. Для любого из способов нужна подписка «BitrixGPT + Маркетплейс» на платном тарифе. Ниже — как выбрать способ, как создать входящий и исходящий вебхук, какие лимиты у API и где интеграции обычно ломаются.

Оглавление:

• Что такое интеграция Битрикс24 и что обычно связывают
• Три способа: Маркетплейс, вебхук, приложение
• Что нужно для REST API: тариф и права
• Входящий вебхук: как создать и вызвать метод
• Исходящий вебхук: события и проверка токена
• Лимиты REST API и как в них уложиться
• Интеграция в коробочной версии
• Типичные ошибки интеграций
• Частые вопросы

Что такое интеграция Битрикс24 и что обычно связывают

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

• Сайт → CRM. Заявки, звонки и чаты с сайта становятся лидами или сделками. Часть закрывается штатными CRM-формами и открытыми линиями, нестандартные формы передают данные через REST API.
• 1С ↔ CRM. Контрагенты, счета, оплаты и номенклатура. Подробно — в статье интеграция 1С и Битрикс24.
• Телефония. Звонки виртуальной АТС пишутся в карточку клиента — см. телефония в Битрикс24.
• Мессенджеры и площадки объявлений. Обращения попадают в открытые линии и дальше в CRM.
• Своя учётная система, склад, личный кабинет. Здесь готовых решений обычно нет, связку пишут под задачу.

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

Три способа: Маркетплейс, вебхук, приложение

Практическое правило: если задачу закрывает приложение из Маркетплейса с понятной поддержкой — берите его. Если данные идут в одну сторону и логика простая — вебхук. Если нужна кнопка в карточке сделки, двусторонний обмен или несколько порталов — приложение. Вебхук и локальное приложение отличаются авторизацией: у вебхука постоянный код в адресе, у приложения OAuth 2.0, где access_token живёт один час, а refresh_token — 180 дней.

Что нужно для REST API: тариф и права

По справке Битрикс24 создавать вебхуки и приложения можно только по подписке «BitrixGPT + Маркетплейс». Подписка оформляется на коммерческих тарифах, поэтому с Бесплатного тарифа сначала нужно перейти на платный; для знакомства есть демо-режим. Подписка видна в разделе «Мой тариф». Если вы только выбираете тариф, удобно зарегистрировать Битрикс24 и проверить связку в демо-режиме до покупки.

Второе условие — права. Пункт «Разработчикам» видят не все сотрудники: если его нет, администратор открывает доступ в разделе «Настройки» > «Безопасность» > «Интеграции Битрикс24». Раздавать это право всем подряд не стоит: каждый вебхук — это постоянный ключ к данным портала.

Входящий вебхук: как создать и вызвать метод

Создание

1. Откройте «Приложения» > «Разработчикам» > «Готовые сценарии» > «Другое» > «Входящий вебхук».
2. Отметьте права (scope): только то, что нужно связке. Для заявок с сайта достаточно CRM, для задач — задач.
3. При необходимости задайте дату окончания действия — удобно для временных выгрузок.
4. Сохраните и скопируйте адрес вида https://ваш-портал.bitrix24.ru/rest/ID/секретный-код/.

Вызов метода

К адресу вебхука дописывается имя метода: например, crm.item.add создаёт элемент CRM. Тип элемента задаёт параметр entityTypeId: 1 — лид, 2 — сделка, 3 — контакт, 4 — компания, 31 — счёт; так же создаются элементы смарт-процессов. Старый метод crm.lead.add ещё работает, но в документации помечен как устаревший с рекомендацией перейти на crm.item.add. Коды полей, которые передаются в запросе, разобраны в статье поля в Битрикс24.

Для рабочих интеграций документация рекомендует отправлять запросы методом POST, а GET оставить для проверок. Суффикс .json в адресе необязателен.

От чьего имени работает вебхук

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

Исходящий вебхук: события и проверка токена

Исходящий вебхук создаётся там же: «Готовые сценарии» > «Другое» > «Исходящий вебхук». Указываются адрес обработчика и события, например ONCRMDEALUPDATE — изменение сделки. Когда событие происходит, портал отправляет на адрес POST-запрос с полями event, data, ts и блоком auth, где есть домен портала и application_token.

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

Адрес обработчика должен быть доступен из интернета: localhost, адреса локальной сети и самоподписанные сертификаты не подойдут. Для реакции на события внутри портала, без внешней системы, проще использовать роботов и бизнес-процессы.

Лимиты REST API и как в них уложиться

REST API Битрикс24 ограничивает нагрузку, и интеграция, написанная без учёта лимитов, начинает терять данные при первом росте объёма.

• Скорость запросов. Считается по принципу протекающего ведра: на Энтерпрайзе 5 запросов в секунду с запасом 250, на остальных тарифах 2 в секунду с запасом 50. При превышении приходит ошибка 503 QUERY_LIMIT_EXCEEDED. Приложения с одного IP-адреса делят общий лимит.
• Время выполнения. Суммарное время работы метода считается за 10 минут, при превышении — ошибка 429 OPERATION_TIME_LIMIT. Отдельный запрос должен укладываться в 60 секунд.
• Пакеты. Метод batch объединяет до 50 команд в один запрос — так массовые выгрузки укладываются в лимит скорости.
• Постраничная выдача. Списочные методы отдают данные порциями (у многих — по 50 записей), остальное запрашивается с параметром start.

Отсюда правила: не опрашивать портал «каждую секунду на всякий случай», а реагировать на события; выгрузки собирать пакетами; при ошибке лимита повторять запрос с паузой, а не терять его. Для аналитики по большому объёму данных удобнее BI-конструктор, чем самописная выгрузка через API.

Интеграция в коробочной версии

В коробочном Битрикс24 REST тоже есть, но с оговорками из документации вендора: обновления REST выходят позже, чем в облаке; владелец сервера может отключать модули, поэтому список доступных методов надо проверять методами methods и events; серверу нужен исходящий доступ к сервисам вендора, без него REST не заработает. Исходящие вебхуки в коробке требуют активной лицензии. Взамен коробка позволяет то, чего нет в облаке: доработки на уровне кода и прямую работу с базой — это выход, когда ограничений API не хватает.

Важно: адрес входящего вебхука — это логин и пароль в одной строке. Не вставляйте его в JavaScript на страницах сайта, в публичные репозитории и переписку с подрядчиками: любой, кто его увидит, получит доступ к CRM в пределах прав создателя. Запросы к порталу должен отправлять сервер сайта, а не браузер посетителя. Если адрес утёк — удалите вебхук и создайте новый.

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

• Вебхук создан от имени сотрудника, который уходит. При увольнении Битрикс24 предлагает «Уволить и отключить интеграции» или «Уволить и сохранить интеграции». Неверный выбор останавливает приём заявок — подробнее в статье сотрудники в Битрикс24.
• Права «на всё». Вебхуку для заявок с сайта не нужен доступ к задачам, диску и пользователям. Чем уже scope, тем меньше ущерб при утечке.
• Нет проверки application_token. Обработчик исходящего вебхука принимает любые запросы.
• Дубли контактов. Каждая заявка создаёт новый контакт, потому что интеграция не ищет существующий по телефону или e-mail. Проверку на дубли нужно заложить в логику сразу.
• Нет журнала и повторов. При ошибке лимита или недоступности портала заявка пропадает молча. Нужны запись неудачных запросов и повторная отправка.
• Никто не знает, что подключено. Через год в портале десяток вебхуков без описания. Ведите простой реестр: что за связка, кто владелец, какие права, куда идут данные.

Интеграции — часть общей настройки портала: сначала воронки, поля и права (см. настройка Битрикс24 с нуля), потом связки. Если связать нужно сайт с 1С, а не только с CRM, — это отдельное направление, см. интеграцию сайта с 1С.

Частые вопросы

Что такое вебхук в Битрикс24?
Вебхук — это способ связать портал с внешней системой без написания полноценного приложения. Входящий вебхук даёт постоянный адрес, по которому сайт или скрипт вызывает методы REST API: создать лид, обновить сделку, получить список задач. Исходящий вебхук работает в обратную сторону: при событии в портале, например изменении сделки, Битрикс24 сам отправляет POST-запрос на адрес вашего обработчика.

Как создать входящий вебхук в Битрикс24?
Откройте «Приложения» > «Разработчикам» > «Готовые сценарии» > «Другое» > «Входящий вебхук». Выберите права (например, CRM или задачи), сохраните и скопируйте адрес вида https://портал/rest/ID/код/. Если пункта нет, администратор должен открыть право в «Настройки» > «Безопасность» > «Интеграции Битрикс24». Для работы вебхуков нужна подписка «BitrixGPT + Маркетплейс» на платном тарифе.

Можно ли использовать REST API Битрикс24 на бесплатном тарифе?
Для постоянной работы — нет. По документации Битрикс24 создавать вебхуки и приложения можно только по подписке «BitrixGPT + Маркетплейс», а она оформляется на коммерческих тарифах. С бесплатного тарифа сначала нужно перейти на платный; для знакомства есть демо-режим.

Чем вебхук отличается от локального приложения?
Вебхук работает по постоянному секретному коду в адресе и от имени сотрудника, который его создал, с его правами. Локальное приложение авторизуется по OAuth 2.0: access_token живёт один час, refresh_token — 180 дней, приложение может встраиваться в интерфейс портала. Вебхук проще для односторонних связок вроде «заявка с сайта в CRM», приложение — для интеграций с интерфейсом и долгой поддержкой.

Какие лимиты у REST API Битрикс24?
Скорость запросов считается по принципу протекающего ведра: на Энтерпрайзе 5 запросов в секунду с запасом 250, на остальных тарифах 2 в секунду с запасом 50. При превышении приходит ошибка QUERY_LIMIT_EXCEEDED. Есть и лимит суммарного времени выполнения метода за 10 минут, а один запрос batch объединяет до 50 команд.

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

Работает ли REST API в коробочной версии Битрикс24?
Да, но обновления REST в коробке выходят позже, чем в облаке, а владелец сервера может отключать модули, поэтому список доступных методов надо проверять. Серверу нужен исходящий доступ к сервисам вендора, без него REST не работает. Исходящие вебхуки в коробке требуют активной лицензии.

← Все статьи