Налаштування Bitrix24 REST API для React-додатків

Налаштування Bitrix24 REST API для React-застосунків

Bitrix24 REST API — це HTTP-інтерфейс до CRM, завдань, користувачів, файлів та інших об'єктів порталу. React-застосунок взаємодіє з ним через OAuth 2.0-токени або вхідні вебхуки. Без правильного налаштування авторизації, CORS та структури запитів застосунок або взагалі не працює, або втрачає токени і ламається у production.

Схеми авторизації

Вхідний вебхук — найпростіший варіант. Створюється у Налаштування → Розробникам → Інше → Вхідний вебхук. Видає статичний URL з токеном. Підходить для внутрішніх інструментів без складної авторизації.

const WEBHOOK_URL = 'https://your-portal.bitrix24.ru/rest/1/token123abc/';

async function callBX24(method: string, params: object) {
  const response = await fetch(`${WEBHOOK_URL}${method}`, {
    method:  'POST',
    headers: { 'Content-Type': 'application/json' },
    body:    JSON.stringify(params),
  });
  return response.json();
}

OAuth 2.0 через застосунок — для застосунків, що встановлюються на різні портали. Реєстрація в розробницькому акаунті, отримання client_id + client_secret, flow авторизації через redirect.

BX24.js SDK — для застосунків всередині iframe Бітрікс24. SDK автоматично передає токен авторизованого користувача.

React Query + BX24 REST

Для систематичної роботи з REST API у React — обгортка на React Query:

// src/api/bitrix24.ts
import axios from 'axios';

const bx24Api = axios.create({
  baseURL: process.env.REACT_APP_BX24_WEBHOOK,
});

// Автообробка пагінації Бітрікс24 (ліміт 50 записів за запит)
async function getAllItems<T>(method: string, params: object): Promise<T[]> {
  const items: T[] = [];
  let start = 0;

  do {
    const { data } = await bx24Api.post(method, { ...params, start });
    items.push(...data.result);
    start = data.next;
  } while (data.next);

  return items;
}

// Хук для списку угод
export function useDeals(filter?: object) {
  return useQuery({
    queryKey: ['deals', filter],
    queryFn:  () => getAllItems('crm.deal.list', {
      select: ['ID', 'TITLE', 'STAGE_ID', 'OPPORTUNITY', 'ASSIGNED_BY_ID'],
      filter,
      order:  { ID: 'DESC' },
    }),
    staleTime: 60_000,
  });
}

Пагінація Бітрікс24 повертає максимум 50 записів і поле next для наступної сторінки — потрібно обробляти явно.

Batch-запити для оптимізації

Бітрікс24 підтримує пакетні запити через batch — до 50 методів в одному HTTP-запиті:

async function getUsersWithDepartments(userIds: number[]) {
  const batchCommands: Record<string, string> = {};

  userIds.forEach(id => {
    batchCommands[`user_${id}`] = `user.get?ID=${id}`;
    batchCommands[`dept_${id}`] = `department.get?ID=user_${id}`;
  });

  const { data } = await bx24Api.post('batch', { halt: 0, cmd: batchCommands });
  return data.result;
}

Batch суттєво зменшує кількість HTTP round-trips при початковому завантаженні даних.

CORS та серверний проксі

При прямих запитах з браузера до Бітрікс24 REST виникають CORS-обмеження — особливо при роботі з хмарними порталами на піддомені. Рекомендований підхід: всі REST-запити йдуть через власний проксі-сервер (Laravel, Node.js), який додає токени та обробляє помилки авторизації.

Обробка помилок і оновлення токена

bx24Api.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.data?.error === 'expired_token') {
      await refreshBX24Token();
      return bx24Api.request(error.config);
    }
    throw error;
  }
);

Токен Бітрікс24 OAuth діє 1 годину. Refresh token — 2 тижні. Без інтерцептора застосунок ламається через годину роботи.

Склад робіт

• Вибір схеми авторизації під завдання (вебхук / OAuth / BX24.js)
• Налаштування застосунку у Бітрікс24, отримання токенів
• Розробка API-шару: axios/fetch обгортки, React Query хуки
• Обробка пагінації, batch-запитів, оновлення токена
• Налаштування проксі за потреби, CORS-конфігурація

Терміни: базова інтеграція з вебхуком — 2–3 дні. Повний OAuth 2.0 flow з менеджментом токенів і проксі — 1–2 тижні.