CallV3.make

Обзор

Используйте CallV3.make() для вызова методов REST API версии 3.

Метод возвращает Promise с объектом AjaxResult, содержащим данные ответа, статус и методы обработки ошибок.

// Базовое использование
const response = await $b24.actions.v3.call.make({
  method: 'tasks.task.get',
  params: {
    id: 123
  },
  requestId: 'unique-request-id'
})

Сигнатура метода

make<T = unknown>(
  options: ActionCallV3
): Promise<AjaxResult<T>>

Параметры

Объект options содержит следующие свойства:

Возвращаемое значение

Promise<AjaxResult<T>> — promise, разрешающийся в объект AjaxResult.

Этот объект предоставляет:

• .getData(): SuccessPayload<T> | undefined — возвращает success-конверт { result: T, time: PayloadTime } или undefined, если запрос провалился. Сначала проверьте .isSuccess.
• .isSuccess: boolean — флаг успешного выполнения запроса.
• .getErrorMessages(): string[] — массив сообщений об ошибках.

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

SDK не держит клиентский список v3-методов: CallV3.make() отправляет любой переданный метод на v3-endpoint, и решает сервер. Если метод не является v3-методом, сервер отвечает METHODNOTFOUNDEXCEPTION как soft-ошибкой (response.isSuccess === false, сообщение в getErrorMessages()) — предварительного выброса на стороне SDK нет. Используйте CallV2.make() для legacy-методов или проверьте apidocs.bitrix24.ru (либо собственный rest.documentation.openapi портала), что существует в v3.

Для успешных запросов всегда проверяйте isSuccess и обрабатывайте ошибки:

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

const response = await $b24.actions.v3.call.make({
  method: 'some.method',
  params: { /* some_params */ },
  requestId: 'unique-request-id'
})

if (!response.isSuccess) {
  // Обработка ошибки
  console.error(new Error(`Error: ${response.getErrorMessages().join('; ')}`))
  return
}

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

Примеры

Получение задачи

import { B24Hook, LoggerFactory, SdkError, AjaxError } from '@bitrix24/b24jssdk'

type Task = {
  id: number
  title: string
  autocompleteSubTasks: boolean
}

const devMode = typeof import.meta !== 'undefined' && (import.meta?.dev || globalThis._importMeta_.env?.DEV)
const $logger = LoggerFactory.createForBrowser('Example:taskGet', devMode)
const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

async function getTask(itemId: number, requestId: string): Promise<Task> {
  const response = await $b24.actions.v3.call.make<{ item: Task }>({
    method: 'tasks.task.get',
    params: {
      id: itemId,
      select: ['id', 'title', 'autocompleteSubTasks']
    },
    requestId
  })

  if (!response.isSuccess) {
    throw new SdkError({
      code: 'MY_APP_GET_PROBLEM',
      description: `Problem ${response.getErrorMessages().join('; ')}`,
      status: 404
    })
  }

  return (response.getData()!.result as { item: Task }).item
}

// Usage
const itemId = 2
const requestId = `task-${itemId}`
try {
  const entity = await getTask(itemId, requestId)
  $logger.info(`Entity [${entity.id}]`, { entity })
} catch (error) {
  if (error instanceof AjaxError) {
    $logger.critical(error.message, { requestId, code: error.code })
  } else {
    $logger.alert('Problem', { requestId, error })
  }
}

Долгие запросы

Неидемпотентные методы, создающие или сохраняющие состояние — например tasks.task.add — могут превысить axios-таймаут 30 секунд по умолчанию на нагруженном портале. При таймауте SDK по умолчанию делает повторные запросы, что может создать дубликаты сущностей на стороне сервера (см. issue #24).

Для любого метода, создающего или сохраняющего состояние, увеличьте axios-таймаут и отключите повторные запросы при транспортных ошибках:

import { ApiVersion, ParamsFactory } from '@bitrix24/b24jssdk'

// const $b24 = ...
$b24.getHttpClient(ApiVersion.v3).ajaxClient.defaults.timeout = 120_000
await $b24.setRestrictionManagerParams({
  ...ParamsFactory.getDefault(),
  retryOnNetworkError: false
})

await $b24.actions.v3.call.make({
  method: 'tasks.task.add',
  params: {/*…*/}
})

См. Limiters — долгие запросы и неидемпотентные вызовы для полного объяснения и альтернативных конфигураций.

Альтернативы и рекомендации

• Для работы со списками: вместо ручного управления пагинацией используйте:
  • CallList — автоматически получает все страницы и возвращает единый результат.
  • FetchList — возвращает асинхронный генератор для поэтапной обработки больших списков.
• Для пакетных операций: используйте Batch для выполнения до 50 команд в одном запросе.
• На стороне клиента (браузер): используйте встроенный объект B24Frame.