Разработка кастомного 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 часов.