Розробка 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-хуки та кастомні компоненти. Але веб-застосунки через 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 робочих днів.