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

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

REST-приложение для маркетплейса Битрикс24 — это не локальное приложение, установленное на конкретном портале, а многопользовательский продукт, который можно установить на любой портал из каталога маркетплейса. Это меняет требования к архитектуре: приложение должно быть multi-tenant с первого дня, обрабатывать независимые потоки данных от тысяч порталов и не падать при нестандартном поведении любого из них.

Чем REST-приложение отличается от локального

Локальное приложение создаётся в настройках конкретного портала через раздел «Приложения» → «Разработчикам». Оно работает только на этом портале, токены жёстко привязаны, multi-tenancy не нужен.

REST-приложение для маркетплейса регистрируется через partner.bitrix24.ru, имеет единые client_id и client_secret для всех инсталляций. Каждый портал, установивший приложение, получает собственные access_token / refresh_token. Ваш сервис должен хранить токены всех порталов и работать с каждым независимо.

Ключевой идентификатор инсталляции — member_id (хэш, уникальный для каждого портала). Все данные в вашей БД партиционируются по member_id.

Инфраструктура приложения

Минимальная инфраструктура production-приложения для маркетплейса:

Компоненты:

• OAuth-сервер — обрабатывает install, uninstall, login handler'ы
• API-сервис — принимает запросы от iframe, работает с Битрикс24 REST API
• Worker/очередь — обрабатывает webhook'и от порталов асинхронно
• БД — хранит токены, настройки, данные приложения с партиционированием по member_id
• Кэш (Redis) — кэшируем access_token до истечения TTL (3600 сек), данные которые редко меняются

Handler'ы, которые обязательно нужно реализовать:

POST /bitrix/install   → получение code, обмен на токены, сохранение в БД
POST /bitrix/uninstall → инвалидация токенов, очистка данных портала (GDPR)
POST /bitrix/login     → SSO через Битрикс24 (опционально, но удобно)
POST /bitrix/events    → приём webhook-событий от портала
GET  /bitrix/app       → главная страница iframe-приложения

OAuth-флоу: детали реализации

При установке приложения Битрикс24 отправляет POST на handler URL (прописывается при регистрации приложения):

POST /bitrix/install
Content-Type: application/x-www-form-urlencoded

event=ONAPPINSTALL&auth[access_token]=...&auth[refresh_token]=...
&auth[member_id]=abc123&auth[domain]=company.bitrix24.ru

Здесь уже в теле установки приходят токены — code для обмена не нужен. Сохраняете всё в БД. Схема таблицы токенов:

CREATE TABLE app_installations (
    id              SERIAL PRIMARY KEY,
    member_id       VARCHAR(64) UNIQUE NOT NULL,
    domain          VARCHAR(255) NOT NULL,
    access_token    TEXT NOT NULL,
    refresh_token   TEXT NOT NULL,
    expires_at      TIMESTAMP NOT NULL,
    scope           TEXT,
    installed_at    TIMESTAMP DEFAULT NOW(),
    uninstalled_at  TIMESTAMP
);
CREATE INDEX ON app_installations (member_id);

Refresh токена: когда expires_at наступает (или при получении 401 от API портала), делаем запрос на https://oauth.bitrix.info/oauth/token/ с grant_type=refresh_token. Важно: refresh должен быть атомарным (mutex по member_id), иначе при параллельных запросах несколько воркеров могут одновременно обновить токен и один из них получит неактуальный.

Работа с Битрикс24 REST API из вашего сервиса

После получения access_token все запросы к конкретному порталу идут на его домен:

POST https://{domain}/rest/{method}
Authorization: Bearer {access_token}
Content-Type: application/json

Либо токен передаётся в теле: auth={access_token}.

Rate limiting. Битрикс24 ограничивает приложения: не более 2 запросов/секунду на один портал (в некоторых источниках — до 5 RPS на облачных тарифах). При превышении — ответ {"error":"QUERY_LIMIT_EXCEEDED"}. Нужна очередь с rate limiter per member_id.

Batch-запросы. Метод batch позволяет объединить до 50 методов в один HTTP-запрос. Это критично для производительности — вместо 50 отдельных HTTP round-trip делаем один.

Пагинация. Все list-методы возвращают максимум 50 элементов. В ответе есть next (смещение для следующего запроса) и total. Для получения всех записей нужен цикл. При большом объёме данных (тысячи записей) — обязательно используйте асинхронную обработку страниц.

Работа с placements: встраивание в интерфейс

Регистрация placement при установке:

// Вызываем при обработке ONAPPINSTALL
BX24.callMethod('placement.bind', {
    PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
    HANDLER: 'https://your-app.com/bitrix/app?placement=crm_deal',
    TITLE: 'Название вкладки',
    DESCRIPTION: 'Описание'
});

В iframe ваше приложение получает контекст через JS SDK:

BX24.init(function() {
    BX24.placement.getInterface(function(data) {
        // data.ID — ID сделки/лида/контакта
        // data.ENTITY_TYPE — тип сущности
        fetchDataForEntity(data.ID, data.ENTITY_TYPE);
    });

    // Изменение размера iframe под контент
    BX24.fitWindow();
});

Cookie в iframe недоступны в Safari из-за ITP. Сессию нужно хранить в localStorage или получать через BX24.getAuth() при каждом открытии.

Обработка событий (webhooks)

Подписка на события через event.bind делается при установке:

POST /rest/event.bind
{
    "event": "ONCRMDEALUPDATE",
    "handler": "https://your-app.com/bitrix/events",
    "auth_type": 0
}

Критичное требование: handler должен ответить HTTP 200 за 5 секунд. Весь тяжёлый процессинг — в очередь. Схема обработчика:

POST /bitrix/events → верификация подписи → положить в очередь → ответить 200
Воркер → достать из очереди → обработать → обновить данные

Безопасность

Верификация входящих запросов от Битрикс24: в заголовках или теле передаётся auth[application_token] — это статический токен вашего приложения из настроек в partner.bitrix24.ru. Проверяйте его на каждый incoming запрос.

Для webhook'ов из event.bind тело содержит auth[application_token] — то же самое.

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