REST API Битрикс24

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

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

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

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

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

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

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

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

Посмотрим код примера, и начнем с файла cextrest.php.

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

Для начала мы добавим в класс внутреннюю переменную, которая будет отвечать за то, к какому именно порталу будут выполняться REST-запросы. В качестве значения этой переменной мы будем использовать идентификаторы порталов Битрикс24 member_id. Казалось бы, что лучше использовать для этого адреса порталов, однако на практике адрес портала может быть изменен пользователем. Это касается и облачных Битрикс24, и коробочных. Member_id в смысле уникальности намного надежнее.

Базовый класс, как вы знаете, сохранял токены авторизации в файле settings.json. Теперь же токены будут складироваться в папке settings в отдельных файлах, название которых формируется из значения member_id.

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

Файл install.php, практически, не отличается от примера, который я показывал в уроке про REST-события. Однако, вместо класса Crest в текущем примере я обращался к классу наследнику CExtRest.

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

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

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

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

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

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

Давайте посмотрим, что произошло внутри.

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

Во-вторых, посмотрим, что именно передает Битрикс24 на наш обработчик в своем POST-запросе.

Мы уже видели этот массив и знаем, что он из себя представляет. Но сейчас обратим внимание на параметры, которые пришли в POST-запросе в ключе auth. Именно отсюда мы должны получить идентификатор портала, чтобы объяснить классу CExtRest, с каким порталом ему предстоит работать.

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

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

Давайте убедимся, что это сработает, если мы установим приложение на еще один Битрикс24. Вернемся в кабинет разработчика, укажем адрес другого Битрикс24 и установим приложение на него.

Проверим, что на стороне приложения появился новый файл с нужными параметрами авторизации.

Перейдем в список контактов в этом новом Битрикс24 и добавим новый контакт с заведомо неправильно указанными именем и фамилией.