Локальное приложение Битрикс24 с OAuth: когда входящего вебхука не хватает

Ко мне периодически прилетает одна и та же вводная: «уже подключили входящий вебхук, льём заказы в CRM, но теперь нужна вкладка в карточке сделки» или «хотим свой робот в конструкторе бизнес-процессов». На этом моменте выясняется, что вебхук для такой задачи не подходит вообще, и разговор переходит к другому классу интеграции: локальное приложение Битрикс24 с полноценной OAuth-авторизацией. Разница между этими двумя способами подключения к REST API не в объёме кода, а в наборе возможностей, которые открывает каждый вариант.

Чем локальное приложение Битрикс24 отличается от входящего вебхука

Входящий вебхук - это URL с зашитым токеном вида https://portal.bitrix24.ru/rest/12/xxxxxxxxxxxxxxxx/, который создаётся в пару кликов в разделе для разработчиков. При создании сразу выбираешь конкретный набор методов REST API, которые вебхук будет обслуживать, а токен привязывается к правам конкретного сотрудника, от чьего имени его выпустили. Никакого протокола авторизации тут нет: отправляешь POST или GET с нужными параметрами и получаешь ответ.

Локальное приложение работает по OAuth 2.0. Регистрируешь его в том же разделе для разработчиков, указываешь URL обработчика, отмечаешь нужные разделы прав (crm, задачи, диск, бизнес-процессы, размещения и так далее) и получаешь пару client_id и client_secret. После установки Битрикс24 присылает на обработчик POST-запрос с событием ONAPPINSTALL и токенами access_token, refresh_token, а также application_token для проверки, что запрос действительно пришёл от портала. Access_token живёт около часа, и дальше приложение работает не от имени конкретного сотрудника, а как самостоятельная сущность со своим набором прав.

Когда входящего вебхука хватает с запасом

Если задача - закинуть данные в CRM в одну сторону и на этом закончить, вебхука достаточно почти всегда. Пример из практики: интернет-магазин на WooCommerce с оплатой через T‑Bank, заказ оплачен - обработчик эквайринга дёргает мой скрипт, скрипт вызывает crm.deal.add через входящий вебхук. Или связка попроще: форма на Tilda отправляет заявку прямо в crm.lead.add.json без промежуточного сервера. Туда же укладываются статусы доставки от СДЭК: получил трек-номер, обновил поле в сделке тем же вебхуком.

Никакой интерфейс внутри Битрикс24, никакая реакция на события портала здесь не нужны, а значит городить OAuth незачем. Я обычно и начинаю проекты с вебхука: он проверяется за один вечер, не требует отдельного сервера под install-обработчик и решает 70-80% типовых интеграционных задач, с которыми ко мне приходят.

Сценарии, где вебхука уже не хватает

Проблемы начинаются, когда логика должна жить внутри интерфейса Битрикс24 или реагировать на события портала, а не просто дёргаться снаружи.

• Вкладка или кнопка в карточке сделки, лида, компании - это размещение (placement), а размещения регистрирует только приложение через OAuth, обработчик вебхука для этого не подходит в принципе.
• Свой робот в конструкторе бизнес-процессов - метод bizproc.robot.add точно так же требует зарегистрированного приложения с пользователем, от имени которого робот получает права.
• Реакция на подключение или отключение интеграции: у приложения есть события ONAPPINSTALL и ONAPPUNINSTALL, у вебхука такого жизненного цикла нет вообще.
• Живучесть интеграции: вебхук привязан к правам конкретного сотрудника. Уволили его или сменили пароль с принудительным разлогином - хук может перестать работать, и это не всегда сразу заметно. Приложение с OAuth так жёстко на одну учётку не завязано.
• Расширение прав по ходу проекта: у вебхука набор методов фиксируется один раз при создании, для нового раздела REST API нужен новый вебхук и правки в коде. У приложения права можно расширить, обновив запрос при переустановке.

Как создать локальное приложение в Битрикс24 пошагово

Захожу в раздел для разработчиков (в разных редакциях интерфейса он называется «Разработчикам» -> «Другое» -> «Локальное приложение», меню у Битрикс24 периодически перекраивают). Дальше по шагам:

1. Указываю название приложения и URL обработчика - публично доступный HTTPS-адрес, куда портал будет присылать install и последующие события.
2. Отмечаю чекбоксами нужные разделы прав: crm, tasks, bizproc, placement, disk и так далее. Беру только то, что реально использую - лишние права потом сложнее объяснить при повторной установке приложения.
3. Сохраняю приложение и получаю client_id и client_secret. Это секретные значения, храню их в переменных окружения на сервере, а не в репозитории.
4. Устанавливаю приложение на портал. На обработчик прилетает POST-запрос с полями события, доменом портала и парой токенов.

Важный момент: локальное приложение работает только с тем порталом, где его создали. Если одно и то же приложение нужно поставить разным клиентам с их отдельными порталами, это уже задача для публикации в Маркетплейс Битрикс24 с прохождением модерации, а не для локального приложения.

Вот минимальный обработчик install на Python:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/bitrix/install", methods=["POST"])
def install():
    data = request.form
    if data.get("event") != "ONAPPINSTALL":
        return jsonify({"error": "unexpected_event"}), 400

    auth = {
        "access_token": data.get("auth[access_token]"),
        "refresh_token": data.get("auth[refresh_token]"),
        "domain": data.get("auth[domain]"),
        "member_id": data.get("auth[member_id]"),
        "application_token": data.get("auth[application_token]"),
    }

    save_tokens(auth)
    return jsonify({"result": "ok"})

На моей практике такой каркас с обработчиком install и сохранением токенов собирается за 1-2 дня, дальше время уходит уже на конкретные виджеты и роботов.

Получение и обновление OAuth-токена на практике

На install Битрикс24 сразу присылает рабочую пару access_token и refresh_token, отдельно ничего обменивать не нужно. А вот дальше начинается рутина: access_token живёт около часа, и если запрос к REST API уходит с истёкшим токеном, в ответ приходит ошибка просроченного токена. Обновляю токен GET-запросом к серверу авторизации oauth.bitrix24.tech, передавая refresh_token, client_id и client_secret:

curl --get https://oauth.bitrix24.tech/oauth/token/ \
  -d "grant_type=refresh_token" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "refresh_token=$REFRESH_TOKEN"

В ответе снова приходит свежая пара access_token и refresh_token, а старый refresh_token после использования перестаёт работать. Поэтому сохраняю оба значения заново, а не только access_token. Токены храню в связке с доменом портала и member_id: если приложение когда-нибудь пойдёт в Маркетплейс и встанет на несколько порталов, у каждого будет своя пара токенов.

Виджеты, роботы и автоустановка: что даёт OAuth-приложение

Разберём на примерах, что именно открывает OAuth и чего вебхук сделать не может.

Вкладка в карточке сделки регистрируется методом placement.bind: указываю код размещения, например CRM_DEAL_DETAIL_TAB, URL обработчика, который отрисует содержимое внутри iframe, и заголовок вкладки. После регистрации в каждой карточке сделки появляется дополнительная вкладка с моим интерфейсом, который дёргает REST API уже от имени приложения.

Робот для конструктора бизнес-процессов регистрируется методом bizproc.robot.add: код робота, обработчик, пользователь, от имени которого робот получает права через AUTH_USER_ID, и список свойств, которые появятся в конструкторе как настраиваемые поля. Если робот ждёт внешнее событие дольше, чем длится один HTTP-запрос, включаю USE_SUBSCRIPTION, чтобы бизнес-процесс не завершился раньше времени.

curl -X POST "https://$DOMAIN/rest/placement.bind" \
  -d "auth=$ACCESS_TOKEN" \
  -d "PLACEMENT=CRM_DEAL_DETAIL_TAB" \
  -d "HANDLER=https://yourapp.example.com/tab.php" \
  -d "TITLE=Мои данные"

curl -X POST "https://$DOMAIN/rest/bizproc.robot.add" \
  -d "auth=$ACCESS_TOKEN" \
  -d "CODE=notify_manager" \
  -d "HANDLER=https://yourapp.example.com/robot.php" \
  -d "AUTH_USER_ID=1" \
  -d "NAME=Уведомить менеджера" \
  -d "USE_SUBSCRIPTION=Y"

Автоматизацию часто выношу за пределы самого приложения: OAuth-обработчик собирает данные из карточки и отправляет их вебхуком в n8n, а там уже строится ветвление, повторные попытки и уведомления в мессенджеры. Так проще менять логику без переустановки приложения на портале.

Сколько стоит разработка локального приложения Битрикс24

Стоимость зависит от количества точек интеграции, а не от отрасли клиента. Бэкенд под install-обработчик и хранение токенов обычно поднимаю на отдельном сервисе, для такой задачи хорошо подходит API/бэкенд на Laravel, а приложения с несколькими виджетами и роботами дальше вырастают в отдельный веб-сервис. Вот мой актуальный ориентир по прайсу:

Условия и возможности Битрикс24 меняются, поэтому перед запуском я уточняю их у самого сервиса.

Частые вопросы

Можно ли обойтись без сервера для локального приложения Битрикс24

Нет, нужен публично доступный HTTPS-адрес для обработчика install и последующих запросов. Без него портал не сможет прислать токены и события, а значит и OAuth-схема не заработает.

Что будет, если не обновлять access_token вовремя

Через час токен перестаёт действовать, и REST API отвечает ошибкой просроченного токена. На практике обновляю refresh_token заранее, до момента реального запроса, а не по факту ошибки, чтобы не терять секунды на повторный вызов.

Можно ли использовать одно локальное приложение на нескольких порталах Битрикс24

Нет, локальное приложение привязано к тому порталу, где его установили. Для нескольких порталов нужно публиковать приложение в Маркетплейс Битрикс24 и проходить их модерацию, это уже другой процесс.

Стоит ли сразу делать OAuth-приложение, если пока хватает вебхука

Смысла нет. Обычно начинаю с вебхука для быстрого пилота и перехожу на локальное приложение только когда появляется реальная задача под виджет, робота или автоустановку. Переезд с вебхука на OAuth не требует полной переделки бизнес-логики, меняется в основном слой авторизации.