События REST

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

Это открывает широкие возможности по синхронизации данных с внешней системой, различным автоматическим проверкам согласованности информации, автозапуску сценариев в приложениях и многое другое.

В этом уроке мы научимся работать с событиями, реализовав простую задачу – автоформатирование ФИО в контактах CRM, чтобы они гарантировано начинались с заглавных букв.

Зайдем в кабинет разработчика и создадим новое приложение, как мы это делали в предыдущем уроке.

Нажмем кнопку «Добавить приложение». Выберем, как и ранее, основной регион для будущей публикации решения. В карточке приложения нажмем на кнопку «Создать» и укажем тип «Использовать REST API». Убедимся, что скоуп CRM добавлен в список разделов.

Скачайте пример, прикрепленный к уроку, и загрузите его на свой сервер так же, как мы это делали на уроках, посвященным локальным интеграциям.

Вставьте в карточке версии пути к выгруженному на сервер приложению, как мы это делали ранее. Скопируйте значения из полей client_id, client_secret и вставьте их в соответствующие константы в файле settings.php.

Посмотрим код примера, и начнем с install.php. Здесь вызывается уже известный нам из предыдущих уроков метод installApp, который сохранит полученные токены авторизации в файл для дальнейшего использования.

Здесь же в примере мы регистрируем сразу и обработчик второго события, а именно onCrmContactAdd. В результате, наш обработчик будет вызываться и при добавлении нового контакта в CRM, и при изменении существующего.

Вернемся в кабинет разработчика.

Текущая страница позволит установить приложение на наш Битрикс24 и протестировать его до публикации в Битрикс24.Маркет.

Укажем адрес своего Битрикс24, на котором мы являемся администратором и нажмем Установить.

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

Битрикс24 автоматически откроет приложение после завершения установки, поскольку у нашего приложения есть пользовательский интерфейс.

Перейдем в контакты CRM, и добавим новый контакт, указав значения в полях ФИО в самом разном виде. Обновим список и обнаружим, что обработчик из нашего приложения сработал, поменяв формат введенного имени.

Давайте посмотрим, как работает эта магия.

Для начала посмотрим, что именно передает Битрикс24 на наш обработчик в своем POST-запросе. Это массив очень простой структуры.

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

Эти данные можно использовать для вызовов REST из приложения. Однако, авторизационные данные не всегда приходят в обработчик события. Не всегда изменения данных происходят в результата вмешательства конкретного пользователя, а значит, Битрикс24 не всегда может понять, чьи токены авторизации он должен передать в обработчик события.

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

Кроме того, тиражное приложение, опубликованное в Битрикс24.Маркет, может одновременно использоваться на большом количестве разных порталов, а значит для очередного вызова REST запроса приложение должно указывать, к какому конкретно порталу делается вызов прямо сейчас.

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

Далее, мы вызываем метод crm.contact.get для получения полной информации о добавленном или измененном контакте, взяв его идентификатор из POST-запроса.

Следующим шагом, мы преобразуем поля, содержащий имя, фамилию и отчество в нужный нам регистр.

И наконец, мы проверяем, отличаются ли преобразованные нами значения от полученных в текущем контакте. Это очень важная проверка, которая позволит нам избежать зацикливания событий. Ведь когда мы обновляем данные контакта, вызвав метод crm.contact.update, подставив туда преобразованные нами значения, то в результате изменений, Битрикс24 снова инициирует событие onCrmContactUpdate и так далее, по кругу. Только мы в своем коде можем понять, что дальнейшие преобразования не нужны и прервать этот порочный круг.

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