Разработка REST-приложения для Битрикс24

Разработка REST-приложения для Битрикс24

Менеджер по продажам открывает карточку сделки в Битрикс24 и видит только ту информацию, которую занёс вручную. А в учётной системе у этого клиента — 3 года истории покупок, кредитный лимит, открытые рекламации. Переключаться между двумя вкладками утомительно, данные расходятся. REST-приложение встраивает нужную информацию прямо в интерфейс Битрикс24 без необходимости открывать стороннюю систему.

Что такое REST-приложение в экосистеме Битрикс24

REST-приложение — это внешний веб-сервис, который взаимодействует с Битрикс24 через OAuth 2.0 и REST API (https://domain.bitrix24.ru/rest/). Приложение может:

• встраивать виджеты в интерфейс Битрикс24 (через placement)
• читать и записывать данные CRM, задачи, звонки через REST-методы
• подписываться на события (вебхуки) и реагировать на изменения
• добавлять собственные кнопки в карточки сделок, контактов, компаний

Приложения делятся на тиражные (публикуются в Маркетплейс Битрикс24) и встроенные (разрабатываются для конкретного портала). Большинство корпоративных задач — встроенные.

OAuth и авторизация

Первый шаг — настройка OAuth 2.0. Приложение получает client_id и client_secret при регистрации на портале. Пользователь авторизует приложение, оно получает access_token (TTL 1 час) и refresh_token (TTL 30 дней).

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,
        ]);
        // Сохранить новые токены в хранилище
        TokenStorage::save($response['access_token'], $response['refresh_token']);
        return $response;
    }
}

Токены хранятся в зашифрованном виде (AES-256). При каждом API-вызове проверяется TTL токена и при необходимости выполняется рефреш до отправки запроса.

Детально: виджет в карточке сделки

Самый распространённый сценарий — встроить внешние данные в карточку CRM. Регистрация placement:

// Вызов через REST API при установке приложения
$client->call('placement.bind', [
    'PLACEMENT' => 'CRM_DEAL_DETAIL_TAB',
    'HANDLER'   => 'https://myapp.example.com/widget/deal/',
    'TITLE'     => 'История клиента',
    'OPTIONS'   => ['extraData' => 'ENTITY_ID'],
]);

Когда менеджер открывает сделку, Битрикс24 загружает iframe с URL вашего приложения, передавая ENTITY_ID (ID сделки). Приложение:

1. Получает ENTITY_ID из placement.info()
2. Делает REST-запрос crm.deal.get для получения данных сделки (ID контакта/компании)
3. По ID контакта обращается к внутренней учётной системе
4. Отображает историю покупок, кредитный лимит, открытые задачи

Весь цикл занимает 1–2 секунды при правильном кешировании данных из учётной системы.

Взаимодействие с REST API Битрикс24

REST API Битрикс24 содержит более 700 методов. Наиболее используемые в корпоративных приложениях:

• crm.deal.*, crm.contact.*, crm.company.* — работа с CRM
• tasks.task.* — задачи
• im.message.add — отправка сообщений в чат
• bizproc.workflow.start — запуск бизнес-процессов
• user.get — данные пользователей

Batch-запросы. При необходимости получить данные из нескольких методов одновременно используется batch:

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

Это сокращает количество HTTP-запросов и ускоряет загрузку виджета.

Лимиты и квоты

Битрикс24 ограничивает API: 2 запроса в секунду для одного приложения, не более 50 запросов в batch. При превышении — ошибка QUERY_LIMIT_EXCEEDED. Модуль реализует очередь запросов с ограничением скорости (rate limiter на основе Redis или бд-таблицы) и автоматическим повтором при получении ошибки лимита.

Сроки разработки

Перед разработкой нужно определить, будет ли приложение тиражным (публикация в Маркетплейс) или встроенным — это влияет на архитектуру OAuth-потока и требования к мультиарендности.