Локальное приложение: создание

Локальное приложение — это OAuth-приложение, установленное на один конкретный портал без публикации в Маркетплейсе. Оно даёт то, чего не может вебхук: авторизацию OAuth 2.0, встройки в интерфейс и действия от имени пользователя. Разберём, как его создать и настроить правильно.

Когда нужно локальное приложение

Локальное приложение — золотая середина между вебхуком и тиражным решением из Маркетплейса. Его выбирают, когда:

• Нужны встройки в интерфейс (placement): своя вкладка в карточке сделки, виджет на рабочем столе, кнопка в меню.
• Требуется OAuth 2.0 — действия от имени пользователя, а не одного владельца, как у вебхука.
• Решение делается под один портал и не выкладывается на Маркетплейс для чужих компаний.
• Нужны обработчики событий и отложенная логика на вашем backend.

Два типа: серверное и клиентское

При создании портал предлагает выбрать тип приложения — от него зависит модель авторизации.

Для серьёзных интеграций почти всегда выбирают серверный тип: только он даёт полноценный OAuth, обработку событий и безопасное хранение client_secret.

Пошаговое создание

Приложение создаётся в том же разделе, что и вебхук:

1. Левое меню → «Разработчикам» → «Другое» → «Локальное приложение».
2. Выберите тип (серверное — «Использует только API» или с интерфейсом).
3. Укажите путь обработчика (Handler URL) — адрес, который открывается при запуске приложения.
4. Укажите путь для первоначальной установки (Installation URL) — страница, куда портал шлёт токены при установке.
5. Отметьте нужные права (scope).
6. Сохраните — портал выдаст client_id (код приложения) и client_secret (ключ).

Установка и получение токенов

При установке приложения портал открывает ваш Installation URL и передаёт параметры авторизации — в том числе AUTH_ID (access_token), REFRESH_ID (refresh_token), member_id и домен. Их нужно сохранить.

// POST на ваш INSTALL URL при установке
AUTH_ID       = access_token (живёт 1 час)
AUTH_EXPIRES  = 3600
REFRESH_ID    = refresh_token (для обновления)
member_id     = идентификатор портала
DOMAIN        = mycompany.bitrix24.ru

Для клиентского типа установку завершает JS-вызов:

BX24.init(function(){
  // ... логика установки
  BX24.installFinish();
});

После установки вызовы к API идут с access_token в параметре auth, а по истечении часа токен обновляется через refresh_token.

Встройки в интерфейс (placement)

Главное преимущество приложения перед вебхуком — placement, точки встраивания в интерфейс портала. Приложение регистрирует их методом placement.bind.

• CRM_DEAL_DETAIL_TAB — своя вкладка в карточке сделки.
• CRM_DEAL_DETAIL_ACTIVITY — блок в таймлайне.
• CALL_CARD — панель во время звонка.
• LEFT_MENU — пункт в левом меню.

POST /rest/placement.bind.json
{
  "PLACEMENT": "CRM_DEAL_DETAIL_TAB",
  "HANDLER": "https://myapp.example.com/deal-tab",
  "TITLE": "Аналитика сделки"
}

При открытии встройки портал вызывает ваш HANDLER и передаёт контекст (например, ID текущей сделки), а страница внутри iframe работает через BX24.js.

Отладка и типовые ошибки

Частые проблемы при первой настройке локального приложения:

Для отладки полезны методы app.info (данные приложения), scope (выданные права) и placement.list (зарегистрированные встройки).

Итог

Локальное приложение — правильный выбор, когда одного портала мало для вебхука: нужны OAuth-авторизация, встройки в интерфейс и события. Создаётся оно так же просто, в разделе «Разработчикам», но требует backend для хранения токенов и обработки установки. Ключевые артефакты — client_id, client_secret, Handler и Installation URL.

Мы в B2Bsite разрабатываем локальные и тиражные приложения Битрикс24 под ключ: от архитектуры OAuth и хранения токенов до встроек в карточки CRM и обработчиков событий — с учётом безопасности и нагрузки.