Developing a REST application for Bitrix24

REST Application Development for Bitrix24

A sales manager opens a deal card in Bitrix24 and sees only the information entered manually. Yet in the accounting system, that same client has 3 years of purchase history, a credit limit, and open complaints. Switching between two tabs is tedious, and data goes out of sync. A REST application embeds the required information directly into the Bitrix24 interface — no need to open an external system.

What Is a REST Application in the Bitrix24 Ecosystem

A REST application is an external web service that interacts with Bitrix24 via OAuth 2.0 and the REST API (https://domain.bitrix24.ru/rest/). The application can:

• embed widgets into the Bitrix24 interface (via placement)
• read and write CRM data, tasks, and calls through REST methods
• subscribe to events (webhooks) and react to changes
• add custom buttons to deal, contact, and company cards

Applications are divided into mass-market (published in the Bitrix24 Marketplace) and embedded (developed for a specific portal). Most enterprise tasks require embedded applications.

OAuth and Authorization

The first step is configuring OAuth 2.0. The application receives a client_id and client_secret upon registration on the portal. The user authorizes the application, which then receives an access_token (TTL 1 hour) and a refresh_token (TTL 30 days).

class Bitrix24OAuth {
    public function refreshToken(string $refreshToken): array {
        $response = Http::post('https://domain.bitrix24.ru/oauth/token/', [
            'grant_type'    => 'refresh_token',
            'client_id'     => config('b24.client_id'),
            'client_secret' => config('b24.client_secret'),
            'refresh_token' => $refreshToken,
        ]);
        // Save new tokens to storage
        TokenStorage::save($response['access_token'], $response['refresh_token']);
        return $response;
    }
}

Tokens are stored encrypted (AES-256). Before every API call, the token TTL is checked and a refresh is performed if necessary.

Deep Dive: Widget in a Deal Card

The most common scenario is embedding external data into a CRM card. Registering a placement:

// Called via REST API when the application is installed
$client->call('placement.bind', [
    'PLACEMENT' => 'CRM_DEAL_DETAIL_TAB',
    'HANDLER'   => 'https://myapp.example.com/widget/deal/',
    'TITLE'     => 'Client History',
    'OPTIONS'   => ['extraData' => 'ENTITY_ID'],
]);

When a manager opens a deal, Bitrix24 loads an iframe with your application's URL, passing the ENTITY_ID (deal ID). The application:

1. Retrieves ENTITY_ID from placement.info()
2. Makes a crm.deal.get REST request to fetch deal data (contact/company ID)
3. Uses the contact ID to query the internal accounting system
4. Displays purchase history, credit limit, and open tasks

The entire cycle takes 1–2 seconds with proper caching of data from the accounting system.

Interacting with the Bitrix24 REST API

The Bitrix24 REST API contains more than 700 methods. The most commonly used in enterprise applications:

• crm.deal.*, crm.contact.*, crm.company.* — CRM operations
• tasks.task.* — tasks
• im.message.add — sending messages to chat
• bizproc.workflow.start — launching business processes
• user.get — user data

Batch requests. When data from multiple methods is needed simultaneously, use batch:

$result = $client->call('batch', [
    'halt'  => 0,
    'cmd'   => [
        'deal'    => 'crm.deal.get?id=123',
        'contact' => 'crm.contact.get?id=$result[deal][CONTACT_ID]',
    ]
]);

This reduces the number of HTTP requests and speeds up widget loading.

Limits and Quotas

Bitrix24 throttles the API: 2 requests per second per application, no more than 50 requests in a batch. When exceeded — error QUERY_LIMIT_EXCEEDED. The module implements a request queue with rate limiting (rate limiter based on Redis or a database table) and automatic retry on receiving a limit error.

Development Timeline

Before development, determine whether the application will be mass-market (Marketplace publication) or embedded — this affects the OAuth flow architecture and multi-tenancy requirements.