Приложение для Битрикс24 — это внешний веб-сервис, который общается с порталом по REST API и встраивается в его интерфейс. Разберём, какими бывают приложения, как настроить авторизацию OAuth 2.0 и обработать установку, чтобы получить рабочую заготовку под публикацию в Маркете.
Типы приложений и где они регистрируются
Битрикс24 различает локальные и тиражные приложения. Локальное создаётся прямо в портале (Разработчикам → Другое → Локальное приложение) и работает только на этом аккаунте — удобно для интеграции под конкретного клиента. Тиражное регистрируется в кабинете партнёра и после модерации попадает в Битрикс24.Маркет, откуда его ставит любой портал.
По архитектуре приложения делятся на две группы:
- Серверные — имеют бэкенд, хранят токены, могут принимать вебхуки событий и работать в фоне без открытого окна.
- Только клиентские — состоят из статических страниц и JS на базе библиотеки
BX24.js; авторизация проходит через фрейм, отдельный сервер для хранения токенов не обязателен.
refresh_token, обслуживает фоновые задачи и обрабатывает события портала.Регистрация и параметры приложения
При создании приложения вы указываете ключевые параметры, которые затем участвуют в OAuth-обмене:
| Параметр | Назначение |
|---|---|
client_id | Публичный идентификатор приложения («Код приложения») |
client_secret | Секретный ключ, участвует в обмене кода на токен |
| Путь обработчика | URL страницы приложения, открываемой в фрейме портала |
| Путь установки | URL, вызываемый при установке (может совпадать с обработчиком) |
| Права (scope) | crm, user, task, im, placement и др. |
Scope запрашивается по принципу минимальной достаточности: чем меньше прав, тем выше доверие при модерации. Расширить права у уже установленного приложения без переустановки нельзя — это важно закладывать в дизайн заранее.
Авторизация по OAuth 2.0
Битрикс24 использует стандартный OAuth 2.0. Серверное приложение получает authorization code, а затем меняет его на пару токенов через сервис oauth.bitrix.info/oauth/token/:
GET /oauth/token/?grant_type=authorization_code&client_id=...&client_secret=...&code=...
В ответ приходит JSON с полями access_token, refresh_token, expires_in и member_id. Ключевые правила:
access_tokenживёт 1 час — по истечении его нужно обновлять.refresh_tokenодноразовый: при каждом обновлении приходит новая пара, старый токен инвалидируется.member_idоднозначно идентифицирует портал — по нему вы связываете токены с аккаунтом в своей базе.
invalid_grant и приложение «отвалится» до переустановки. Обновляйте токены атомарно, с блокировкой на уровне записи портала.Обработка установки
При установке портал открывает страницу установки в iframe и передаёт POST-параметры авторизации: AUTH_ID, REFRESH_ID, AUTH_EXPIRES, member_id, DOMAIN. Сценарий обычно такой:
- Сохранить токены и
member_idв своей базе, привязав к порталу. - При необходимости привязать встройки методом
placement.bindи зарегистрировать обработчики событий черезevent.bind. - Вызвать в JS
BX24.installFinish()— сигнал порталу об успешном завершении установки.
Без вызова installFinish() портал считает установку незавершённой, и приложение не появится в списке рабочих. Для клиентских приложений шаг сводится к инициализации SDK и финализации:
BX24.init(function(){ /* bind placements */ BX24.installFinish(); });
Первые вызовы REST
После установки можно вызывать REST-методы. В клиентском коде это BX24.callMethod, в серверном — HTTP-запрос на https://portal.bitrix24.ru/rest/METHOD.json с access_token. Пример из браузера:
BX24.callMethod('crm.deal.list', {select:['ID','TITLE']}, function(res){ console.log(res.data()); });
Полезные приёмы на старте:
batch— до 50 команд в одном запросе, экономит лимиты и снижает задержки.profileиscope— проверить, кто вызывает и какие права реально выданы.- Соблюдайте лимиты: при превышении интенсивности приходит
QUERY_LIMIT_EXCEEDED— закладывайте очередь и повторы.
Подготовка к публикации
Когда логика работает, приложение упаковывают для Маркета. Понадобятся заполненная карточка (описание, скриншоты, иконки), корректно оформленные права, страницы установки и удаления, а также обработчик события ONAPPUNINSTALL — чтобы чистить данные при удалении. Перед отправкой на модерацию пройдитесь по чек-листу:
- Приложение ставится и удаляется без ошибок на чистом портале.
- Все запрашиваемые права реально используются.
- Есть политика конфиденциальности и корректная обработка персональных данных.
- Интерфейс адаптирован под фрейм: окно подгоняется через
BX24.fitWindow().
Итог
Разработка приложения для Битрикс24 начинается с выбора типа (локальное или тиражное, серверное или клиентское), настройки OAuth 2.0 и корректной обработки установки с обязательным installFinish(). Дальше — аккуратная работа с токенами, вызовы REST и упаковка под Маркет. Самые частые ошибки лежат в области жизненного цикла токенов и прав доступа, поэтому их стоит проектировать с самого начала.
Мы в B2Bsite проектируем и разрабатываем приложения и интеграции для Битрикс24 под ключ — от архитектуры и OAuth до публикации в Маркете и последующей поддержки. Если нужен надёжный REST-сервис, который переживёт рост нагрузки и обновления платформы, поможем собрать его правильно.
Частые вопросы
Чем локальное приложение отличается от тиражного?
Локальное создаётся в самом портале и работает только на нём, тиражное регистрируется в кабинете партнёра и после модерации доступно всем порталам через Битрикс24.Маркет.
Нужен ли свой сервер для приложения?
Для чисто интерфейсных приложений можно обойтись статикой и BX24.js. Но как только нужны фоновые задачи, хранение токенов и обработка событий, требуется серверный бэкенд.
Сколько живёт access_token?
Один час. После этого его нужно обновлять по refresh_token, который при каждом обновлении меняется на новый.
Что будет, если не вызвать installFinish?
Портал сочтёт установку незавершённой, и приложение не появится в списке рабочих. Вызов installFinish обязателен в конце сценария установки.
Можно ли добавить права уже установленному приложению?
Нет, расширить scope без переустановки нельзя. Поэтому набор прав нужно продумывать заранее, с запасом под планируемую функциональность.
Как связать токены с конкретным порталом?
По полю member_id — оно однозначно идентифицирует аккаунт Битрикс24 и передаётся вместе с токенами при установке и авторизации.
Что делать при QUERY_LIMIT_EXCEEDED?
Это превышение интенсивности запросов. Нужно снижать частоту, объединять вызовы в batch и ставить повторы с задержкой через очередь.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.