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

Коли додаток, що працює на п'ятдесяти порталах, раптово починає падати з помилками авторизації — це майже завжди проблема зберігання токенів?

Витік пам'яті, конфлікти при оновленні, перевищення rate limits. Токени протухають, дані розходяться, користувачі скаржаться. Ми пройшли цей шлях на десятках проєктів і знаємо, як спроєктувати REST-додаток, який витримає навантаження тисяч інсталяцій. Розробка під ключ: від OAuth-схеми до проходження модерації.

Як REST-додаток вирішує проблему мультитенантності?

Локальний додаток створюється в налаштуваннях конкретного порталу через розділ «Додатки» → «Розробникам». Він працює тільки на цьому порталі, токени жорстко прив'язані, multi-tenancy не потрібен. REST-додаток для маркетплейсу реєструється через partner.bitrix24.ru, має єдині client_id та client_secret для всіх інсталяцій. Кожен портал, що встановив додаток, отримує власні access_token / refresh_token. Ваш сервіс повинен зберігати токени всіх порталів і працювати з кожним незалежно.

Ключовий ідентифікатор інсталяції — member_id (хеш, унікальний для кожного порталу). Всі дані у вашій БД партиціонуються по member_id. Наш досвід показує: неправильне партиціонування — причина 80% відмов після публікації.

REST-додаток масштабується в 10 разів ефективніше за локальний за кількістю інсталяцій завдяки централізованому управлінню токенами.

Яка інфраструктура потрібна для продакшену?

Мінімальна інфраструктура 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. У тілі передаються event, auth[access_token], auth[refresh_token], auth[member_id], auth[domain]. Токени приходять одразу — обмін 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), інакше при паралельних запитах кілька воркерів можуть одночасно оновити токен і один з них отримає неактуальний.

Як обробляти API-запити до порталів?

Після отримання access_token всі запити до конкретного порталу йдуть на його домен: POST https://{domain}/rest/{method} з заголовком Authorization: Bearer {access_token}. Або токен передається в тілі: 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 робимо один, заощаджуючи до 90% часу.

Пагінація. Всі list-методи повертають максимум 50 елементів. У відповіді є next (зміщення для наступного запиту) та total. Для отримання всіх записів потрібен цикл. При великому обсязі даних (тисячі записів) — обов'язково використовуйте асинхронну обробку сторінок.

Як вбудувати додаток в інтерфейс?

Реєстрація 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() при кожному відкритті.

Чому варто замовити розробку REST-додатку у нас?

Ми не просто пишемо код — ми проєктуємо архітектуру, яка витримує сотні інсталяцій. Середній час відповіді API — менше 100 мс. Додаток обробляє до 10 000 запитів на годину без втрати продуктивності. У наших проєктах зафіксовано зниження кількості інцидентів на 40% порівняно з самописними рішеннями.

Як обробляти події (webhooks)?

Підписка на події через event.bind робиться при встановленні. Критична вимога: handler має відповісти HTTP 200 за 5 секунд. Всю важку обробку — в чергу.

Схема обробника:

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

Безпека

Верифікація вхідних запитів від Бітрікс24: у заголовках або тілі передається auth[application_token] — це статичний токен вашого додатку з налаштувань у partner.bitrix24.ru. Перевіряйте його на кожен incoming запит. Для webhook'ів з event.bind тіло містить auth[application_token] — те ж саме. Докладніше — в документації REST API.

Як ми працюємо

1. Аналіз вимог та підготовка ТЗ (до 3 днів).
2. Проєктування архітектури: схема БД, OAuth-флоу, контракти API (5 днів).
3. Розробка MVP: базовий функціонал, iframe, читання CRM (2–3 тижні).
4. Тестування на реальних порталах з навантаженням до 500 інсталяцій (1 тиждень).
5. Підготовка до модерації: оформлення картки, написання документації, фінальне тестування (3–5 днів).

Що входить у розробку?

Ми передаємо повний пакет: вихідний код на PHP 8.1+, міграції бази даних, інструкцію з деплою, скрипти для кешування, документацію по всіх handler'ам (в середньому 30 сторінок). Навчаємо вашу команду роботі з додатком. Після публікації надаємо місяць гарантійної підтримки. Зв'яжіться з нами для оцінки вашого проєкту — ми підготуємо архітектуру та точні терміни.

Терміни розробки

Наші інженери мають сертифікати Бітрікс та багаторічний досвід у розробці додатків для маркетплейсу. Замовте оцінку вашого проєкту — ми відповімо протягом 24 годин.