REST API Битрикс24: вебхуки, приложения и OAuth

Интеграцию с Битрикс24 обычно начинают с вебхука, потому что это быстро. Через несколько месяцев выясняется, что выбранный способ определяет и модель прав, и надёжность, и возможность тиражирования. Разберём варианты до того, как выбор станет необратимым.

Три способа достучаться до портала

• Входящий вебхук. Портал выдаёт URL с секретным кодом; ваш скрипт дёргает методы REST от имени создавшего вебхук пользователя.
• Исходящий вебхук. Портал сам отправляет запрос на ваш адрес, когда происходит событие.
• Приложение. Полноценная интеграция с авторизацией через OAuth, собственными правами, интерфейсом внутри портала и возможностью публикации в Маркетплейсе.

Входящий вебхук: быстро, но с последствиями

Вебхук делается за минуту и отлично подходит для внутренней утилиты. Но у него есть свойства, которые стоит осознавать:

• Он работает от имени конкретного пользователя. Всё, что делает интеграция, видно в истории как действия этого сотрудника, и ограничено его правами.
• Он умирает вместе с пользователем. Сотрудник уволился, его учётку отключили — интеграция встала. Это классическая причина инцидентов «всё сломалось, а мы ничего не меняли».
• Секрет в URL. Такой адрес легко утекает в логи, в мессенджер, в чужой конфиг. Компрометация означает полный доступ в рамках прав пользователя.
• Он не тиражируется. Для каждого нового портала всё создаётся руками.

Практический вывод: если вебхук всё-таки используется, создавайте его от отдельной технической учётной записи с минимально необходимыми правами, а не от аккаунта руководителя.

Исходящие вебхуки и события

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

• Доставка не гарантирована абсолютно. Ваш сервер был недоступен — событие может потеряться. Критичные сценарии нуждаются в сверке состояния, а не только в реакции на события.
• Возможны дубли. Обработчик обязан быть идемпотентным: повторное событие о той же сделке не должно порождать второй счёт.
• В событии приходит минимум данных. Обычно идентификатор и тип; за подробностями всё равно придётся идти в REST.
• Отвечать нужно быстро. Долгая обработка прямо в обработчике приводит к таймауту. Правильный подход — принять, положить в очередь, ответить, обработать асинхронно.

Приложения: локальные и тиражные

Локальное приложение живёт на одном портале, но в отличие от вебхука авторизуется по OAuth, имеет собственный набор прав (scope) и может встраивать интерфейс в портал. Это разумный выбор для корпоративной интеграции, которую планируют развивать.

Тиражное приложение публикуется в Маркетплейсе и устанавливается на любой портал. Здесь добавляются требования: хранение токенов для множества порталов, корректная обработка установки и удаления, поддержка и облака, и коробки, если вы заявляете обе платформы.

OAuth: где обычно ломается

Схема стандартная: приложение получает пару токенов — короткоживущий access и долгоживущий refresh. Первый протухает быстро, второй позволяет получить новую пару.

Две типичные ошибки:

• Обновление токена по расписанию, а не по ошибке. Надёжнее реагировать на ответ об истёкшем токене: обновить пару и повторить исходный запрос один раз.
• Гонка при обновлении. Если несколько параллельных процессов одновременно обнаружат протухший токен и полезут обновлять его, часть из них получит невалидную пару. Обновление нужно сериализовать блокировкой.

Отдельно: адрес портала может измениться, а вместе с ним и домен для запросов. Хранить его нужно рядом с токенами и обновлять при получении новых данных, а не зашивать в конфиг.

Лимиты и batch

REST Битрикс24 ограничивает интенсивность запросов. Интеграция, которая в цикле дёргает метод на каждый элемент списка, упирается в лимит на первой же выгрузке в несколько тысяч записей.

Что помогает:

• Batch. Один запрос вместо пятидесяти; внутри — команды, которые могут ссылаться на результаты предыдущих.
• Списочные методы с фильтром и выборкой полей. Запрашивать только нужные поля дешевле, чем тянуть всё и фильтровать у себя.
• Постраничный обход по идентификатору. Для больших выгрузок он устойчивее обычного смещения, потому что данные меняются во время обхода.
• Обработка ответа о превышении лимита. Пауза с увеличением интервала вместо немедленного повтора.

Что выбрать

Короткий ориентир: разовая утилита для себя — входящий вебхук от технической учётки. Постоянная корпоративная интеграция — локальное приложение. Решение, которое планируется продавать или ставить нескольким клиентам, — тиражное приложение с самого начала, потому что переезд на него из вебхуков всегда оказывается отдельным проектом.