BX24.js и B24JsSDK: какую библиотеку выбрать для приложения

Для работы с REST API из JavaScript есть два основных подхода:

• BX24.js — классическая библиотека для приложений, открытых внутри интерфейса Bitrix24;
• B24JsSDK — более новая универсальная библиотека для браузера и Node.js.

Обе могут использоваться для вызова REST-методов, но у них разная область применения. Если выбрать библиотеку не под свой сценарий, код получится неудобным или небезопасным.

В старом коде коробочного Битрикса часто встречается объект BX. Это не то же самое, что BX24.js для REST-приложений.

• BX — объект клиентского ядра Битрикса, который часто используют внутри самого портала;
• BX24 — объект JS-библиотеки для приложений Bitrix24 и работы с REST из iframe;
• B24Js — объект новой библиотеки @bitrix24/b24jssdk.

Для локального приложения, которое открывается во фрейме Bitrix24, обычно речь идёт именно о выборе между BX24.js и B24JsSDK.

BX24.js

BX24.js подключается обычным скриптом:

<script src="//api.bitrix24.com/api/v1/"></script>

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

Что обычно даёт BX24.js:

• быстрый вызов REST через BX24.callMethod;
• готовую авторизацию внутри iframe-приложения;
• методы для работы с интерфейсом Bitrix24;
• управление размером фрейма через fitWindow и resizeWindow;
• простую схему для небольших локальных приложений.

Минус — старый callback-стиль. Для небольших задач это нормально, но в большом приложении код быстро становится менее удобным.

B24JsSDK

B24JsSDK — это пакет @bitrix24/b24jssdk. Его можно подключать как UMD-скрипт или использовать через сборщик.

<script src="https://unpkg.com/@bitrix24/b24jssdk@latest/dist/umd/index.min.js"></script>

Что даёт B24JsSDK:

• работу через async/await;
• варианты для iframe-приложения, OAuth и вебхуков;
• использование в браузере и Node.js;
• более удобную основу для TypeScript и современного frontend-кода;
• логирование и дополнительные обёртки вокруг REST-вызовов.

Для нового приложения я бы сначала смотрел в сторону B24JsSDK, особенно если планируется сборка, TypeScript, отдельный backend или более сложная интеграция.

Так выглядит простой вызов REST-метода через классическую библиотеку:

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

                return;
            }

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

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

Такой же смысл, но через новую библиотеку:

<script src="https://unpkg.com/@bitrix24/b24jssdk@latest/dist/umd/index.min.js"></script>

<script type="module">
    try {
        const b24 = await B24Js.initializeB24Frame();

        const response = await b24.callMethod(
            'user.current',
            {}
        );

        console.log(response.getData().result);
    } catch (error) {
        console.error(error);
    }
</script>

Код получается ближе к обычному современному JavaScript. Его проще встроить в проект со сборкой, модулями и отдельной обработкой ошибок.

Для простого iframe-приложения

Если нужно быстро сделать вкладку, кнопку, виджет или небольшую страницу внутри Bitrix24, BX24.js всё ещё нормальный вариант.

Я бы брал BX24.js, если:

• приложение открывается только внутри Bitrix24;
• нужно быстро вызвать несколько REST-методов;
• не планируется отдельная сборка frontend-проекта;
• callback-стиль не мешает;
• нужны простые методы для управления фреймом и интерфейсом.

Для нового приложения

Для нового проекта лучше рассмотреть B24JsSDK. Особенно если приложение не ограничивается одной HTML-страницей.

Я бы смотрел в сторону B24JsSDK, если:

• проект пишется на современном JavaScript или TypeScript;
• нужен async/await вместо callback-цепочек;
• есть сборка через Vite, Webpack или другой инструмент;
• часть логики будет работать на Node.js;
• нужна более удобная структура для сложной интеграции.

Для вебхуков

Вебхуки нельзя держать во frontend-коде. Это относится и к статичным приложениям, и к приложениям на новой библиотеке.

Если используется входящий вебхук, его нужно хранить на backend-стороне. Frontend может обращаться к своему серверному обработчику, а уже сервер — к Bitrix24.

// Плохо: вебхук лежит в frontend-коде.
const webhook_url = 'https://example.bitrix24.ru/rest/1/secret/crm.deal.list.json';

// Лучше: frontend обращается к своему backend.
fetch('/local/app/ajax.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        action: 'load_deals',
    }),
});

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