Введение в работу с REST API Bitrix24

Эта страница ещё обновляется. Некоторые данные могут отсутствовать — мы их вскоре дополним.

Обзор

SDK для работы с REST API Bitrix24 предоставляет набор инструментов для взаимодействия с API Bitrix24 из JavaScript/TypeScript-приложений.

Библиотека поддерживает как REST API версии 2 (процесс устаревания начат, но всё ещё широко используется), так и новую версию 3 (процесс внедрения начат).

Архитектура SDK

SDK построен на трёх основных классах, которые наследуются от общего базового класса и предоставляют единый интерфейс для работы с REST API:

Три класса для разных сценариев использования

Класс	Назначение	Где использовать	Особенности
`B24Frame`	Работа из приложений, встроенных в интерфейс Bitrix24	На стороне клиента (браузер)	Автоматически доступен в iframe Bitrix24-приложения, использует токен текущего пользователя
`B24Hook`	Работа из автономных серверных приложений через вебхук	На стороне сервера	Использует постоянный токен вебхука, нельзя использовать в браузере
`B24OAuth`	Работа из автономных серверных приложений через OAuth 2.0	На стороне сервера	Использует OAuth-токен с возможностью обновления, нельзя использовать в браузере

Общий интерфейс

Все три класса наследуются от общего базового класса и предоставляют одинаковый набор методов:

Все три класса реализуют интерфейс TypeB24, который определяет единый набор операций:

type TypeB24 = {
  readonly isInit: boolean
  init(): Promise<void>
  destroy(): void

  getLogger(): LoggerInterface
  setLogger(logger: LoggerInterface): void

  get auth(): AuthActions

  // REST API (v2 / v3) — call, callList, fetchList, batch, batchByChunk
  get actions(): ActionsManager

  // Helper utilities (healthCheck, ping)
  get tools(): ToolsManager

  setRestrictionManagerParams(params: RestrictionParams): Promise<void>

  getTargetOrigin(): string
  getTargetOriginWithPath(): Map<ApiVersion, string>

  getHttpClient(version: ApiVersion): TypeHttp
  setHttpClient(version: ApiVersion, client: TypeHttp): void
}

REST-методы доступны через actions.v2.* и actions.v3.*:

// $b24 — экземпляр B24Frame | B24Hook | B24OAuth

await $b24.actions.v2.call.make(options)         // Promise<AjaxResult>
await $b24.actions.v2.callList.make(options)     // Promise<Result<T[]>>
$b24.actions.v2.fetchList.make(options)          // AsyncGenerator<T[]>
await $b24.actions.v2.batch.make(options)        // Promise<CallBatchResult>
await $b24.actions.v2.batchByChunk.make(options) // Promise<Result<T[]>>

// v3 симметрична
await $b24.actions.v3.call.make(options)
// ...

await $b24.tools.healthCheck.make({ requestId })  // Promise<boolean>
await $b24.tools.ping.make({ requestId })         // Promise<number>

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

Основные методы API

Call — базовый метод для вызова любых REST API-методов
CallList — автоматическое получение всех данных из list-методов с пагинацией
FetchList — поэтапная обработка больших объёмов данных через AsyncGenerator
Batch — выполнение до 50 команд в одном запросе
BatchByChunk — автоматическое разбиение больших наборов команд на батчи

Вспомогательные инструменты

HealthCheck — проверка доступности REST API
Ping — измерение времени отклика API

Выбор подходящего класса

Для клиентских приложений (браузер) client-side

Используйте B24Frame — он доступен в iframe Bitrix24-приложений:

// В приложении, встроенном в Bitrix24
async () => {
  $b24 = await initializeB24Frame()
  const response = await $b24.actions.v2.call.make({
    method: 'crm.contact.get',
    params: { id: 123 }
  })
}

// В приложении, встроенном в Bitrix24
async () => {
  $b24 = await initializeB24Frame()
  const response = await $b24.actions.v3.call.make({
    method: 'tasks.task.get',
    params: { id: 123 }
  })
}

Для серверных приложений с постоянным доступом server-side

Используйте B24Hook с вебхуком:

import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

const response = await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 },
  requestId: 'server-request'
})

import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

const response = await $b24.actions.v3.call.make({
  method: 'tasks.task.get',
  params: { id: 123 },
  requestId: 'server-request'
})

Для серверных приложений с OAuth-аутентификацией server-side authentication

Используйте B24OAuth:

См. B24OAuth для полной сигнатуры конструктора и потока обновления токена.

// @check-ignore: placeholder params for illustration — real B24OAuthParams required at runtime

import { B24OAuth, EnumAppStatus } from '@bitrix24/b24jssdk'

const $b24 = new B24OAuth(
  { /* B24OAuthParams: applicationToken, userId, memberId, accessToken,
       refreshToken, expires, expiresIn, scope, domain, clientEndpoint,
       serverEndpoint, status (EnumAppStatus.*) */ },
  { clientId: 'your_client_id', clientSecret: 'your_client_secret' }
)

const response = await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 },
  requestId: 'oauth-request'
})

// @check-ignore: placeholder params for illustration — real B24OAuthParams required at runtime

import { B24OAuth, EnumAppStatus } from '@bitrix24/b24jssdk'

const $b24 = new B24OAuth(
  { /* B24OAuthParams: см. /docs/working-with-the-rest-api/oauth/ */ },
  { clientId: 'your_client_id', clientSecret: 'your_client_secret' }
)

const response = await $b24.actions.v3.call.make({
  method: 'tasks.task.get',
  params: { id: 123 },
  requestId: 'oauth-request'
})

Общие методы (доступны во всех классах)

Архитектура методов

Метод	Возвращаемое значение	Память	Использование	Подходит для
`Call`	`Promise<AjaxResult>`	Минимум	Одиночные вызовы	Получение отдельных элементов, вызов методов без пагинации
`CallList`	`Promise<Result<T[]>>`	Все данные в памяти	`await response.getData()`	Малые и средние объёмы данных, когда все данные нужны сразу
`FetchList`	`AsyncGenerator<T[]>`	Обработка по частям	`for await (const chunk of generator)`	Большие объёмы данных, потоковая обработка, ограниченная память
`Batch`	`Promise<CallBatchResult>`	Зависит от объёма	Пакетные операции до 50 команд	Массовые операции, оптимизация сетевых запросов

Автоматические предупреждения
SDK автоматически отслеживает использование методов, доступных в REST API v3:
"The method {method_name} is available in restApi:v3. It's worth migrating to the new API."
Это позволяет постепенно мигрировать с устаревающего API v2 на современный v3.

Лучшие практики

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

Всегда проверяйте isSuccess и обрабатывайте ошибки:

// @check-ignore: top-level return in error-handling illustration

const response = await $b24.actions.v2.call.make({
  method: 'some.method',
  params: { /* параметры */ },
  requestId: 'unique-id'
})

if (!response.isSuccess) {
  console.error('Error:', response.getErrorMessages().join('; '))
  // Дополнительная логика обработки ошибок
  return
}

// Работа с успешным результатом
const data = response.getData()

// @check-ignore: top-level return in error-handling illustration

const response = await $b24.actions.v3.call.make({
  method: 'some.method',
  params: { /* параметры */ },
  requestId: 'unique-id'
})

if (!response.isSuccess) {
  console.error('Error:', response.getErrorMessages().join('; '))
  // Дополнительная логика обработки ошибок
  return
}

// Работа с успешным результатом
const data = response.getData()

Управление запросами

requestId — всегда указывайте уникальный идентификатор запроса для отслеживания и дедупликации
Логирование — используйте встроенные механизмы логирования для отладки
Таймауты — настраивайте таймауты для длительных операций

Миграция с REST API v2 на v3

Bitrix24 постепенно переходит на REST API версии 3. Рекомендуется:

Следить за предупреждениями от SDK о доступности методов в v3
Использовать документацию REST API v3
Планировать миграцию существующих проектов

Что дальше?

Общие методы — вы уже познакомились с общими методами, доступными во всех трёх классах
Индивидуальные возможности — у каждого класса (B24Frame, B24Hook, B24OAuth) есть свои уникальные методы и возможности, которые описаны в отдельных разделах документации
Примеры использования — смотрите конкретные примеры для каждого сценария использования

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

Выбор метода

Руководство по выбору между Call, CallList, FetchList, Batch и BatchByChunk в REST API v2 и v3.