Как расширить Битрикс24 своим приложением: локальные приложения, кнопки в меню, REST

Стандартный Битрикс24 закрывает большинство задач бизнеса. Но рано или поздно компания упирается в потолок: нужна кнопка, которой нет в коробке, свой пункт меню, обмен данными с внутренней системой, которой в Маркетплейсе никогда не будет. Разберём, что реально можно сделать своими силами, а где начинается работа, которую разумнее заказать.

Три способа расширить портал

Прежде чем выбирать инструмент, стоит понимать разницу между тремя принципиально разными подходами.

Встроенное приложение в интерфейсе. Полноценное расширение, которое живёт внутри Битрикс24 как вкладка, виджет или отдельный раздел. Пользователь работает с ним, не покидая портал.

Кнопка или пункт меню. Более точечное расширение: добавляется конкретный элемент управления (кнопка в карточке, пункт левого меню), который запускает своё действие или открывает своё приложение.

Вебхук с внешним сервисом. Не расширение интерфейса, а канал обмена данными: Битрикс24 отправляет или принимает данные по запросу, без какого-либо визуального элемента внутри портала.

Выбор зависит от задачи: если нужно, чтобы сотрудник что-то видел и с чем-то взаимодействовал внутри Битрикс24, нужно приложение или элемент интерфейса. Если нужно просто передать данные между системами без участия человека, обычно достаточно вебхука.

Что такое локальное приложение и чем оно отличается от тиражного

В терминологии Битрикс24 приложение может быть локальным или тиражным.

Тиражное приложение публикуется в Маркетплейсе и устанавливается любым порталом Битрикс24. Оно проходит модерацию, должно соответствовать требованиям платформы, и его код физически размещается у разработчика приложения, а не у конечного клиента.

Локальное приложение создаётся и работает в рамках одного конкретного портала. Оно не публикуется в Маркетплейсе, не проходит модерацию для публичного распространения, и предназначено именно для внутренних нужд вашей компании. По функциональным возможностям локальное приложение ничем не уступает тиражному: тот же доступ к API, те же точки встраивания в интерфейс. Разница только в распространении: одно приложение для одного портала против готового решения для всех.

Для большинства компаний, которые хотят расширить свой конкретный Битрикс24 под свои процессы, нужно именно локальное приложение: проще в регистрации, не требует модерации, полностью под вашим контролем.

Где регистрируется локальное приложение и какие права запрашивает

Путь к регистрации. «Разработчикам» → «Другое» → «Локальное приложение» (раздел может называться незначительно по-разному в зависимости от версии интерфейса, ищите пункт с упоминанием «Приложения» или «REST API» в разделе разработчика).

При регистрации приложения указываются:

Название и описание. Внутреннее, видно только администраторам портала.

URL обработчика. Адрес вашего сервера, куда Битрикс24 будет отправлять запросы и куда будет перенаправлять пользователя при открытии приложения.

Права доступа (scope). Конкретный список того, к каким разделам портала приложению разрешён доступ: CRM, задачи, диск, пользователи и так далее. Это ключевой момент безопасности: приложению стоит давать только те права, которые реально нужны для его функции, а не «всё подряд на всякий случай».

После регистрации Битрикс24 выдаёт идентификатор приложения и ключ доступа, которые используются при каждом запросе к API от имени этого приложения.

Как добавить кнопку в карточку сделки и пункт в левое меню

Оба сценария реализуются через механизм placement, точки встраивания, которые Битрикс24 предоставляет для сторонних приложений.

Кнопка в карточке сделки. Приложение регистрируется на placement типа CRM_DEAL_DETAIL_TAB (для отдельной вкладки) или на более точечные placement для конкретных зон карточки. Регистрация выполняется методом REST API placement.bind: приложение указывает, на каком placement оно хочет появиться, и URL обработчика, который откроется при нажатии.

Пункт в левом меню. Для добавления собственного раздела в основную навигацию Битрикс24 используется placement LEFT_MENU. После регистрации в левом меню портала появляется новый пункт со ссылкой на ваше приложение, доступный всем пользователям с соответствующими правами.

Путь для просмотра уже зарегистрированных placement конкретного приложения: «Разработчикам» → открыть приложение → раздел «Обработчики событий» или «Placement» (название зависит от версии интерфейса).

Технически регистрация placement, это один REST-запрос с указанием типа точки встраивания, заголовка элемента и URL. Дальше, что происходит при нажатии, определяется вашим обработчиком: можно открыть простую страницу, полноценный интерфейс или сразу выполнить действие через API без визуального окна.

Что можно и чего нельзя без серверной части

Частый вопрос: обязательно ли иметь свой сервер, чтобы расширить Битрикс24.

Без серверной части возможно: простые сценарии на основе исходящих вебхуков и роботов, которые сам Битрикс24 умеет выполнять без внешнего кода (уведомления, изменение полей, создание задач по условию). Такие сценарии полностью укладываются в стандартный функционал роботов и бизнес-процессов.

Без серверной части невозможно: любое приложение, добавляющее в интерфейс свою кнопку, вкладку или пункт меню, которая должна что-то показывать или обрабатывать нестандартную логику. Для этого нужен обработчик, физически расположенный на каком-то сервере, будь то ваш собственный сервер, облачный хостинг или даже простая бессерверная функция. Битрикс24 обращается к этому URL, а логика приложения выполняется там, а не внутри самого портала.

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

REST и вебхуки: когда чего достаточно

Вебхук в Битрикс24 бывает входящим и исходящим. Входящий вебхук, это готовый URL с ключом доступа, который позволяет внешней системе обращаться к Битрикс24 напрямую, без регистрации полноценного приложения. Исходящий вебхук, это подписка на событие: когда в портале что-то происходит (создана сделка, изменено поле), Битрикс24 сам отправляет запрос на указанный вами URL.

Когда достаточно вебхука. Разовая или простая регулярная передача данных между Битрикс24 и внешней системой, без визуального элемента в интерфейсе. Например: при создании новой сделки автоматически создать запись во внутренней учётной системе компании. Настройка входящего вебхука занимает несколько минут: путь «Разработчикам» → «Другое» → «Входящий вебхук» → выбрать права доступа → получить готовый URL.

Когда нужно полноценное приложение. Если требуется визуальный элемент внутри Битрикс24 (кнопка, вкладка, виджет), сложная логика с несколькими правами доступа, или если приложением должны пользоваться разные сотрудники с разграничением доступа: здесь входящего вебхука недостаточно, нужна регистрация приложения с собственной авторизацией через OAuth.

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

Ограничения, о которых нужно знать заранее

Лимиты запросов. REST API Битрикс24 ограничивает количество запросов в единицу времени. При интенсивном использовании (массовая выгрузка, синхронизация больших объёмов данных) нужно проектировать обработчик с учётом очередей и повторных попыток при превышении лимита, а не рассчитывать на мгновенную обработку любого объёма.

Что ломается при обновлении портала. Официальный REST API и стандартные placement обновляются с обратной совместимостью: приложения, написанные по документации, продолжают работать. Риск возникает там, где разработчик обходит официальный API и опирается на внутреннюю структуру интерфейса (конкретные CSS-классы, недокументированное поведение): такие решения могут сломаться при любом обновлении без предупреждения.

Коробка против облака. Если у компании коробочная версия Битрикс24 (установленная на собственном сервере, а не облачная), часть возможностей REST API и типов приложений может отличаться от облачной версии. Перед разработкой стоит уточнить, на какой версии портала будет работать расширение, чтобы не упереться в отличия уже на стадии реализации.

Типичная ошибка: интеграция на вебхуке с админскими правами

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

Что происходит дальше. Администратор, под чьей учётной записью создан вебхук, увольняется или меняет должность. Интеграция продолжает физически работать (ключ не привязан жёстко к активности пользователя в моменте), но никто в компании не понимает, что вебхук существует, какие у него права и что будет, если этого пользователя деактивировать. В какой-то момент интеграция ломается без видимой причины, потому что аккаунт, от имени которого она работала, оказался заблокирован.

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

Где заканчивается «сделать самому» и начинается разработка

Настройка входящего вебхука и простого исходящего события, это задача, с которой справится технически грамотный сотрудник компании без опыта профессиональной разработки, по документации Битрикс24.

Регистрация локального приложения с собственным обработчиком, добавление кнопки в карточку сделки, пункт в меню, полноценная логика на сервере, это уже задача для разработчика: нужен код, который принимает запросы от Битрикс24, обрабатывает данные, отдаёт ответ, и который нужно где-то размещать и поддерживать.

Если у вас есть штатный разработчик или подрядчик, знакомый с REST API Битрикс24: описанного в этой статье достаточно, чтобы понимать логику и ставить задачу правильно. Если такого специалиста нет, а расширение нужно: у нас есть каталог из 36 готовых модулей в приложениях SellUs, которые закрывают частые задачи без разработки с нуля, и отдельное направление разработки под задачу, если требуется что-то нестандартное именно под ваш процесс.

Похожий пример точечной интеграции, синхронизация Битрикс24 с 1С, разобран в статье интеграция Битрикс24 и 1С, там показано, как выглядит рабочая связка на практике.

Часто задаваемые вопросы

Нужен ли отдельный сервер для локального приложения или можно обойтись без него?

Обработчик приложения должен быть доступен по URL из интернета, это может быть собственный сервер, облачный хостинг или бессерверная платформа. Без какого-либо внешнего адреса, куда Битрикс24 сможет отправлять запросы, приложение работать не будет.

Можно ли протестировать локальное приложение перед тем, как показывать его сотрудникам?

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

Чем OAuth-авторизация приложения лучше входящего вебхука с точки зрения безопасности?

OAuth привязывает каждый запрос к конкретному авторизованному пользователю с его правами, а не к одному общему ключу. Если сотрудник увольняется или меняются его права в Битрикс24, это автоматически отражается на том, что может делать приложение от его имени, чего не происходит с единым ключом вебхука.

Сколько времени занимает регистрация локального приложения?

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

Можно ли добавить своё приложение сразу в несколько мест интерфейса?

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

Разберём, что нужно именно вам

Если у вас есть конкретная задача расширения Битрикс24, кнопка, интеграция с внутренней системой, нестандартный процесс, который не укладывается в коробочный функционал: расскажем, что из этого закрывается готовыми решениями, а что требует точечной разработки, и дадим оценку по срокам и стоимости.

Полезные материалы

Каталог приложений SellUs: 36 готовых модулей для Битрикс24, многие задачи закрываются без разработки с нуля.

Разработка под Битрикс24: когда нужно нестандартное решение именно под ваш процесс.

Интеграция Битрикс24 и 1С: пример рабочей связки через REST API на практике.

Аудит-чеклист Битрикс24: проверьте текущую настройку портала перед тем, как расширять его новой разработкой.