Битрикс24 REST API

Чтобы понять, как работают вебхуки, нужно сначала разобрать определение REST API. REST API (от англ. Representational State Transfer, «передача репрезентативного состояния») - это интерфейс для упрощения разработки приложения. Грубо говоря, язык общения между разработчиком и конкретным приложением.

Представьте, что есть у нас Битрикс - одна большая система. В ней существуют разные объекты: сделки, лиды, компании, контакты, бизнес-процессы, дела, задачи, сотрудники, настройки и т.д.. Объектом будет любая сущность, у которой есть какие-то свойства и с которой мы можем производить какие-либо действия - методы. Получить сумму сделки - метод. Изменить стадию сделки - тоже метод.

Представим, как программист пишет модуль или расширение для системы. В случае Битрикса он использует язык PHP. Чтобы не писать много кода с нуля, он использует язык упрощенных команд, которые будет понимать только эта конкретная система - ее API. Чтобы разработчик и система "понимали" друг друга - используется объектно-ориентированная модель приложения, на основе которой работает REST API.

Чтобы все это работало, разработчики Битрикс пишут, грубо говоря, карту, которая "знает" все о системе - какие есть объекты, что и как с ними можно делать. Например, описан объект сделки: ее свойства, код создания новой, код удаления уже созданной и т.д. В итоге программист должен просто использовать метод удаления. В целом любое действие, которое производится вручную в Битриксе, также описано в этой модели и может быть вызвано из кода.

Это сделано, чтобы код приложения был универсальным и легко поддерживаемым. Не нужно с нуля разбираться в архитектуре базы данных, чтобы написать скрипт удаления сделки. Также, если разработчики Битрикса поменяют что-то под капотом этой модели - глобально ничего не сломается, система будет принимать те же самые команды API, просто выполнять их станет немного по-другому, но разработчика это уже не коснется.

Без API разработчик должен был бы писать что-то в духе "пойди в базу данных, удали/создай в такой таблицу такую-то строку, а в такой - такую-то". Эта же команда с API выглядит проще - "удали эту сделку". Надеюсь, в общих чертах все понятно.

Когда уже про вебхуки

Собственно, при чем тут вебхуки. REST API как таковой можно использовать при написании приложения для Битрикс на языке PHP. Но нам не нужно разрабатывать приложение, нам нужна какая-то простая интеграция Битрикса с внешним сервисом. Например, чтобы при заполнении формы на сайте у нас создавался лид в Битрикс.

Вебхуки - это инструмент, который открывает доступ к большинству методов REST API без написания кода, либо дает возможность уведомлять внешнюю систему об изменениях в Битрикс.

Есть 2 вида вебхуков: входящие и исходящие. Входящий вебхук запускается при обращении к порталу Битрикс по определенному URL. Иначе говоря, можно открыть в браузере страницу, и Битрикс выполнит соответствующее действие. Само собой, страницу может открывать скрипт на нашем сервере либо бизнес-процесс в самом Битриксе.

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

Создаем вебхук

Чтобы Битрикс понимал, что поступившая команда прилетела из безопасного источника и ее можно выполнять - в адресе указывается специально сгенерированный ключ доступа. Чтобы получить ключ, нужно перейти в раздел "Разработчикам>Другое>Входящий вебхук".

Раздел разработчикам Битрикс

Раздел другое Битрикс

Создание входящего вебхука Битрикс

Ключ доступа видит только создавший его пользователь. Даже если администратор портала отредактирует доступ - ключ сбросится, а создателем доступа вместо старого владельца станет администратор.

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

Права доступа вебхука

В итоге мы получаем URL адрес вида:

  • https://yourportal.bitrix24.ru/rest/23/ydgt3vidym4l110o/crm.lead.get.json?id=1

URL имеет определенную структуру:

  • https://yourportal.bitrix24.ru - адрес портала Битрикс;
  • /rest - указание, что идет обращение к REST API;
  • /23 - ID пользователя, создавшего доступ;
  • /ydgt3vidym4l110o - строка ключа доступа;
  • /crm.lead.get - метод, который будет использоваться;
  • .json - формат ответа, т.н. "транспорт" - json или xml (по-умолчанию json)
  • ?id=1 - наименование и значение параметра, который мы передаем в Битрикс.

Как видно из структуры ссылки, все значения, необходимые для работы метода, передаются в параметрах URL адреса. В параметрах вебхуков также можно указывать множественные значения - для этого нужно записать их в виде массива.

  • ?param[]=value1&param[]=value2

Для каждого метода существует свой набор необходимых параметров, которые описаны в документации Битрикс по работе с REST API.

Чтобы просмотреть, изменить или удалить созданные вебхуки, нужно перейти в раздел "Разработчикам>Интеграции", где будет список всех созданных вебхуков.

Переход в раздел Интеграции

Список созданных вебхуков в Битрикс

Следует учитывать, что в облачной версии Битрикс действует ограничение на 2 запроса к REST API в секунду. Если ограничение превышается более 50 раз - функционал блокируется и проблема решается через техподдержку.

ограничение REST API в Битрикс

Вебхуки можно запускать из Бизнес процессов.

Ограничения вебхуков

  • Утечка ключа доступа создает серьезную угрозу безопасности для данных портала.
  • Часть методов REST API недоступна для использования в вебхуках.
  • Для входящих вебхуков в облачной версии действует ограничение на 2 запроса в секунду. Если ограничение превышается 50 раз - возможность приема входящих вебхуков блокируется. В коробочной версии таких ограничений нет.