REST-приложения Битрикс24 на TypeScript под ключ

Проблема: отсутствие типов в 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.js SDK.
• Серверное приложение — PHP/Node.js, работает независимо, обменивается с Битрикс24 через REST поверх OAuth.
• Виджет — компактное приложение в sidebar или CRM.

TypeScript применим во всех трёх случаях, но с разными точками входа.

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); }); 

Процесс работы

1. Аналитика — изучаем бизнес-логику, выявляем сущности CRM, определяем частоту запросов к API.
2. Проектирование — создаём типы для BX24 SDK и всех CRM-сущностей, планируем batch-запросы.
3. Разработка — пишем обёртки callMethod и callBatch, React-компоненты, настраиваем OAuth-авторизацию.
4. Тестирование — проверяем типы, пагинацию, обработку ошибок, производительность batch.
5. Деплой — размещаем приложение в Битрикс24, настраиваем права доступа, документируем API.

Что входит в работу

• Полная типизация BX24 SDK и используемых CRM-сущностей.
• Автоматическая пагинация обёрток callMethod.
• Batch-оптимизация для высоконагруженных запросов.
• React-компоненты с адаптивной вёрсткой под iframe.
• Документация по интеграции и API.
• Поддержка в течение 1 года.

Типичные ошибки и чек-лист

• Неправильные типы для BX24.getAuth(): возвращаемые поля могут отсутствовать при первом вызове — используем Partial<BX24Auth>.
• Отсутствие таймаутов для callMethod: при большом количестве запросов API может сбросить соединение — мы добавляем повторные попытки.
• Неполные типы пользовательских полей: UF_* поля нужно описывать вручную, иначе они останутся any.

Сроки

Мы работаем с REST API Битрикс24 более 5 лет. Оценим ваш проект за 2 дня. Свяжитесь с нами — получите консультацию и коммерческое предложение без обязательств. Закажите разработку вашего REST-приложения уже сегодня.