Документация1С-Битрикс: Модулиnative.apiРазработчикамПримеры работыЗапросы

JavaScript

Замените https://example.ru/api/ адресом своего API. Нужные наборы роутов должны быть включены.

Отправка запроса

Примеры для браузера. Функция возвращает тело ответа, включая ответы с HTTP-ошибкой

const apiUrl = 'https://example.ru/api/'

async function apiRequest(path, {method = 'GET', authorization, body} = {}) {
  const headers = new Headers()

  if (authorization) headers.set('Authorization', authorization)
  if (body !== undefined) headers.set('Content-Type', 'application/json')

  const response = await fetch(new URL(path, apiUrl), {
    method,
    headers,
    credentials: 'same-origin',
    body: body === undefined ? undefined : JSON.stringify(body),
  })

  return response.text()
}

Сервисные роуты

Параметры адреса

// Проверить работу API
console.log(await apiRequest('up'))

// Передать id в адресе и name в строке запроса
console.log(await apiRequest('up/user/15?name=Ivan'))

Передача JSON

// Передать параметры в теле запроса
console.log(await apiRequest('up', {
  method: 'POST',
  body: {name: 'Иван', quantity: 2},
}))

XML-ответ

// Отправить JSON и получить XML-ответ встроенного PUT-роута
console.log(await apiRequest('up', {
  method: 'PUT',
  body: {name: 'Иван'},
}))

// Выбрать XML для GET-запроса
console.log(await apiRequest('up?format=xml'))

Доступ по группам

// HTTP 403: в штатной карте задан whitelist без авторизации API
console.log(await apiRequest('up/group/1'))

Вызываемый класс

// Проверить вызываемый класс; данные не удаляются
console.log(await apiRequest('up', {method: 'DELETE'}))

Токены

При AUTH_MFA_REQUIRED для выпуска и списка токенов через Basic нужны cookie сессии того же пользователя после входа с MFA. При запросе к тому же сайту cookie передаются автоматически — сначала завершите вход с MFA.

Подставьте логин, пароль, <ACCESS_TOKEN>, <REFRESH_TOKEN> и <CLIENT_ID>. Клиента определяют заголовки браузера. Выпускайте и используйте пару в одном клиенте: перенос привязанного токена из другого браузера или cURL приведёт к HTTP 401. Изменение заголовков после обновления браузера или смены языка также может потребовать повторного выпуска пары.

const login = 'login'
const password = '<PASSWORD>'
const accessToken = '<ACCESS_TOKEN>'
const refreshToken = '<REFRESH_TOKEN>'
const clientId = '<CLIENT_ID>'
const bytes = new TextEncoder().encode(`${login}:${password}`)
const credentials = btoa(Array.from(bytes, byte => String.fromCharCode(byte)).join(''))
const basicAuthorization = `Basic ${credentials}`

Выпуск

// Создать пару токенов
console.log(await apiRequest('token', {
  method: 'POST',
  authorization: basicAuthorization,
}))

Обновление

// Заменить пару по refresh-токену
console.log(await apiRequest('token', {
  method: 'PUT',
  authorization: `Bearer ${refreshToken}`,
}))

Список

// Получить активные токен-сессии пользователя
console.log(await apiRequest('token', {authorization: basicAuthorization}))

Отзыв

// client.id берётся из списка сессий
console.log(await apiRequest(`token?client_id=${encodeURIComponent(clientId)}`, {
  method: 'DELETE',
  authorization: `Bearer ${accessToken}`,
}))

После выпуска или обновления сохраните оба токена из ответа: access и refresh. Поля ответа и правила работы с токенами.

Провайдер

Описание метода

// Узнать параметры разрешённого метода
const query = new URLSearchParams({
  class: 'Bitrix\\Main\\Localization\\Loc',
  method: 'getCurrentLang',
})

console.log(await apiRequest(`provider?${query}`, {
  authorization: `Bearer ${accessToken}`,
}))

Выполнение метода

// Получить текущий язык Битрикса
console.log(await apiRequest('provider', {
  method: 'POST',
  authorization: `Bearer ${accessToken}`,
  body: {
    class: 'Bitrix\\Main\\Localization\\Loc',
    method: 'getCurrentLang',
  },
}))

Для другого домена разрешите Origin, Authorization и Content-Type в CORS.