Callback установки

Приложению без интерфейса тоже нужны токены авторизации. Callback установки — способ их получить: Битрикс24 отправляет токены на ваш обработчик сразу после того, как пользователь установит тиражное приложение.

Когда применятьКогда применять

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

Адрес обработчика указывают в карточке приложения, в поле Ссылка на обработчик события установки. Битрикс24 принимает адрес по протоколу HTTP или HTTPS. Используйте HTTPS: в запросе передаются токены.

Если при установке пользователь должен что-то настроить, callback не подойдет: у него нет интерфейса. Выберите мастер установки для приложения с интерфейсом или мастер настройки для REST-only приложений. Все способы установки сравниваются в обзоре Обзор установки тиражных приложений.

Как работаетКак работает

Битрикс24 регистрирует адрес из карточки как обработчик события и присылает на него обычный POST-запрос. В PHP поля запроса доступны в $_POST: event, data, ts и объект auth с данными авторизации OAuth 2.0. Обычно в auth есть access-токен, refresh-токен и срок жизни access-токена, но токенов в запросе может не быть.

На один адрес приходят два события:

Различайте события по полю event. Иначе приложение примет второе событие за повторную установку.

Авторизация у событий лежит в разных местах запроса:

• ONAPPINSTALL — в auth
• ONAPPUSERREADY — системного пользователя в data, сотрудника, который установил приложение, в auth

application_token для проверки подлинности есть в auth у обоих событий.

Пример запроса ONAPPINSTALL, data и auth сокращены:

$_POST = [
  'event' => 'ONAPPINSTALL',
  'event_handler_id' => '17',
  'data' => [
    // поля события
  ],
  'ts' => '1696527000',
  'auth' => [
    'access_token' => '***',
    'refresh_token' => '***',
    'expires_in' => 3600,
    'scope' => 'crm,user',
    'domain' => 'some-domain.bitrix24.ru',
    'client_endpoint' => 'https://some-domain.bitrix24.ru/rest/',
    'server_endpoint' => 'https://oauth.bitrix24.tech/rest/',
    'member_id' => '***',
    'application_token' => '***'
  ]
];

Полный состав полей описан на страницах событий.

Что вернутьЧто вернуть

Верните код 200. Установка от ответа не зависит: у приложения без интерфейса она считается завершенной сразу при добавлении. Токены сохраните на своей стороне. Access-токен живет ограниченное время и обновляется по refresh-токену.

Метод BX24.installFinish() в этом сценарии вызывать не нужно, в отличие от мастера установки. Это метод JS-библиотеки, а она работает только во фрейме интерфейса приложения. Обработчик вызывает сервер Битрикс24, браузер в этом не участвует.

Обработчик доступен по публичному адресу, поэтому запрос на него может прислать кто угодно. Убедитесь, что запрос пришел от Битрикс24:

• сверьте auth.application_token с токеном, сохраненным для этого member_id
• если сохраненного токена нет или он не совпал, проверьте access-токен методом app.info на сервере авторизации https://oauth.bitrix24.tech/rest/

Адресу Битрикс24 из запроса доверять нельзя: его задает отправитель, а адрес сервера авторизации известен заранее. Сохраненного токена нет при первой установке, а не совпасть он может после обновления: application_token при обновлении меняется. Токен передайте в параметре auth. В ответе сверьте result.client_id с client_id вашего приложения, а result.install.member_id — с member_id из запроса. Если оба совпали, сохраните новый application_token вместе с member_id. Без access-токена первый запрос проверить нечем — отклоните его.

Фрагмент ответа app.info на сервере авторизации:

{
  "result": {
    "client_id": "app.000000000000000000000000",
    "install": {
      "installed": true,
      "member_id": "a223c6b3710f85df22e9377d6c4f7553"
    }
  }
}

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

Пример разбирает событие и сохраняет токены. Проверку подлинности выполняет функция вашего приложения isRequestTrusted():

$event = $_POST['event'] ?? '';
$auth = $_POST['auth'] ?? [];
$data = $_POST['data'] ?? [];

if ($event !== 'ONAPPINSTALL' && $event !== 'ONAPPUSERREADY') {
    http_response_code(200);
    exit;
}

if (!isRequestTrusted($auth)) {
    http_response_code(403);
    exit;
}

// у ONAPPINSTALL авторизация лежит в auth, у ONAPPUSERREADY — в data
$tokens = $event === 'ONAPPUSERREADY' ? $data : $auth;

// токенов в запросе может не быть — тогда сохраненные не трогаем
if (!empty($tokens['access_token']) && !empty($tokens['refresh_token'])) {
    saveTokens($auth['member_id'], $event, [ // функция вашего хранилища
        'access_token' => $tokens['access_token'],
        'refresh_token' => $tokens['refresh_token'],
        'expires_in' => (int)($tokens['expires_in'] ?? 0),
    ]);
}

http_response_code(200);
echo 'OK';

Храните авторизации двух событий раздельно. Токены системного пользователя из ONAPPUSERREADY живут дольше и не зависят от сотрудника, который установил приложение.

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

• Обзор установки тиражных приложений
• Мастер настройки для REST-only приложений
• Событие после успешной установки приложения onAppInstall
• Событие при создании системного пользователя приложения ONAPPUSERREADY
• Безопасность в обработчиках