Розробка програм Бітрікс24 на React

Розробка застосунків Бітрікс24 на React

Застосунки Бітрікс24 — це зовнішні веб-застосунки, що вбудовуються в інтерфейс порталу через iframe або відкриваються в окремій вкладці. Вони працюють через REST API Бітрікс24, отримують контекст користувача через BX24.js SDK і можуть вбудовуватись у різні місця інтерфейсу: бокова панель CRM, картка ліда, шапка порталу, окрема сторінка застосунку.

React — природний вибір для таких застосунків: компонентний підхід, багата екосистема, TypeScript-типізація REST API Бітрікс24.

Типи застосунків та їх архітектура

Вбудовані (embedded) застосунки — відображаються всередині інтерфейсу Бітрікс24 в iframe. Розмір фіксований або адаптивний через BX24.resizeWindow(). Доступні місця вбудовування: CRM_LEAD_DETAIL_TAB, CRM_DEAL_DETAIL_TAB, TASKS_TASK_VIEWFORM_SIDEBAR та десятки інших.

Standalone-застосунки — відкриваються на окремій сторінці в рамках Бітрікс24 (/apps/). Повноцінний SPA з власним роутингом.

Віджети — невеликі компоненти, що вбудовуються в конкретні картки. Наприклад, віджет у картці угоди, що показує історію поставок із зовнішньої ERP.

// Ініціалізація BX24 у React-застосунку
import { useEffect, useState } from 'react';

declare global {
  interface Window { BX24: any; }
}

function useBX24Init() {
  const [isReady, setIsReady] = useState(false);
  const [user, setUser] = useState(null);

  useEffect(() => {
    window.BX24.init(() => {
      setIsReady(true);
      window.BX24.callMethod('profile', {}, (result: any) => {
        setUser(result.data());
      });
    });
  }, []);

  return { isReady, user };
}

Аутентифікація та REST API

Авторизація в застосунку — через OAuth 2.0. Бітрікс24 видає access_token при відкритті застосунку в iframe (через postMessage або URL-параметри). Для серверних запитів (backend-to-Bitrix24) — авторизація через client_id + client_secret + webhook.

Типова архітектура: React-фронт робить запити до власного бекенду (не напряму в Бітрікс24), бекенд проксує до Бітрікс24 REST API з серверним токеном. Це приховує токени від браузера і дозволяє кешувати повторювані запити.

// React-хук для виклику Бітрікс24 REST через BX24.js (клієнтська сторона)
function useBX24Method<T>(method: string, params: object) {
  return useQuery({
    queryKey: ['bx24', method, params],
    queryFn: () =>
      new Promise<T>((resolve, reject) => {
        window.BX24.callMethod(method, params, (result: any) => {
          if (result.error()) reject(result.error());
          else resolve(result.data());
        });
      }),
    staleTime: 30_000,
  });
}

// Використання
const { data: deals } = useBX24Method<Deal[]>('crm.deal.list', {
  select: ['ID', 'TITLE', 'STAGE_ID', 'OPPORTUNITY'],
  filter: { ASSIGNED_BY_ID: currentUserId },
  order:  { DATE_MODIFY: 'DESC' },
});

Bitrix24 UI Kit у React

Бітрікс24 надає офіційний @bitrix24/b24jssdk і UI Kit на основі React-компонентів. Використання UI Kit забезпечує візуальну консистентність з інтерфейсом Бітрікс24 — застосунок виглядає як рідна частина порталу.

Компоненти UI Kit: Button, Input, Select, Table, Modal, Notification, Avatar, Badge. Стилізація через CSS-змінні — автоматично адаптується під тему порталу (світла/темна).

Кейс: застосунок для контролю SLA в CRM

Компанія B2B-послуг, 45 менеджерів, угоди проходять через 8 стадій. Завдання: віджет у картці угоди, що показує, скільки часу угода перебуває на поточній стадії, прапор порушення SLA (якщо більше норми), історія переходів за стадіями.

Штатний Бітрікс24 не має SLA-контролю в CRM Deal з коробки.

Реалізація:

Бекенд — Laravel (окремий сервер). При кожній зміні стадії угоди — вебхук від Бітрікс24 (event: ONCRMDEALUPDATE) записує перехід у таблицю deal_stage_history з мітками часу.

React-віджет вбудований у CRM_DEAL_DETAIL_TAB. При відкритті картки — запит на власний бекенд з DEAL_ID, який повертає: поточна стадія, час на стадії, SLA-норма для цієї стадії, статус (у нормі / порушено), список переходів.

Візуалізація: таймлайн стадій із кольоровою індикацією. Червоний — SLA порушено, жовтий — 75% часу використано, зелений — у нормі.

function SlaWidget({ dealId }: { dealId: number }) {
  const { data } = useSlaData(dealId);

  if (!data) return <Spinner />;

  return (
    <div className="sla-widget">
      <SlaTimer
        currentStage={data.currentStage}
        timeOnStage={data.timeOnStage}
        slaLimit={data.slaLimit}
        status={data.status}
      />
      <StageTimeline history={data.stageHistory} />
    </div>
  );
}

Сповіщення: при порушенні SLA бекенд надсилає сповіщення відповідальному менеджеру та його керівнику через im.notify.system.add REST API.

Вебхуки та real-time оновлення

Застосунки Бітрікс24 можуть підписуватись на події через вебхуки: зміна угод, завдань, контактів. Це дозволяє будувати застосунки з near-real-time оновленнями.

Для real-time у React — Server-Sent Events (SSE) або polling. WebSocket поверх Бітрікс24 — тільки через BX24.callMethod('pull.application.event.add') з модулем Push & Pull.

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

Застосунок реєструється в Маркетплейс Бітрікс24 або встановлюється напряму на конкретний портал. Для корпоративних рішень — другий варіант: застосунок деплоїться на власний сервер, реєструється через Налаштування → Застосунки → Додати застосунок.

HTTPS обов'язковий — Бітрікс24 не завантажує HTTP-контент в iframe.

Склад робіт

• Проєктування: місце вбудовування, API-методи, схема авторизації
• Реєстрація застосунку в Бітрікс24, налаштування OAuth
• Розробка бекенду: проксі REST, бізнес-логіка, вебхуки
• Розробка React SPA: компоненти, стейт, інтеграція з BX24.js
• Тестування на реальному порталі Бітрікс24, edge cases авторизації

Терміни: простий віджет-вставка — 1–2 тижні. Повноцінний standalone-застосунок із власним бекендом — 4–12 тижнів залежно від функціоналу.