Серверное локальное приложение с пользовательским интерфейсом

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

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

Другие виды локальных приложений и критерии выбора между ними описаны в статье Локальные приложения.

Как работает авторизацияКак работает авторизация

Приложение во фрейме использует упрощенный вариант OAuth 2.0: запрашивать токены отдельно не нужно, Битрикс24 передает их при каждом открытии приложения.

1. Сотрудник запускает приложение в интерфейсе Битрикс24.
2. Битрикс24 обращается POST-запросом к адресу обработчика и передает данные авторизации. Обработчик — это страница приложения, которую вы указали в поле Путь вашего обработчика.
3. Обработчик сравнивает пришедший APPLICATION_TOKEN с сохраненным значением.
4. Приложение подставляет AUTH_ID в запросы к REST API и вызывает методы от имени сотрудника, который открыл приложение.

Сравнение на третьем шаге — требование к вашему коду. Порядок описан в разделе Как проверить источник запроса.

Основные параметры запроса:

Полный состав данных разобран в статье Упрощенный вариант получения токенов OAuth 2.0, порядок продления токенов — в статье Автоматическое продление токенов OAuth 2.0.

Токены приходят только в том запросе, которым Битрикс24 открывает страницу. Последующие запросы со страницы, в том числе AJAX, идут уже без них, поэтому сохраняйте токены на своей стороне — например, в сессии. Обновить токены на самой странице можно вызовом BX24.refreshAuth из BX24 JS SDK, но передать их на сервер все равно должен ваш код.

Тот же набор параметров Битрикс24 передает и на адрес первоначальной установки.

Когда выбрать этот вид приложенияКогда выбрать этот вид приложения

Серверное локальное приложение с пользовательским интерфейсом подходит, если нужно:

• показать свою страницу или виджет внутри Битрикс24 и обработать данные на своем сервере
• держать секретный ключ приложения и токены на сервере, а не в коде, который загружается в браузер
• получать события Битрикс24 на свой обработчик событий

Выберите другой вид приложения, если:

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

Что нужно подготовитьЧто нужно подготовить

• Доступ к REST API. Локальное приложение работает, только если у Битрикс24 есть доступ к REST API — по подписке Маркетплейс или в пробном режиме.
• Право на создание приложений. Создать приложение может администратор Битрикс24 или сотрудник, которому выдано такое право. Если пункта Локальное приложение нет в интерфейсе, попросите администратора настроить доступ к созданию приложений.
• Веб-сервер. Пример написан на PHP, поэтому нужен сервер с PHP, модулем cURL и действующим SSL-сертификатом. Страницы приложения должны быть доступны по HTTPS до того, как вы добавите приложение в Битрикс24: их адреса указывают уже в форме создания. Требования к серверу описаны в статье CRest PHP SDK: установка и первый вызов.
• Разрешение на встраивание. Битрикс24 открывает страницу приложения во фрейме, поэтому сервер не должен запрещать встраивание заголовками X-Frame-Options и Content-Security-Policy. Как разрешить встраивание для адреса своего Битрикс24, описано в статье Как исправить ошибку «Сайт не позволяет установить соединение» при открытии приложения.

Что содержит примерЧто содержит пример

Готовый пример — приложение «ФИО». Оно печатает два блока: данные запроса, которым Битрикс24 открыл страницу, включая авторизационные, и сведения о сотруднике, который открыл приложение. Эти сведения возвращает метод user.current — приложение вызывает его с токенами, которые пришли вместе со страницей.

Архив состоит из трех частей:

• SDK CRest — PHP-библиотека для вызова методов REST API. В ее поставку входят settings.php с настройками приложения, install.php для первоначальной установки и checkserver.php для проверки сервера
• модификация SDK CRest — файл crestcurrent.php с классом-наследником, который подставляет в запросы токены текущего сотрудника
• index.php — страница приложения с кодом примера, в архиве этот файл уже стоит вместо стандартного index.php из поставки CRest

Скачать архив

Класс-наследник берет токены прямо из запроса, которым Битрикс24 открыл страницу. Поэтому user.current возвращает данные текущего сотрудника. Код index.php:

<?php

require_once __DIR__ . '/crestcurrent.php';

echo '<pre>';
    print_r($_REQUEST);
echo '</pre>';

$result = CRestCurrent::call('user.current');

echo '<pre>';
    print_r($result);
echo '</pre>';

Пример собран на CRest, но сам вид приложения к этой библиотеке и к PHP не привязан. Для PHP есть и B24PhpSDK. Он оформляет вызовы как PHP-классы и методы, но требует Composer и PHP 8.2 или новее. CRest подключают файлами из архива. Остальные библиотеки перечислены в обзоре SDK.

Как создать приложениеКак создать приложение

Пример идет по сценарию с мастером установки: у приложения есть отдельная страница первоначальной установки, на которой CRest сохраняет настройки. Сам сценарий описан в статье Мастер установки локального приложения.

Битрикс24 выдает код приложения и секретный ключ только после сохранения формы, а install.php без них настройки не сохранит. Поэтому порядок такой: сначала создать приложение, затем заполнить settings.php и переустановить приложение.

1. Разместите файлы из архива на своем сервере. Запомните адреса страниц index.php и install.php: их указывают в форме.

2. Откройте в браузере checkserver.php по адресу сервера. Скрипт проверит, что модуль cURL доступен и CRest может сохранять свои файлы. Если проверка не прошла, устраните замечания скрипта до перехода к форме: CRest не сохранит настройки без cURL и без права на запись.

3. Откройте форму локального приложения: Приложения > Разработчикам, вкладка Готовые сценарии, далее Другое > Локальное приложение.

   

   

4. Выберите вариант Серверное — он открывает поля для адресов страниц на вашем сервере. Вариант Статичное рассчитан на архив со страницей — смотрите статью Статичное локальное приложение.

5. Укажите адреса страниц на своем сервере: в поле Путь для первоначальной установки — адрес install.php, в поле Путь вашего обработчика — адрес index.php. По первому адресу Битрикс24 обращается при установке приложения, по второму открывает приложение во фрейме.

6. Заполните Название пункта меню — по нему приложение находят в интерфейсе Битрикс24. В примере это «ФИО». Названия на других языках заполняют, если приложением пользуются не только на русском.

7. Выберите скоупы приложения в блоке Настройка прав. Примеру подойдет любой из скоупов пользователей: Пользователи — user, Пользователи (базовый) — user_basic, Пользователи (минимальный) — user_brief. От выбранного скоупа зависит, какие поля вернет user.current. Остальные скоупы перечислены в статье Доступные скоупы Битрикс24.

   

8. Сохраните форму. Приложение появится в списке Приложения > Разработчикам > Интеграции.

   

9. Откройте приложение. Битрикс24 покажет страницу первоначальной установки — так вы проверите, что адрес install.php доступен. Настройки на этом шаге не сохранятся. Эту страницу открывает администратор Битрикс24 или сотрудник с правом на установку приложений — остальные вместо нее увидят сообщение об ошибке.

10. Откройте карточку приложения. После сохранения в ней есть поля Код приложения (client_id) и Ключ приложения (client_secret). Скопируйте эти значения в константы C_REST_CLIENT_ID и C_REST_CLIENT_SECRET файла settings.php и загрузите измененный файл на сервер.

    

11. Нажмите Переустановить в карточке приложения и откройте приложение еще раз. Кнопка доступна только администратору Битрикс24. Теперь install.php отработает с заполненными константами и создаст settings.json. Без этого файла CRest не сможет вызвать метод.

Сценарии установки локального приложения и их отличия описаны в статье Установка локальных приложений: обзор сценариев.

Как проверить результатКак проверить результат

Найдите приложение «ФИО» в левом меню или в меню Еще раздела Приложения и запустите его. Приложение откроется во фрейме и напечатает два блока.

Первый блок — все данные запроса, которым Битрикс24 открыл страницу. $_REQUEST сводит вместе параметры из query-строки и из тела запроса, поэтому в блоке есть и авторизационные данные, и служебные:

Array
(
    [DOMAIN] => example.bitrix24.ru
    [PROTOCOL] => 1
    [LANG] => ru
    [APP_SID] => 0f5a2e9b6c1d4a8e7f30b21c5d9e4a6b
    [AUTH_ID] => a1b2c3d4e5f60718293a4b5c6d7e8f90
    [AUTH_EXPIRES] => 3600
    [REFRESH_ID] => 90f8e7d6c5b4a3928170f6e5d4c3b2a1
    [SERVER_ENDPOINT] => https://oauth.bitrix24.tech/rest/
    [APPLICATION_TOKEN] => 7d1e4c02fa93b586ce4710d2f8b3a9c5
    [APPLICATION_SCOPE] => user
    [member_id] => 4c8f2b91d7e3a56f0b1c9d8e7a6f5b43
    [status] => L
    [PLACEMENT] => DEFAULT
)

Основные параметры описаны в разделе Как работает авторизация, полный состав данных — в статье Упрощенный вариант получения токенов OAuth 2.0.

Второй блок — результат вызова user.current:

Array
(
    [result] => Array
        (
            [ID] => 1
            [ACTIVE] => 1
            [NAME] => Иван
            [LAST_NAME] => Петров
            [EMAIL] => ivan@example.com
            [LAST_LOGIN] => 2026-09-08T13:51:07+03:00
            [DATE_REGISTER] => 2020-04-20T03:00:00+03:00
            [TIME_ZONE] => Europe/Moscow
            [IS_ONLINE] => Y
            [WORK_POSITION] => Менеджер
            [UF_DEPARTMENT] => Array
                (
                    [0] => 1
                )

        )

    [time] => Array
        (
            [start] => 1788867501
            [finish] => 1788867502.0294
            [duration] => 1.0293660163879
            [processing] => 0
            [date_start] => 2026-09-08T14:38:21+03:00
            [date_finish] => 2026-09-08T14:38:22+03:00
        )

)

Данные сотрудника возвращаются в ключе result, а time добавляет к ответу сам REST API. Набор полей зависит от выбранного скоупа и от пользовательских полей Битрикс24. Пользовательские поля приходят в ключах с префиксом UF_. Полный список полей описан в статье Получить информацию о текущем пользователе user.current.

Что делать при ошибкахЧто делать при ошибках

• «Сайт не позволяет установить соединение». Сервер приложения запрещает встраивание своей страницы во фрейм. Разберите заголовки ответа по статье Как исправить ошибку «Сайт не позволяет установить соединение» при открытии приложения.
• no_install_app. В настройках CRest пусто хотя бы одно из значений access_token, domain, refresh_token, application_token, client_endpoint. Первая причина — страницу открыли напрямую по адресу сервера, без POST-запроса от Битрикс24, и подставлять в настройки оказалось нечего. Вторая — приложение не переустановили после заполнения settings.php, поэтому файл settings.json не создан.
• insufficient_scope. Приложению не выдан скоуп метода. Добавьте нужный скоуп в карточке приложения.
• expired_token. С момента открытия страницы прошло больше часа, и AUTH_ID истек. Получите новую пару токенов по REFRESH_ID — порядок описан в статье Автоматическое продление токенов OAuth 2.0.
• Вместо приложения каждый раз открывается страница установки. Скрипт первоначальной установки не вызвал BX24.installFinish — что при этом происходит, разобрано в разделе Как создать приложение.

Права и безопасностьПрава и безопасность

• Права сотрудника. Токены выданы конкретному сотруднику, поэтому вызов ограничен его правами в Битрикс24: один и тот же вызов у разных сотрудников вернет разный результат. Отличие от поведения базового CRest разобрано в разделе Как работает авторизация.
• Скоупы приложения. Набор скоупов выбирают при создании и меняют в карточке приложения.
• Секреты и токены. Код приложения, секретный ключ, AUTH_ID и REFRESH_ID храните на своем сервере. Не размещайте их в клиентском коде, который загружается в браузер, не сохраняйте в репозитории, не записывайте в логи и не передавайте третьим лицам.

Как проверить источник запросаКак проверить источник запроса

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

• эталон приложение должно сохранить при установке — в скрипте install.php или в обработчике события ONAPPINSTALL. У локального приложения это значение остается прежним, пока не меняется секретный ключ
• Битрикс24 передает текущее значение в теле каждого запроса, которым открывает страницу

Перед работой с токенами сравните эти значения и отклоните запрос, если они не совпали.

В поставке CRest install.php не сохраняет эталон, а библиотека записывает в настройку application_token значение APP_SID. Сравнение с этой настройкой не сработает, потому что APP_SID каждый раз новый. Чтобы проверка заработала, заведите свое хранилище:

1. Сохраняйте APPLICATION_TOKEN из запроса в install.php — например, в свою таблицу или файл рядом с приложением.
2. Сравнивайте на странице приложения сохраненное значение с APPLICATION_TOKEN из входящего запроса и отвечайте кодом 403, если они не совпали.

Адрес install.php тоже доступен из внешней сети. Храните эталон в недоступном извне месте и не перезаписывайте сохраненное значение при каждом обращении к странице установки.

Обработчики событий приложения проверяют источник так же, но берут значение из параметра auth.application_token, а сохраненный эталон ищут по auth.member_id — идентификатору Битрикс24. Правила хранения токена описаны в статье Безопасность в обработчиках.

Продолжите изучениеПродолжите изучение

• Локальные приложения
• Статичное локальное приложение
• Серверное локальное приложение без пользовательского интерфейса
• Работа в контексте текущего пользователя
• Упрощенный вариант получения токенов OAuth 2.0