Разработка приложений Битрикс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 недель в зависимости от функционала.