Локальное приложение Битрикс24: с чего начать разработку

Локальное приложение — самый быстрый способ начать разработку под Битрикс24, если у вас уже есть конкретный портал (свой или клиента) и не стоит задача публикации в Маркете. В отличие от вебхука, локальное приложение даёт полноценный OAuth-поток, доступ к виджетам и роботам, и при этом не требует прохождения модерации — регистрируется прямо в разделе «Разработчикам» нужного портала за несколько минут. Ниже — с чего начать и на какие грабли не наступить в первую неделю.

Регистрация приложения в разделе «Разработчикам»

В любом портале Битрикс24 есть раздел Приложения → Разработчикам → Другое → Локальное приложение. При создании указываете название, путь обработчика (URL, на который портал будет перенаправлять пользователя при открытии приложения и который будет использован для установки) и запрашиваемые права доступа (scope): crm, task, bizproc, disk, calendar и десятки других, каждое отдельно включается чекбоксом. После сохранения система выдаёт client_id и client_secret — это постоянные значения именно для этого портала, их нужно сохранить в конфигурации вашего сервиса.

Установка: обработчик ON_APP_INSTALL

При первом открытии приложения пользователем портал делает запрос (обычно POST) на указанный вами Handler path с параметрами AUTH_ID (access_token), REFRESH_ID (refresh_token), member_id (уникальный идентификатор портала), а также, при установке через событие, кодом события ONAPPINSTALL. Ваша задача на этом шаге — сохранить member_id вместе с токенами в базе данных: без этой связки вы не сможете определить, какому порталу принадлежит очередной входящий запрос, если приложение однажды будет использоваться не только вами.

POST /install (ваш обработчик)
Content-Type: application/x-www-form-urlencoded

AUTH_ID=a1b2c3...&REFRESH_ID=d4e5f6...&member_id=abc123def456&AUTH_EXPIRES=3600

// Сохраняем в БД:
// INSERT INTO installations (member_id, access_token, refresh_token, expires_at) VALUES (...)

Обновление токена по refresh_token

access_token живёт около часа. При получении ошибки expired_token в ответе на любой REST-вызов нужно вызвать oauth.bitrix.info/oauth/token с grant_type=refresh_token, вашим client_id, client_secret и текущим refresh_token — в ответ придёт новая пара токенов. Важно: refresh_token тоже меняется при каждом обновлении, старое значение становится недействительным — обновляйте оба значения в базе атомарно, иначе при параллельных запросах можно получить рассинхронизацию и потерять доступ к порталу до повторной установки.

Ограничение прав: scope и его последствия

Локальное приложение, в отличие от вебхука, запрашивает права не по конкретным методам, а по крупным блокам (scope): crm даёт доступ ко всем crm.*-методам, bizproc — ко всем bizproc.*, и так далее. Здесь легко переусердствовать и запросить лишние права «на всякий случай» — это не только избыточный риск при утечке токена, но и повод для настороженности у администратора портала при установке, если приложение публикуется публично. Запрашивайте минимально необходимый набор, а расширяйте только при реальной необходимости новой функциональности.

Куда встраивается интерфейс приложения

У локального приложения по умолчанию есть собственная точка входа — раздел в левом меню портала («Приложения» → название вашего приложения), который открывает ваш iframe напрямую, без привязки к конкретной сущности CRM. Если нужна интеграция именно в карточки сущностей — это делается отдельно через placement.bind, как и для полноценного облачного приложения; локальное приложение полностью поддерживает виджеты и роботов, разница только в способе регистрации и отсутствии модерации.

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

Структура минимального рабочего проекта

1. 1.Endpoint /install — принимает установку, сохраняет токены и member_id
2. 2.Endpoint /uninstall — принимает событие ONAPPUNINSTALL, удаляет данные портала из вашей БД
3. 3.Middleware обновления токена — перехватывает expired_token и делает retry запроса после обновления
4. 4.Основной UI приложения — то, что видит пользователь при открытии из левого меню
5. 5.Очередь фоновых задач — для операций, которые не должны блокировать интерфейс (импорт, синхронизация)

Локальная разработка: туннелирование и HTTPS

Битрикс24 требует, чтобы Handler и все точки размещения были доступны по HTTPS с валидным сертификатом — localhost напрямую не подойдёт. На этапе разработки поднимайте туннель (ngrok, Cloudflare Tunnel или аналог) к локальному серверу и регистрируйте приложение с временным HTTPS-адресом туннеля; при каждом перезапуске туннеля с новым адресом придётся обновлять Handler в настройках приложения на портале, поэтому многие разработчики фиксируют туннель на постоянный поддомен, чтобы не переустанавливать приложение каждый день.

Правило одного member_id — одна запись токенов. Никогда не привязывайте токены к email администратора или к домену портала как к первичному ключу — домен может меняться, а member_id остаётся стабильным идентификатором инсталляции на всё время жизни приложения на этом портале. Использование домена как ключа — частая причина, по которой интеграция «слетает» после переезда клиента на новый адрес портала.

Курс школы: Вебхуки в Битрикс24 без программирования — от 9 990 ₽

Тестирование на нескольких ролях пользователей

Приложение, которое тестировалось только под администратором портала, почти гарантированно сломается для рядового менеджера: у обычного сотрудника нет доступа к части CRM-сущностей, нет прав на настройки, а иногда ограничена видимость чужих сделок. Прежде чем считать приложение готовым, откройте его под учётной записью с правами обычного менеджера и убедитесь, что все сценарии (в том числе обработка ошибок доступа ACCESS_DENIED) работают предсказуемо, а не падают с необработанным исключением.

Приложение, работающее только под администратором портала, — это демо, а не продукт: 90% реальных пользователей CRM — не администраторы.

Переход от локального приложения к публикации в Маркете

Если локальное приложение показало себя хорошо на одном портале и возникает идея предложить его другим компаниям, техническая миграция минимальна — тот же код, тот же OAuth-поток, но регистрация делается уже на уровне партнёрского кабинета разработчика с прохождением модерации и заполнением карточки в Маркете (описание, скриншоты, тарификация). Стоит заранее спроектировать мультитенантность в базе данных (хранение по member_id, а не по единственному захардкоженному порталу), чтобы этот переход не потребовал переписывания слоя хранения токенов.

Частые ошибки первой недели разработки

Разработчики, впервые столкнувшиеся с локальным приложением, обычно проходят через один и тот же набор граблей. Первая — хранение единственного access_token в конфиг-файле или переменной окружения вместо базы данных: работает, пока вы тестируете на одном портале руками, и разваливается, как только приложение ставится на второй портал или токен обновляется в фоне и файл конфигурации не синхронизируется между процессами. Вторая — обработка установки без идемпотентности: если пользователь случайно откроет приложение дважды до завершения первого редиректа, обработчик /install может создать две записи установки вместо обновления одной, и в дальнейшем неясно, какой токен актуален.

1. 1.Не храните токены в файлах или переменных окружения — только в базе данных, привязанные к member_id
2. 2.Делайте /install идемпотентным: при повторной установке обновляйте существующую запись, а не создавайте дубликат
3. 3.Не забывайте про /uninstall — очищайте все данные портала, включая запланированные фоновые задачи и вебхуки на внешние сервисы
4. 4.Тестируйте обновление токена намеренно — не ждите первого протухания в проде, чтобы обнаружить баг в этой логике
5. 5.Логируйте каждую установку и удаление отдельно от обычных операционных логов — это данные для поддержки и биллинга

Обработчик деинсталляции и очистка данных

Событие ONAPPUNINSTALL приходит на тот же Handler, что и установка, но с другим кодом события в теле запроса. На этом шаге нужно не только пометить установку как неактивную в своей базе, но и снять все зарегистрированные placement.bind, event.bind и bizproc.robot.add, если это в принципе ещё возможно (иногда к моменту получения события токен уже недействителен, и снять привязки не получится — в таком случае они «отвалятся» сами вместе с удалением приложения на стороне портала, но лучше не полагаться на это молча). Обязательно остановите все фоновые синхронизации и очереди, связанные с этим member_id, иначе ваш сервис продолжит впустую пытаться достучаться до портала, которого для него больше не существует.

Работа с несколькими окружениями: dev, staging, прод

Даже для локального приложения, разрабатываемого под одного клиента, полезно разделять окружения: одно приложение на тестовом портале для разработки новых фич, второе — реальная установка на портале клиента. Использование одного и того же client_id и client_secret для обоих сценариев допустимо технически, но смешивает логи и токены разных окружений в одной таблице, что усложняет отладку. Заведите отдельную запись регистрации приложения для тестового портала — это бесплатно и снимает риск случайно отправить тестовый запрос в боевую CRM клиента.

Документирование прав доступа для заказчика

Если приложение разрабатывается на заказ, а не для себя, приложите к сдаче проекта короткий документ с перечнем запрошенных scope и объяснением, зачем каждый из них нужен: это не бюрократия, а практическая защита от вопроса службы безопасности заказчика «почему интеграция для печати документов просит доступ к телефонии» на этапе согласования установки. Отсутствие такого объяснения — частая причина, по которой согласование локального приложения у крупного клиента затягивается на недели вместо одного звонка.

Что делать, если портал клиента переходит на self-hosted версию

Отдельный редкий, но встречающийся сценарий — клиент переезжает с облачного Битрикс24 на коробочную версию продукта (Битрикс24 в редакции для установки на собственный сервер). REST API там формально тот же, но локальное приложение, зарегистрированное на облачном портале, не переносится автоматически — потребуется новая регистрация и новый обмен client_id/client_secret уже на self-hosted инсталляции. Закладывайте эту возможность в архитектуру заранее, если работаете с крупными корпоративными клиентами, у которых миграция на собственную инфраструктуру — реалистичный сценарий через год-два после старта проекта.