Инструкция для ИИ агентов: @bitrix24/b24jssdk

Краткая сводка

@bitrix24/b24jssdk — официальный JavaScript SDK для работы с REST API Bitrix24. Предназначен для создания приложений, интеграций и автоматизации бизнес-процессов в экосистеме Bitrix24.

Ключевые возможности:

🔄 Вызов REST API методов Bitrix24 (фронтенд iframe / бэкенд через webhook)
🖼️ Управление UI: слайдеры, диалоги, изменение размера фрейма, заголовки
📦 Helpers: профили, валюты, лицензии, опции, платежи
📡 Pull Client для real-time коммуникации
🔐 Автоматическое управление OAuth токенами и refresh

Версия: 0.4.10 | Лицензия: MIT | Node.js: ^18.0.0 || ^20.0.0 || >=22.0.0

⚠️ С версии 0.4.0 поддерживаются только ESM и UMD (CommonJS удален)

Установка

Node.js / Frontend (ESM)

npm install @bitrix24/b24jssdk

Browser (UMD через CDN)

<script src="https://unpkg.com/@bitrix24/b24jssdk@latest/dist/umd/index.min.js"></script>

Nuxt 3

npx nuxi module add @bitrix24/b24jssdk-nuxt

Документация:

Примеры проектов:

Основные требования для разработки

MCP server

Для уточнения методов и параметров REST API используйте Bitrix24 MCP server.
См. также: инструкция по MCP и официальная страница https://apidocs.bitrix24.ru/sdk/mcp.html

1. Выбор режима работы

B24Frame — для приложений в iframe Bitrix24

Используется для приложений, встроенных в портал Bitrix24 через placement.

import { initializeB24Frame, B24Frame } from '@bitrix24/b24jssdk'

let $b24: B24Frame
$b24 = await initializeB24Frame() // Всегда await перед использованием!

// Вызов REST API
const result = await $b24.callMethod('crm.deal.list', { select: ['ID', 'TITLE'] })

// Очистка при размонтировании
$b24.destroy()

📚 Ссылки:

B24Hook — для серверных скриптов через webhook

Используется для бэкенд-сервисов, скриптов, интеграций.

import { B24Hook } from '@bitrix24/b24jssdk'

// Создание из URL webhook
const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/k32t88gf3azpmwv3')

// Или через параметры
const $b24 = new B24Hook({
  b24Url: 'https://your_domain.bitrix24.com',
  userId: 123,
  secret: 'k32t88gf3azpmwv3'
})

$b24.offClientSideWarning() // Отключить warning о клиентской стороне (только для Node.js!)

⚠️ ВАЖНО: B24Hook НЕ использовать на фронтенде! Только на сервере/бэкенде.

📚 Ссылки:

B24OAuth — для OAuth приложений (экспериментально)

Используется для приложений с OAuth авторизацией (не стабильная реализация).

import { B24OAuth } from '@bitrix24/b24jssdk'

const $b24 = new B24OAuth({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret'
})

// Обработка OAuth колбэка
await $b24.auth.handleOAuthCallback(callbackParams)

⚠️ ВНИМАНИЕ: B24OAuth находится в разработке. Для продакшена рекомендуется использовать B24Frame или B24Hook.

📚 Ссылки:

2. Вызов REST API методов

Базовые методы (AbstractB24)

// Одиночный вызов
const result = await $b24.callMethod('crm.deal.get', { id: 123 })

// Batch вызов (объект с ключами)
const batch = await $b24.callBatch({
  deals: { method: 'crm.deal.list', params: { select: ['ID'] } },
  contacts: { method: 'crm.contact.list', params: { select: ['ID'] } }
}, true) // true = halt on error

// Batch массивом
const batch = await $b24.callBatch([
  ['crm.deal.list', { select: ['ID'] }],
  ['crm.contact.list', { select: ['ID'] }]
], true)

📚 Ссылки:

Работа с большими списками

Стратегии:

callListMethod — загружает весь список в память (< 1000 записей)
fetchListMethod — stream по чанкам (рекомендуется для больших данных)
callMethod с ручной пагинацией — полный контроль

// callListMethod (всё в память)
const list = await $b24.callListMethod('crm.deal.list', 
  { select: ['ID', 'TITLE'] },
  (progress) => console.log(`Прогресс: ${progress}%`)
)

// fetchListMethod (потоковая загрузка)
for await (const chunk of $b24.fetchListMethod('crm.item.list', {
  entityTypeId: 4, // company
  select: ['id', 'title']
}, 'id')) {
  console.log(`Получено ${chunk.length} записей`)
}

📚 Ссылки:

Примеры работы со списками

3. Обработка ошибок

import { AjaxError, AjaxResult, Result } from '@bitrix24/b24jssdk'

try {
  const response: AjaxResult = await $b24.callMethod('crm.deal.get', { id: 999 })
  
  if (response.isSuccess) {
    const data = response.getData()
  }
} catch (error) {
  if (error instanceof AjaxError) {
    console.error(`Ошибка API: ${error.code}`, error.message, error.status)
    console.error('Request:', error.requestInfo)
  }
}

📚 Ссылки:

4. Работа с UI (только B24Frame)

Слайдеры

// Открыть слайдер с порталом
const url = $b24.slider.getUrl('/crm/deal/details/123')
const result = await $b24.slider.openPath(url, 1640) // ширина

// Открыть страницу приложения в слайдере
await $b24.slider.openSliderAppPage({ customParam: 'value' })
await $b24.slider.closeSliderAppPage()

📚 Ссылки:

Диалоги

// Выбор пользователя
const user = await $b24.dialog.selectUser()
const users = await $b24.dialog.selectUsers()

📚 Ссылки:

Управление родительским окном

await $b24.parent.fitWindow() // Подогнать размер под контент
await $b24.parent.resizeWindow(800, 600)
await $b24.parent.setTitle('Мое приложение')
await $b24.parent.closeApplication()
await $b24.parent.scrollParentWindow(0)

📚 Ссылки:

Настройки приложения/пользователя

// App-level
await $b24.options.appSet('myKey', 'value')
const value = $b24.options.appGet('myKey')

// User-level
await $b24.options.userSet('theme', 'dark')
const theme = $b24.options.userGet('theme')

📚 Ссылки:

5. Helpers и Pull Client

import { useB24Helper, LoadDataType } from '@bitrix24/b24jssdk'

const {
  initB24Helper,
  getB24Helper,
  usePullClient,
  useSubscribePullClient,
  startPullClient,
  destroyB24Helper
} = useB24Helper()

// Инициализация после B24Frame
const $b24 = await initializeB24Frame()
await initB24Helper($b24, [
  LoadDataType.Profile,
  LoadDataType.App,
  LoadDataType.Currency
])

// Доступ к данным
const helper = getB24Helper()
const userId = helper.profileInfo.data.id
const currencyName = helper.currency.getCurrencyFullName('USD', 'en')

// Pull Client
usePullClient()
useSubscribePullClient((message) => {
  console.log('Pull message:', message)
}, 'application')
startPullClient()

📚 Ссылки:

6. Utilities

import { Type, Text, LoggerBrowser, EnumCrmEntityTypeId } from '@bitrix24/b24jssdk'

// Type helpers
Type.isStringFilled('test') // true
Type.isNumber(123) // true

// Text utilities
const dt = Text.toDateTime('2024-01-01T10:00:00Z') // Luxon DateTime
const uuid = Text.getUuidRfc4122()
const num = Text.numberFormat(12345.67, 2, '.', ' ') // "12 345.67"

// Logger
const logger = LoggerBrowser.build('MyApp', true) // isDev = true
logger.info('message', data)
logger.error('error', error)

📚 Ссылки:

7. Типы и Enums

SDK предоставляет типы TypeScript для всех компонентов:

import { 
  EnumCrmEntityTypeId,
  EnumCrmEntityType,
  type TypeB24,
  type AuthData,
  type AjaxResultParams
} from '@bitrix24/b24jssdk'

// Использование enum для CRM сущностей
const dealId = EnumCrmEntityTypeId.deal // 2
const companyId = EnumCrmEntityTypeId.company // 4

// TypeB24 интерфейс для типизации B24Frame/B24Hook
function processB24(b24: TypeB24) {
  // ...
}

📚 Ссылки на типы:

8. Управление лимитами REST API

SDK автоматически управляет лимитами запросов через RestrictionManager:

import { RestrictionManagerParamsForEnterprise } from '@bitrix24/b24jssdk'

// Получить HTTP клиент
const http = $b24.getHttpClient()

// Для Enterprise тарифа можно увеличить лимиты
// (автоматически делается через LicenseManager в useB24Helper)
http.setRestrictionManagerParams(RestrictionManagerParamsForEnterprise)

// Проверить текущие параметры
const params = http.getRestrictionManagerParams()

Лимиты по умолчанию:

Batch размер: 50 команд
Throttling: автоматическая задержка при превышении

📚 Ссылки:

Шаги при ошибках и сложностях

1️⃣ Изучить исходный код класса/метода

Все основные классы доступны на GitHub:

Компонент	Ссылка на исходный код
B24Frame	frame/frame.ts
B24Hook	hook/controller.ts
AbstractB24	core/abstract-b24.ts
Http	core/http/controller.ts
AjaxError	core/http/ajax-error.ts
AjaxResult	core/http/ajax-result.ts
Result	core/result.ts
RestrictionManager	core/http/restriction-manager.ts
Auth (Frame)	frame/auth.ts
Auth (Hook)	hook/auth.ts
Slider	frame/slider.ts
Dialog	frame/dialog.ts
Parent	frame/parent.ts
Placement	frame/placement.ts
Options	frame/options.ts
useB24Helper	helper/use-b24-helper.ts
B24HelperManager	helper/helper-manager.ts
CurrencyManager	helper/currency-manager.ts
ProfileManager	helper/profile-manager.ts
Pull Client	pullClient/client.ts
Types	types/

2️⃣ Проверить официальную документацию SDK

3️⃣ Обратиться к документации Bitrix24 REST API

Если проблема связана с вызовом конкретного REST метода:

4️⃣ Изучить примеры использования

5️⃣ Проверить CHANGELOG

📋 CHANGELOG.md — история изменений и breaking changes

6️⃣ Создать Issue на GitHub

Если проблема не решена:

🐛 Создать Issue

Типичные ошибки и решения

Ошибка	Причина	Решение
`B24Frame is not initialized`	Не вызван `await initializeB24Frame()`	Всегда вызывать `await initializeB24Frame()` перед использованием
`invalid_token` / `expired_token`	Токен истек	SDK автоматически обновляет токены. Проверить `$b24.auth.refreshAuth()`
`B24Hook warning on client`	Используется B24Hook на фронтенде	Переместить на сервер или использовать `B24Frame`
`Batch limit exceeded`	Слишком большой batch	Использовать `callBatchByChunk()` или уменьшить размер
`isMore() returns false`	Нет следующей страницы	Проверить условие `while (result.isMore())`

📚 Ссылки:

Дополнительные ресурсы

Официальная документация

REST API Bitrix24

📚 Документация REST API
🌐 API Reference Online

Примеры проектов

🎯 b24sdk-examples

Best Practices для ИИ агентов

Паттерны инициализации

Фронтенд (B24Frame)

import { initializeB24Frame, B24Frame } from '@bitrix24/b24jssdk'

let $b24: B24Frame

async function init() {
  try {
    $b24 = await initializeB24Frame()
    
    // Инициализация helpers (опционально)
    const { initB24Helper } = useB24Helper()
    await initB24Helper($b24, [LoadDataType.Profile, LoadDataType.App])
    
    // Ваша логика
  } catch (error) {
    console.error('Init error:', error)
  }
}

function cleanup() {
  const { destroyB24Helper } = useB24Helper()
  destroyB24Helper()
  $b24?.destroy()
}

Бэкенд (B24Hook)

import { B24Hook, LoggerBrowser } from '@bitrix24/b24jssdk'

const logger = LoggerBrowser.build('App', true)

const $b24 = B24Hook.fromWebhookUrl(process.env.B24_WEBHOOK_URL!)
$b24.setLogger(logger)
$b24.offClientSideWarning()

// Использование
async function getData() {
  try {
    const result = await $b24.callMethod('crm.deal.list', { select: ['ID'] })
    return result.getData()
  } catch (error) {
    logger.error('API error:', error)
    throw error
  }
}

Оптимизация производительности

Batch запросы — группировать связанные запросы
fetchListMethod — для больших данных использовать потоковую загрузку
RestrictionManager — автоматически управляет throttling
Кэширование — сохранять результаты через options.appSet/userSet

Версия документа: 1.0
Дата: 2025-10-23
SDK версия: 0.4.10

FilesExpand file tree

bitrix24-js-sdk.md

Latest commit

History

bitrix24-js-sdk.md

File metadata and controls

Инструкция для ИИ агентов: @bitrix24/b24jssdk

Краткая сводка

Установка

Node.js / Frontend (ESM)

Browser (UMD через CDN)

Nuxt 3

Основные требования для разработки

MCP server

1. Выбор режима работы

B24Frame — для приложений в iframe Bitrix24

B24Hook — для серверных скриптов через webhook

B24OAuth — для OAuth приложений (экспериментально)

2. Вызов REST API методов

Базовые методы (AbstractB24)

Работа с большими списками

3. Обработка ошибок

4. Работа с UI (только B24Frame)

Слайдеры

Диалоги

Управление родительским окном

Настройки приложения/пользователя

5. Helpers и Pull Client

6. Utilities

7. Типы и Enums

8. Управление лимитами REST API

Шаги при ошибках и сложностях

1️⃣ Изучить исходный код класса/метода

2️⃣ Проверить официальную документацию SDK

3️⃣ Обратиться к документации Bitrix24 REST API

4️⃣ Изучить примеры использования

5️⃣ Проверить CHANGELOG

6️⃣ Создать Issue на GitHub

Типичные ошибки и решения

Дополнительные ресурсы

Официальная документация

REST API Bitrix24

Примеры проектов

Best Practices для ИИ агентов

Паттерны инициализации

Фронтенд (B24Frame)

Бэкенд (B24Hook)

Рекомендации

Оптимизация производительности