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

Розробка кастомного REST-додатка для маркетплейсу Bitrix24

REST-додаток для маркетплейсу Bitrix24 — це не локальний додаток, встановлений на конкретному портальні, а багатокористувацький продукт, який можна встановити на будь-якому порталі з каталогу маркетплейсу. Це змінює вимоги до архітектури: додаток повинен бути 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 обробники
• API-сервіс — приймає запити від iframe, працює з REST API Bitrix24
• Worker/черга — обробляє webhook'и від порталів асинхронно
• БД — зберігає токени, параметри, дані додатка з партиціюванням по member_id
• Кеш (Redis) — кешуємо access_token до закінчення TTL (3600 сек), дані які рідко змінюються

Обробники, які обов'язково потрібно реалізувати:

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

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

При установці додатка Bitrix24 відправляє 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), інакше при паралельних запитах кілька воркерів можуть одночасно оновити токен й один отримає неактуальний.

Робота з REST API Bitrix24 з вашого сервісу

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

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

Або токен передається в тілі: auth={access_token}.

Rate limiting. Bitrix24 обмежує додатки: не більше 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
}

Критична вимога: обробник повинен відповісти HTTP 200 за 5 секунд. Усе тяжке процесинг — в чергу. Схема обробника:

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

Безпека

Верифікація вхідних запитів від Bitrix24: у заголовках або тілі передається auth[application_token] — це статичний токен вашого додатка з параметрів у partner.bitrix24.ru. Перевіряйте його на кожен вхідний запит.

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

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