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

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

Приложение для маркетплейса Битрикс24 — это не просто веб-сервис с OAuth. Это продукт, который должен работать в iframe внутри корпоративного портала десятков тысяч компаний, на разных тарифных планах, с разными наборами модулей и правами пользователей. Большинство проблем возникает не на этапе разработки, а после публикации — когда выясняется, что у половины пользователей нет нужных прав, а REST-метод недоступен на тарифе «Базовый».

Типы приложений в экосистеме Битрикс24

Перед разработкой важно выбрать правильный тип приложения:

Встраиваемые приложения (embed) — работают в iframe, интегрируются в интерфейс Битрикс24 через placement API. Точки встраивания: CRM_LEAD_DETAIL_TAB, CRM_DEAL_DETAIL_TAB, CRM_CONTACT_DETAIL_TAB, CALL_LIST, TASKS_TASK_VIEW_TAB, USER_PROFILE_MENU и ещё несколько десятков. Это самый распространённый тип.

Виджеты — встраиваются в конкретные области интерфейса через BX24.placement.call(). Полезны для небольших действий: кнопка в карточке CRM, панель в чате.

Приложения с собственным интерфейсом — открываются в отдельной вкладке или модальном окне, используют REST API полностью в своей логике. Больше свободы в UX, но пользователь «выходит» из контекста Б24.

Боты и чат-приложения — работают через imbot.* и imsetting.* методы, имеют собственный обработчик событий.

Механизм авторизации: OAuth 2.0 + server-to-server

Авторизация в приложении Битрикс24 работает через OAuth 2.0 с кодом авторизации. Флоу при первом запуске:

1. Пользователь устанавливает приложение → Битрикс24 редиректит на redirect_uri с code
2. Приложение обменивает code на access_token и refresh_token через https://oauth.bitrix.info/oauth/token/
3. access_token живёт 1 час, refresh_token — 180 дней
4. Приложение хранит токены в своей БД, привязывая их к member_id (уникальный идентификатор портала)

Для server-to-server взаимодействия (без участия пользователя) нужно запрашивать права от имени приложения, а не пользователя. Это работает через OAuth с grant_type=client_credentials — доступно только для приложений с типом «Приложение», не «Виджет».

Критичный момент: member_id нужно использовать как tenant-идентификатор, если ваше приложение мультиарендное. Все данные в БД должны партиционироваться по member_id, иначе данные одной компании попадут к другой.

REST API: работа с данными Битрикс24

Битрикс24 REST API — это не классический REST. Методы вызываются через POST на https://{portal}.bitrix24.ru/rest/{method} с телом в виде form-data или JSON. Пагинация работает через start (смещение), лимит фиксирован — 50 записей. Для получения всех записей нужен цикл с next из ответа.

Наиболее используемые группы методов:

• crm.lead., crm.deal., crm.contact., crm.company. — работа с CRM
• tasks.task.*, task.item.list — задачи
• disk.folder., disk.file. — файлы и диски
• im.message.add, imbot.message.add — сообщения
• user.get, user.search — пользователи
• placement.bind — регистрация точек встраивания

Батчинг: одновременно можно отправить до 50 запросов через метод batch. Это критично для производительности — не делайте 50 отдельных HTTP-запросов там, где можно сделать один batched.

POST /rest/batch
{
  "halt": 0,
  "cmd": {
    "get_deal": "crm.deal.get?id=123",
    "get_contact": "crm.contact.get?id=456",
    "get_company": "crm.company.get?id=789"
  }
}

Webhooks и события

Приложение может подписываться на события портала через event.bind. При наступлении события Битрикс24 делает POST-запрос на handler URL приложения. Важные детали:

• Handler должен отвечать в течение 5 секунд, иначе Битрикс24 считает доставку неуспешной
• После 3 неуспешных доставок подряд — обработчик автоматически отвязывается
• Для тяжёлой обработки обязательно используйте очередь: принимайте webhook, кладите в очередь, отвечайте 200, обрабатывайте асинхронно

Доступные события: ONCRMLEADADD, ONCRMDEALUPDATE, ONTASKUPDATE, ONIM MESSAGECHAT, ONUSERADD и сотни других. Полный список зависит от тарифа и установленных модулей портала.

Размещение (placements) — как приложение встраивается в интерфейс

Регистрация placement производится при установке приложения через вызов placement.bind. Размещение привязывается к конкретной точке интерфейса и передаёт в приложение контекст: ID сущности, тип, права пользователя.

// В iframe приложения:
BX24.placement.getInterface(function(data) {
    // data содержит контекст: entityType, entityId и т.д.
    console.log(data);
});

Для работы с BX24 JS SDK нужно подключить //api.bitrix24.com/api/v1/ и вызвать BX24.init() перед любыми обращениями к API. В iframe среде cookies работают с ограничениями — нужно использовать localStorage или передавать токен через postMessage.

Работа с тарифными ограничениями

Главная боль приложений для маркетплейса: REST-методы доступны не на всех тарифах. Методы crm.* есть только начиная с определённых планов, telephony.* — только при подключении телефонии, tasks.* могут быть недоступны при отключённом модуле.

Правильный подход — при установке проверять доступность нужных методов через app.info и profile, и явно сообщать пользователю, если его тариф не поддерживает функциональность приложения. Падать с необработанным 403 при вызове метода недопустимо.

Хранение данных приложения

Битрикс24 предоставляет собственное хранилище для приложений через методы app.option.set / app.option.get — это простое key-value хранилище на стороне портала, лимит значения ~32KB. Для серьёзных данных приложение должно иметь собственную БД.

Для пользовательских настроек: user.option.set / user.option.get — хранение per-user настроек на стороне Битрикс24.

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

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

Приложение должно быть доступно по HTTPS с валидным SSL-сертификатом — Битрикс24 не работает с HTTP или самоподписанными сертификатами. Для production: отдельный домен, возможность горизонтального масштабирования (токены хранятся в Redis/БД, не в памяти процесса), мониторинг webhook-обработчиков.

Логирование: все вызовы REST API, все входящие webhook'и, все OAuth-обмены. При разборе инцидентов у клиента это единственный способ понять, что пошло не так.