Разбираем архитектуру приложений Битрикс24 — локальных и маркетплейс-решений: как они встраиваются в интерфейс, на чём строится авторизация и какие готовые сценарии реально экономят время разработчику.
Когда компании нужна нестандартная функциональность в Битрикс24, которой нет в коробке, разработчик оказывается перед выбором из нескольких путей: написать интеграцию через вебхуки, зарегистрировать полноценное REST-приложение или найти готовое решение в Маркетплейсе. Разница между этими вариантами — не просто «дольше или быстрее», а принципиально разная архитектура взаимодействия с платформой, и от этого выбора зависит, насколько стабильно решение переживёт следующее обновление Битрикс24.
Из чего состоит платформа приложений Битрикс24
Приложение Битрикс24 — это не модуль, который устанавливается «внутрь» портала, а внешний сервис, который встраивается в интерфейс через iframe и общается с порталом по REST API поверх OAuth 2.0. Именно поэтому у любого приложения, независимо от сложности, есть свой backend — даже простое приложение, показывающее виджет в карточке сделки, должно где-то обрабатывать события установки, обновления токенов доступа и запросы от JS-библиотеки BX24.js.
Точки встраивания в интерфейс называются placement — это конкретные места портала, куда приложение может добавить свой блок: карточка сделки, левое меню, панель CRM, форма создания задачи. Разработчик регистрирует обработчик для нужного placement, и Битрикс24 сам определяет, когда и где показать приложение, передавая ему контекст — например, ID текущей сделки.
Локальное приложение против Маркетплейса
Для разработки под собственные нужды компании обычно достаточно локального приложения — оно регистрируется прямо на конкретном портале и не проходит модерацию, но и не может быть переиспользовано на других порталах без повторной настройки. Это стандартный путь для кастомной интеграции, разработанной под конкретного заказчика.
Приложение в Маркетплейсе — совсем другая история: оно должно пройти проверку модерацией, поддерживать множество разных порталов одновременно, корректно обрабатывать событие деинсталляции и работать в рамках лимитов API, общих для всех клиентов сервиса. Разработка под Маркетплейс оправдана, если решение действительно универсально и рассчитано на широкий круг клиентов — для точечной автоматизации одного бизнеса это избыточные накладные расходы.
- вебхуки — самый простой способ интеграции без полноценного приложения, подходит для одностороннего обмена данными без сложной авторизации;
- локальное REST-приложение — для кастомной автоматизации конкретного портала с UI-встраиванием;
- приложение в Маркетплейсе — для тиражируемого продукта, рассчитанного на многих клиентов;
- роботы и триггеры в бизнес-процессах CRM — для логики, которая должна срабатывать автоматически при смене стадии сделки, без участия пользователя.
Готовые сценарии и ресурсы разработчика
У Битрикс24 есть официальный портал для разработчиков с документацией по REST API, SDK для разных языков и готовыми примерами обработчиков событий. Разумно использовать эти ресурсы не как справочник «для быстрого копирования», а как источник понимания архитектурных ограничений платформы — лимитов на количество запросов в единицу времени, формата пакетных запросов (batch), особенностей работы с правами доступа при вызовах от имени приложения.
Отдельного внимания заслуживают готовые сценарии для типовых интеграций — синхронизация каталога товаров и заказов, о которой мы писали в статье «Получение товаров заказа 1С-Битрикс API», или мобильные кастомные приложения для Битрикс24, разбор которых есть в статье «Мобильное приложение для Битрикс24: интеграция и кастомная разработка». Изучение подобных готовых кейсов часто экономит недели разработки — многие проблемы, с которыми сталкивается новый разработчик (устаревающие токены, ограничение по числу вебхуков, особенности пагинации в списках сделок), уже решены в этих референсных реализациях.
Типичные ошибки при разработке приложений для Битрикс24
Самая частая архитектурная ошибка — хранить access-токен как статичное значение вместо реализации полноценного механизма обновления через refresh-токен. Токены доступа Битрикс24 живут ограниченное время, и приложение, не умеющее их автоматически обновлять, начинает возвращать ошибки авторизации спустя час после первого успешного запроса — это классическая причина, по которой «работавшая вчера» интеграция внезапно перестаёт функционировать.
Вторая типичная проблема — игнорирование лимитов API. Битрикс24 ограничивает количество запросов в секунду на один портал, и приложение, которое делает синхронные вызовы в цикле по каждой сделке вместо использования batch-запросов, упирается в лимит уже на портале среднего размера. Правильная архитектура — группировать запросы через batch-метод и обрабатывать ответ с учётом ограничения по размеру пакета.
Третья ошибка — обработка события деинсталляции по остаточному принципу или вообще без неё. Когда клиент удаляет приложение с портала, backend обязан корректно завершить все связанные процессы и удалить неактуальные токены — иначе в базе годами копятся «мёртвые» подключения, которые усложняют поддержку и потенциально создают риск безопасности.
Как мы разрабатываем приложения и интеграции для Битрикс24
В Codeking для большинства заказчиков мы разрабатываем именно локальные приложения — это даёт полную гибкость под конкретные бизнес-процессы без накладных расходов на прохождение модерации Маркетплейса. Для типовых задач — синхронизация с 1С, генерация документов, интеграция с внешними сервисами — мы используем собственную библиотеку обработчиков, которая уже учитывает обновление токенов, батчинг запросов и корректную обработку деинсталляции.
Если решение действительно тиражируемо и востребовано у широкого круга компаний, мы обсуждаем с заказчиком вариант публикации в Маркетплейсе — это отдельный трек с собственными требованиями к качеству кода, документации и поддержке, но он открывает возможность монетизировать разработку за пределами одного проекта.