Разработка Vue.js-виджетов для Битрикс24

Разработка Vue.js-виджетов для Битрикс24

Битрикс24 — не просто CRM. Это открытая платформа с REST API, системой приложений и механизмом встраивания кастомных интерфейсов через виджеты. Виджет — это Vue.js-приложение, которое открывается внутри интерфейса Битрикс24 и расширяет его функциональность: добавляет кнопки в карточки CRM, отображает кастомные дашборды, интегрирует внешние сервисы прямо в интерфейс менеджера.

Это принципиально другой уровень работы с Битрикс24 — не настройка, а расширение платформы.

Типы встраивания виджетов

В Битрикс24 существует несколько механизмов встраивания приложений:

Слайдер — приложение открывается в боковой панели поверх интерфейса Битрикс24. Самый распространённый тип. Запускается по кнопке в правой панели портала, из меню или через BX24.openApplication().

Встраивание в карточку CRM — вкладка или блок в карточке лида, сделки, контакта. Реализуется через REST-событие CRM_*_DETAIL_TAB. Виджет получает контекст открытой карточки (ID сущности, тип).

Контекстное меню — кнопка в контекстном меню списка сущностей CRM. Получает массив выбранных ID.

Встроенный в ленту — публикации кастомного типа в живой ленте.

Телефония — кнопки и интерфейс в карточке звонка.

Каждый тип встраивания регистрируется через rest_app_event при установке приложения. Конфигурация хранится на стороне Битрикс24, сам код виджета — на внешнем сервере.

Архитектура Vue-виджета

Vue-виджет для Битрикс24 — это Vue 3-приложение, которое:

1. Встраивается в iframe Битрикс24 (или открывается как слайдер).
2. Взаимодействует с Битрикс24 через JS SDK (BX24.js).
3. Работает с данными через REST API Битрикс24.

Инициализация BX24 SDK:

import { createApp } from 'vue';
import App from './App.vue';

document.addEventListener('DOMContentLoaded', () => {
    BX24.init(() => {
        const app = createApp(App);
        app.provide('bx24', BX24);
        app.mount('#app');
    });
});

Получение контекста из карточки CRM:

// В компоненте
const bx24 = inject('bx24');
const placement = bx24.placement.info();

// placement.options содержит ID открытой сущности
const dealId = placement.options.ID;

// Запрос данных сделки через REST
bx24.callMethod('crm.deal.get', { id: dealId }, (result) => {
    dealData.value = result.data();
});

Вызов REST API батчами — для эффективных запросов:

bx24.callBatch({
    deal: ['crm.deal.get', { id: dealId }],
    contacts: ['crm.deal.contact.items.get', { id: dealId }],
    products: ['crm.deal.productrows.get', { id: dealId }],
}, (results) => {
    deal.value = results.deal.data();
    contacts.value = results.contacts.data();
    products.value = results.products.data();
});

Разработка OAuth-приложения vs Webhook

Для виджетов, которые нужно устанавливать у множества клиентов — разрабатывается OAuth-приложение с регистрацией в Маркетплейсе Битрикс24. Для внутрикорпоративного использования — достаточно локального приложения через вебхук.

Разница существенна архитектурно:

• Webhook — статичный токен, привязан к конкретному порталу, не требует OAuth-флоу.
• OAuth-приложение — требует хранения токенов (access_token / refresh_token) на стороне сервера приложения, логику обновления токенов, установку через Маркетплейс.

Для корпоративных виджетов (только для одной компании) — вебхук проще и быстрее. Для коммерческого продукта — OAuth.

Кейс: виджет расчёта стоимости доставки в карточке сделки

Клиент — логистическая компания. Задача: менеджеры должны видеть стоимость доставки прямо в карточке сделки Битрикс24, без перехода в стороннюю систему расчёта.

Решение: Vue-виджет в виде вкладки в карточке сделки.

Логика работы:

1. Виджет открывается в карточке сделки и читает из неё адрес доставки (кастомное поле UF_CRM_DEAL_DELIVERY_ADDRESS) и вес груза (UF_CRM_DEAL_WEIGHT).
2. Vue-приложение отправляет запрос к внутреннему API расчёта стоимости (REST-сервис на Laravel).
3. Отображает тарифную таблицу: по видам транспортировки (автотранспорт, авиа, ЖД), срокам и стоимости.
4. Менеджер выбирает подходящий вариант — кнопка «Сохранить» записывает стоимость в поле сделки через crm.deal.update.

Технический стек:

• Vue 3 + Composition API
• BX24.js SDK для взаимодействия с Битрикс24
• Axios для запросов к API расчёта
• Vite для сборки
• Приложение размещено на отдельном хосте (widget.company.ru), Битрикс24 открывает его в iframe

Разработка заняла 12 рабочих дней: настройка приложения в Битрикс24, разработка Vue-компонента, интеграция с API расчёта, тестирование в тестовом портале, деплой.

Особенности безопасности

Виджет открывается в iframe на домене, отличном от портала Битрикс24. Нужно учесть:

• CORS — REST API бэкенда должен разрешать запросы с домена Битрикс24-портала клиента.
• Верификация запросов — при использовании webhook нужно проверять подпись запросов через application_token.
• iframe политики — заголовок X-Frame-Options бэкенда должен разрешать встраивание в Битрикс24-домен.

Сроки

Корпоративный виджет (один тип встраивания, вебхук) — 8–15 дней: проектирование, разработка Vue-компонента, интеграция с BX24 SDK, тестирование. OAuth-приложение для Маркетплейса с несколькими типами встраивания — 3–8 недель с учётом серверной части, OAuth-флоу, документации и прохождения проверки Маркетплейса.

Битрикс24 — закрытая система с ограниченными точками расширения интерфейса. Но эти точки есть: встроенные приложения, кастомные вкладки в карточках CRM, виджеты в левой панели, кнопки на ленте. Разработка виджетов на Vue.js позволяет встроить в интерфейс Битрикс24 собственный функционал — калькуляторы, подборщики, дашборды, интеграционные панели.

Как устроены приложения и виджеты в Битрикс24

Битрикс24 предоставляет несколько механизмов встраивания:

Встроенные приложения (Embedded Apps). Приложение открывается в iframe внутри интерфейса Битрикс24. Размещается в левой панели навигации, во всплывающем окне или как отдельная вкладка. Общается с Битрикс24 через JS SDK (BX24.js).

Виджеты в карточках CRM. Через CRM Detail Tab — кастомная вкладка в карточке лида, сделки, контакта, компании. Отображается как iframe с вашим приложением, получает контекст (ID сущности, данные) через BX24.placement.info().

Коробочный Битрикс24. Для on-premise установки доступны дополнительные точки встраивания через PHP-хуки и кастомные компоненты. Но web-приложения через REST/iframe работают везде — и в облаке, и в коробке.

Битрикс24 Маркетплейс. Виджет может быть опубликован как приложение в Маркетплейс и использоваться другими компаниями.

BX24.js SDK: взаимодействие с платформой

Vue-виджет общается с Битрикс24 через BX24.js — официальный JavaScript SDK. Ключевые методы:

// Инициализация приложения
BX24.init(() => {
  // Получение контекста плейсмента
  const placement = BX24.placement.info()
  // placement.options.ID - ID сущности CRM
  
  // Вызов REST API
  BX24.callMethod('crm.deal.get', { id: placement.options.ID }, (result) => {
    if (result.error()) console.error(result.error())
    else console.log(result.data())
  })
})

// Изменение размера iframe
BX24.fitWindow()

// Открытие диалога выбора пользователя
BX24.selectUser((user) => {
  console.log(user.id, user.name)
})

В Vue 3 оборачиваем BX24 в composable:

// composables/useBX24.js
export function useBX24() {
  const callMethod = (method, params) => new Promise((resolve, reject) => {
    BX24.callMethod(method, params, (result) => {
      if (result.error()) reject(result.error())
      else resolve(result.data())
    })
  })
  
  const placementInfo = () => BX24.placement.info()
  
  return { callMethod, placementInfo }
}

Архитектура Vue-виджета

Стандартная структура проекта:

/src
  /components       # UI-компоненты виджета
  /composables      # useBX24, useDeals, useContacts
  /stores           # Pinia stores для состояния
  /views            # Страницы/состояния виджета
  App.vue
  main.js
/public
  index.html        # Входная точка iframe

Виджет собирается через Vite в статические файлы и деплоится на сервер с HTTPS. Битрикс24 открывает index.html в iframe.

Важно: Битрикс24 требует HTTPS для всех встроенных приложений. Локальная разработка — через ngrok или локальный SSL.

Кейс: виджет калькулятора стоимости в карточке сделки

Клиент — транспортная компания, Битрикс24 облако. В карточке сделки менеджеры вручную считали стоимость перевозки: расстояние × тариф × коэффициент загрузки × надбавка за тип груза. Ошибались, пересчитывали, суммы в сделках расходились с реальными счётами.

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

Реализация:

Плейсмент: CRM_DEAL_DETAIL_TAB — кастомная вкладка в карточке сделки.

При открытии виджет:

1. Получает ID сделки через BX24.placement.info()
2. Подтягивает данные сделки через crm.deal.get — поля маршрута, типа груза, веса
3. Обращается к собственному API за тарифами (тарифная сетка хранилась во внешней БД)
4. Рассчитывает стоимость в реальном времени при изменении параметров
5. Кнопка «Применить» записывает рассчитанную сумму обратно через crm.deal.update

Интерфейс калькулятора: Vue 3 + Pinia для хранения состояния, <Suspense> для загрузочного состояния пока подтягиваются данные сделки.

Дополнительно: виджет показывал историю расчётов для этой сделки — хранилась в кастомном поле типа «строка» в виде JSON.

После внедрения ошибки в суммах сделок сократились до нуля. Менеджеры перестали держать Excel-калькулятор рядом с CRM.

Публикация и деплой

Виджет для одной компании (не Маркетплейс):

1. Создаётся «Локальное приложение» в настройках Битрикс24
2. Указывается URL обработчика (адрес задеплоенного index.html)
3. Настраиваются плейсменты и права доступа
4. Разработчик получает client_id и client_secret для OAuth

Деплой: статика на S3 + CloudFront или на отдельный VPS с nginx. CI/CD через GitHub Actions: push в main → сборка Vite → деплой на сервер.

Сроки

Простой виджет (одна вкладка CRM, чтение/запись данных сделки) — 5–10 рабочих дней. Сложный виджет с собственным бекендом, историей, интеграцией с внешними API — 15–30 рабочих дней.