Setting up Bitrix24 REST API for React applications

Configuring Bitrix24 REST API for React Applications

The Bitrix24 REST API is an HTTP interface to CRM, tasks, users, files, and other portal objects. A React application communicates with it via OAuth 2.0 tokens or inbound webhooks. Without correct authorization setup, CORS handling, and request structure, the application either fails entirely or loses tokens and breaks in production.

Authorization Schemes

Inbound webhook — the simplest option. Created under Settings → Developers → Other → Inbound Webhook. Issues a static URL with a token. Suitable for internal tools that do not require complex authorization.

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 via application — for applications installed on multiple portals. Register in a developer account, obtain client_id + client_secret, implement the authorization flow via redirect.

BX24.js SDK — for applications running inside a Bitrix24 iframe. The SDK automatically passes the authenticated user's token.

React Query + BX24 REST

For systematic REST API usage in React — a wrapper built on React Query:

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

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

// Auto-handle Bitrix24 pagination (50-record limit per request)
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;
}

// Hook for deal list
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,
  });
}

Bitrix24 pagination returns a maximum of 50 records and a next field for the next page — this must be handled explicitly.

Batch Requests for Optimization

Bitrix24 supports batch requests via batch — up to 50 methods in a single HTTP request:

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;
}

Batching significantly reduces the number of HTTP round-trips during initial data loading.

CORS and Server-Side Proxy

Direct browser requests to Bitrix24 REST encounter CORS restrictions — particularly when working with cloud portals on a subdomain. The recommended approach: all REST requests go through a dedicated proxy server (Laravel, Node.js) that adds tokens and handles authorization errors.

Error Handling and Token Refresh

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

Bitrix24 OAuth tokens expire after 1 hour. Refresh tokens are valid for 2 weeks. Without the interceptor, the application breaks after one hour of use.

Scope of Work

• Selecting the appropriate authorization scheme (webhook / OAuth / BX24.js)
• Configuring the application in Bitrix24, obtaining tokens
• Developing the API layer: axios/fetch wrappers, React Query hooks
• Handling pagination, batch requests, token refresh
• Proxy configuration if required, CORS setup

Timeline: basic webhook integration — 2–3 days. Full OAuth 2.0 flow with token management and proxy — 1–2 weeks.