Разработка встраиваемых приложений Битрикс24

Разработка встраиваемых приложений Битрикс24

Встраиваемые приложения — это не просто «окно в iframe». Когда менеджер работает в карточке сделки и видит вкладку с историей отгрузок из вашей WMS, с возможностью прямо там создать новый заказ — это результат правильно построенного встраиваемого приложения. Разница с обычным виджетом в том, что встраиваемое приложение имеет двустороннее взаимодействие с интерфейсом Битрикс24 и может управлять его состоянием.

Что такое встраиваемое приложение в терминологии Bitrix24

В документации Bitrix24 встраиваемые приложения (Embedded Apps) — это приложения с типом IFRAME, которые регистрируют плейсменты и работают внутри интерфейса портала. В отличие от внешних (серверных) приложений, они имеют прямой доступ к JS SDK BX24 и могут:

• читать и изменять поля открытой карточки CRM в реальном времени без перезагрузки
• вызывать диалоги, слайдеры и уведомления Битрикс24 (BX24.openPath, BX24.showMessagePopup)
• подписываться на события интерфейса через BX24.placement.call('getInterface', ...)

Жизненный цикл и авторизация

При открытии вкладки с приложением Битрикс24 формирует iframe-запрос к вашему handler URL с параметрами:

GET https://your-app.com/handler?
    DOMAIN=company.bitrix24.ru&
    PROTOCOL=1&
    AUTH_ID=abc123&
    AUTH_EXPIRES=3600&
    REFRESH_ID=xyz789&
    member_id=a1b2c3&
    PLACEMENT=CRM_DEAL_DETAIL_TAB&
    PLACEMENT_OPTIONS={"ID":"42","SECTION":""}

AUTH_ID живёт 1 час. Для долгоживущих сессий (пользователь оставил вкладку открытой) нужен refresh:

BX24.init(() => {
    // Автоматически обновляет токен если он истёк
    BX24.getAuth((auth) => {
        // auth.access_token — актуальный токен
        fetch('/api/data', {
            headers: { 'X-Bitrix-Auth': auth.access_token }
        });
    });
});

На вашем сервере проверяйте токен через:

GET https://company.bitrix24.ru/rest/profile?auth=ACCESS_TOKEN

Взаимодействие с CRM-карточкой в реальном времени

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

Подписка на изменение поля в карточке:

BX24.placement.call('bindEvent', {
    event: 'onCrmBindEntityUpdated'
}, (eventData) => {
    // Вызывается когда пользователь сохраняет карточку
    const entityId = eventData.ENTITY_ID;
    refreshWidgetData(entityId);
});

Программное изменение поля карточки (без сохранения — только визуально):

BX24.placement.call('setFieldValue', {
    FIELD: 'UF_CRM_CUSTOM_STATUS',
    VALUE: 'shipped'
}, () => {
    console.log('Поле обновлено в интерфейсе');
});

Полный список событий и методов placement зависит от типа карточки (CRM_DEAL, CRM_LEAD, CRM_CONTACT, CRM_COMPANY) — у каждой своя документация.

Структура проекта встраиваемого приложения

Минимальная структура:

/app
  /public
    index.html        # Точка входа (handler URL)
    app.js            # Клиентский код с BX24 SDK
  /src
    /api
      bitrix.js       # Обёртка над BX24.callMethod
      external.js     # Запросы к внешнему API
    /components
      DealTab.jsx     # React/Vue/Vanilla — что угодно
  server.js           # Express/Fastify для OAuth callback и API proxy

Почему нужен серверный компонент даже для "клиентского" приложения: OAuth callback (/oauth/callback) должен обрабатываться на сервере, client_secret нельзя выносить в браузер, проксирование запросов к внешним API избегает CORS-проблем.

Работа с событиями через BX24.placement

Разные плейсменты предоставляют разный набор методов. Для CRM_DEAL_DETAIL_TAB:

// Получить интерфейс текущего плейсмента
BX24.placement.call('getInterface', {}, (interfaceData) => {
    /*
    interfaceData содержит:
    {
        ID: "42",           // ID сделки
        ENTITY_TYPE: "CRM_TYPE_DEAL",
        FIELDS: { ... },   // Текущие значения полей
        BUTTONS: [ ... ]   // Доступные кнопки
    }
    */
});

Публикация и установка

Встраиваемые приложения могут быть:

1. Локальными — доступны только на одном портале, устанавливаются через настройки разработчика
2. Тиражными — публикуются в Битрикс24 Маркете, проходят модерацию

Для локальной установки достаточно зарегистрировать приложение в /devops/ и указать handler URL. Для тиражного — нужен SSL, корректный manifest.json и прохождение ревью Bitrix.

Тестирование

Самая частая проблема при разработке — отладка внутри iframe. Браузерные DevTools не открываются в контексте iframe Битрикс24 напрямую. Решения:

• Открывайте handler URL напрямую в браузере с mock-параметрами для отладки UI
• Используйте ngrok или localtunnel для локального сервера с HTTPS (Битрикс24 требует HTTPS даже на dev)
• Логируйте через BX24.console.log() — сообщения появятся в консоли родительского окна

Сроки разработки

Критичный момент: перед стартом разработки согласуйте с заказчиком список плейсментов — добавление нового плейсмента после публикации тиражного приложения требует повторного прохождения модерации.