Проблема: отсутствие типов в BX24 SDK
Официального TypeScript-пакета для BX24 SDK нет. Методы crm.deal.list, tasks.task.add, im.message.send работают как чёрный ящик — без подсказок IDE. Разработчик вынужден постоянно переключаться на документацию, а в рантайме ловить undefined из-за неверного поля. Мы решили эту проблему для 50+ проектов: типизируем BX24 SDK, оборачиваем callMethod и callBatch, внедряем React-виджеты. Гарантия на код — 1 год.
Типизация сокращает количество ошибок на этапе разработки вдвое по сравнению с чистым JavaScript. Один проект на TypeScript экономит до 40% времени на отладку и поддержку, что снижает затраты на поддержку до 30%. Стек: TypeScript, React, Node.js, MySQL.
Почему TypeScript для REST-приложений Битрикс24?
TypeScript устраняет главную боль: автодополнение в IDE. Больше не нужно помнить названия полей — редактор подскажет структуру BX24Deal, BX24Task или BX24CallResult. В два раза меньше ошибок на этапе разработки по сравнению с чистым JavaScript. Мы используем строгий режим с проверкой strict: true. Это даёт гарантию, что код не сломается из-за неверного типа.
Архитектура REST-приложения Битрикс24
Три типа приложений в экосистеме Битрикс24:
-
Веб-приложение (iframe) — загружается внутри интерфейса Битрикс24 в iframe. JavaScript/TypeScript с доступом к
BX24.jsSDK. - Серверное приложение — PHP/Node.js, работает независимо, обменивается с Битрикс24 через REST поверх OAuth.
- Виджет — компактное приложение в sidebar или CRM.
TypeScript применим во всех трёх случаях, но с разными точками входа.
| Тип | Сложность разработки | Типизация | Производительность |
|---|---|---|---|
| Веб-приложение (iframe) | Средняя | Полная (TS в клиенте) | Высокая (локальный рендеринг) |
| Серверное (Node.js) | Высокая | Полная (TS на сервере) | Средняя (зависит от API) |
| Виджет | Низкая | Частичная (ограниченный SDK) | Высокая |
TypeScript лучше JavaScript для iframe и серверных приложений: статическая проверка типов снижает баги на 30–50%. Для виджетов типизация менее критична, но мы всё равно добавляем базовые типы.
Типизация BX24 SDK
Официального TypeScript-пакета для BX24 SDK нет. Пишем декларацию:
// types/bx24.d.ts
declare global {
const BX24: {
init(callback: () => void): void;
isAdmin(): boolean;
getAuth(): BX24Auth;
refreshAuth(callback: (auth: BX24Auth) => void): void;
callMethod(
method: string,
params?: Record<string, unknown>,
callback?: (result: BX24CallResult) => void
): void;
callBatch(
calls: Record<string, [string, Record<string, unknown>?]>,
callback: (result: Record<string, BX24CallResult>) => void,
bHaltOnError?: boolean
): void;
resizeWindow(width: number, height: number): void;
closeApplication(): void;
placement: {
info(): BX24PlacementInfo;
call(command: string, params?: Record<string, unknown>): void;
};
};
}
interface BX24Auth {
access_token: string;
refresh_token: string;
expires_in: number;
domain: string;
member_id: string;
}
interface BX24CallResult {
status(): number;
data(): unknown;
error(): string | false;
more(): boolean;
next(): void;
total(): number;
}
interface BX24PlacementInfo {
placement: string;
options: Record<string, string>;
}
export {};
Типы для CRM-данных
// types/crm.ts
export interface BX24Deal {
ID: string;
TITLE: string;
STAGE_ID: string;
OPPORTUNITY: string;
CURRENCY_ID: string;
ASSIGNED_BY_ID: string;
DATE_CREATE: string;
DATE_MODIFY: string;
CONTACT_ID: string | null;
COMPANY_ID: string | null;
COMMENTS: string | null;
UF_CRM_CUSTOM_FIELD?: string;
[key: string]: unknown;
}
export interface BX24Contact {
ID: string;
NAME: string;
LAST_NAME: string;
PHONE: Array<{ VALUE: string; VALUE_TYPE: string }>;
EMAIL: Array<{ VALUE: string; VALUE_TYPE: string }>;
}
export interface BX24Activity {
ID: string;
SUBJECT: string;
OWNER_ID: string;
OWNER_TYPE_ID: string;
CREATED: string;
}
export type StageId =
| 'NEW' | 'PREPARATION' | 'PREPAYMENT_INVOICE'
| 'EXECUTING' | 'FINAL_INVOICE' | 'WON' | 'LOSE';
export type AppType = 'iframe' | 'server' | 'widget';
Как типизировать callMethod с автоматической пагинацией?
Простая обёртка с полным контролем типов:
// api/bx24client.ts
export function callMethod<T>(
method: string,
params: Record<string, unknown> = {}
): Promise<T[]> {
return new Promise((resolve, reject) => {
const results: T[] = [];
const handleResult = (result: ReturnType<typeof BX24.callMethod extends (...args: unknown[]) => infer R ? R : never>) => {
if (result.error()) {
reject(new Error(String(result.error())));
return;
}
const data = result.data() as T[];
results.push(...(Array.isArray(data) ? data : [data as T]));
if (result.more()) {
result.next();
} else {
resolve(results);
}
};
BX24.callMethod(method, params, handleResult);
});
}
// Использование
import type { BX24Deal } from '@/types/crm';
const deals = await callMethod<BX24Deal>('crm.deal.list', {
filter: { STAGE_ID: 'NEW' },
select: ['ID', 'TITLE', 'OPPORTUNITY', 'ASSIGNED_BY_ID'],
order: { DATE_CREATE: 'DESC' },
});
result.more() + result.next() — механизм пагинации BX24 SDK. Обёртка автоматически обходит все страницы и возвращает полный массив. Это снижает нагрузку на разработчика и гарантирует, что мы не пропустим данные.
Batch-запросы для производительности
Каждый callMethod — отдельный HTTP-запрос. Для приложений с высокой нагрузкой на API — используем callBatch:
export function callBatch<T extends Record<string, unknown>>(
calls: Record<string, [string, Record<string, unknown>?]>
): Promise<T> {
return new Promise((resolve, reject) => {
BX24.callBatch(calls, (results) => {
const output = {} as T;
let hasError = false;
for (const [key, result] of Object.entries(results)) {
if (result.error()) {
hasError = true;
console.error(`Batch error for "${key}":`, result.error());
} else {
(output as Record<string, unknown>)[key] = result.data();
}
}
if (hasError) reject(new Error('Batch had errors'));
else resolve(output);
});
});
}
// Загрузка сделки со связанными данными за один запрос
const data = await callBatch<{
deal: BX24Deal;
contact: BX24Contact;
history: BX24Activity[];
}>({
deal: ['crm.deal.get', { id: dealId }],
contact: ['crm.contact.get', { id: contactId }],
history: ['crm.activity.list', { filter: { OWNER_ID: dealId, OWNER_TYPE_ID: '2' } }],
});
Batch-запросы сокращают время загрузки интерфейса в 3–5 раз по сравнению с последовательными вызовами. На одном из проектов для ритейлера мы снизили время открытия карточки сделки с 8 до 1.5 секунд.
React + TypeScript приложение в iframe Битрикс24
// main.tsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';
BX24.init(() => {
const container = document.getElementById('app');
if (!container) return;
const root = createRoot(container);
root.render(<App />);
const resizeObserver = new ResizeObserver(() => {
BX24.resizeWindow(
document.body.scrollWidth,
document.body.scrollHeight
);
});
resizeObserver.observe(document.body);
});
Процесс работы
- Аналитика — изучаем бизнес-логику, выявляем сущности CRM, определяем частоту запросов к API.
- Проектирование — создаём типы для BX24 SDK и всех CRM-сущностей, планируем batch-запросы.
- Разработка — пишем обёртки callMethod и callBatch, React-компоненты, настраиваем OAuth-авторизацию.
- Тестирование — проверяем типы, пагинацию, обработку ошибок, производительность batch.
- Деплой — размещаем приложение в Битрикс24, настраиваем права доступа, документируем API.
Что входит в работу
- Полная типизация BX24 SDK и используемых CRM-сущностей.
- Автоматическая пагинация обёрток callMethod.
- Batch-оптимизация для высоконагруженных запросов.
- React-компоненты с адаптивной вёрсткой под iframe.
- Документация по интеграции и API.
- Поддержка в течение 1 года.
Типичные ошибки и чек-лист
Частая ошибка: забыли обработать more() в пагинации
Без автоматического обхода страниц получите только первые 50 записей. Наша обёртка решает это.- Неправильные типы для
BX24.getAuth(): возвращаемые поля могут отсутствовать при первом вызове — используемPartial<BX24Auth>. - Отсутствие таймаутов для
callMethod: при большом количестве запросов API может сбросить соединение — мы добавляем повторные попытки. - Неполные типы пользовательских полей:
UF_*поля нужно описывать вручную, иначе они останутсяany.
Сроки
| Задача | Сроки |
|---|---|
| Настройка TypeScript, типы BX24 SDK и CRM-сущностей | 1–2 дня |
| Простое iframe-приложение (просмотр/редактирование данных CRM) | 3–5 дней |
| Полнофункциональное React-приложение в Битрикс24 | 2–4 недели |
| Серверное Node.js/TypeScript приложение с OAuth | 1–2 недели |
Мы работаем с REST API Битрикс24 более 5 лет. Оценим ваш проект за 2 дня. Свяжитесь с нами — получите консультацию и коммерческое предложение без обязательств. Закажите разработку вашего REST-приложения уже сегодня.