← Назад к справке

REST

Локальные приложения и авторизация

Рабочая справка по локальным приложениям Bitrix24 REST: OAuth, BX24.init, BX24.install, BX24.getAuth, access_token и вызов REST.

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

Локальное приложение

Локальное приложение работает в конкретном портале и открывается внутри Bitrix24 в iframe.

Когда нужно приложение

Нужно приложение Можно вебхук
Нужен интерфейс в Bitrix24. Нужен серверный скрипт без UI.
Нужны виджеты и placement. Нужен простой обмен с CRM.
Нужна OAuth-авторизация. Достаточно постоянного URL вебхука.
Нужны методы, работающие только в контексте приложения. Метод поддерживает вызов через вебхук.

Что получает приложение

При открытии приложения Bitrix24 передаёт данные для работы: домен портала, авторизационные данные, пользователя и контекст запуска. В JS это обычно получают через BX24.init() и связанные методы SDK.

Сервер приложения

Для локального приложения нужен URL обработчика. Он должен быть доступен Bitrix24 по HTTPS, если приложение использует события, установку, виджеты или серверные callback.

BX24 JS SDK

В интерфейсных приложениях обычно используется библиотека BX24.

BX24.init

BX24.init() выполняет код после готовности библиотеки и получения данных от родительского фрейма Bitrix24. 

document.addEventListener('DOMContentLoaded', function () {
    BX24.init(function () {
        console.log('BX24 initialized');

        BX24.callMethod('user.current', {}, function (result) {
            if (result.error()) {
                console.error(result.error());
                return;
            }

            console.log(result.data());
        });
    });
});

BX24.install

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

BX24.install(function () {
    BX24.callMethod('user.current', {}, function (result) {
        if (result.error()) {
            console.error(result.error());
            BX24.installFinish();
            return;
        }

        console.log('Installed for user:', result.data());

        BX24.installFinish();
    });
});

Если используется BX24.install(), после завершения нужно вызвать BX24.installFinish(), иначе установка может считаться незавершённой.

BX24.getAuth

BX24.getAuth() возвращает данные OAuth-авторизации, которые можно передать на свой сервер, если серверу нужно вызывать REST от имени текущего пользователя. 

BX24.init(function () {
    var auth = BX24.getAuth();

    console.log(auth);
});

OAuth

Приложения используют временный OAuth-токен, а не постоянный код вебхука.

access_token и refresh_token

access_token используется для вызова REST. Когда он истекает, приложение обновляет его через refresh_token. Готовые SDK обычно берут эту работу на себя.

Вызов REST с токеном

<?php

const BITRIX24_DOMAIN = 'portal.bitrix24.ru';

/**
 * Вызывает REST-метод с OAuth-токеном.
 */
function callBitrix24RestWithToken(string $method, string $access_token, array $parameters = []): array
{
    $url = 'https://' . BITRIX24_DOMAIN . '/rest/' . $method . '.json';

    $parameters['auth'] = $access_token;

    $curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_URL => $url,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($parameters),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
    ]);

    $response_body = curl_exec($curl);
    $curl_error = curl_error($curl);

    curl_close($curl);

    if ($response_body === false) {
        return [
            'is_success' => false,
            'error_messages' => [$curl_error],
            'data' => null,
        ];
    }

    $response_data = json_decode($response_body, true);

    return [
        'is_success' => empty($response_data['error']),
        'error_messages' => !empty($response_data['error_description'])
            ? [$response_data['error_description']]
            : [],
        'data' => $response_data,
    ];
}

$result = callBitrix24RestWithToken(
    'user.current',
    $access_token
);

print_r($result);

Источники