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-застосунку вже сьогодні.