REST API Битрикс24

Для решения таких задач лучше использовать REST API вместе с удобными инструментами раздела Разработчика в Битрикс24.

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

В этом разделе вы найдете готовые примеры для типовых задач.

Откроем раздел «Импортировать/экспортировать данные», а затем выберем пример «Импортировать контрагентов».

Мы видим слайдер с заготовленным сценарием добавления контакта CRM при помощи REST API.

Когда мы открыли слайдер, Битрикс24 уже сгенерировал уникальный код этого вебхука.

Генератор запросов

Ниже вы видите блок Генератор запросов.

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

Когда вы указали параметры и значения параметров, Битрикс24 формирует полный http-запрос за вас. Вы можете его подсмотреть, скопировать во внешнюю систему для выполнения или можете выполнить прямо здесь и сейчас.

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

Сейчас просто обратим внимание, что запрос был выполнен успешно и, поскольку мы вызывали метод добавления контакта, Битрикс24 сообщил нам, что был создан контакт с конкретным идентификатором.

Если мы перейдем в CRM, то мы увидим там этот контакт, только что созданный при помощи REST API.

Входящий вебхук и SDK CRest

Однако, нам важно научиться вызывать методы REST из своего программного кода. Здесь Битрикс24 нам тоже помогает.

Поскольку мы воспользовались готовым сценарием, то мы можем сразу скачать готовый пример на PHP. Давайте посмотрим, что внутри полученного архива.

В нем содержатся 5 файлов, созданных на основе официального минимально необходимого SDK для языка PHP. SDK называется CRest и он доступен для скачивания с Github.

Как уже было сказано, в скачанном нами примере, он целиком содержится.

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

Файл crest содержит PHP-класс для работы с Rest API. В дальнейшем мы просто им воспользуемся, не заглядывая в его реализацию.

Файл checkserver поможет нам проверить, правильно ли настроен наш веб-сервер, на котором будет выполняться PHP-код примера. Мы уже загрузили файлы на свой сервер и теперь можем проверить, все ли правильно.

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

Файл install.php нам сейчас не пригодится, поскольку предназначен для другой ситуации – для создания так называемого локального приложения.

Зато нам пригодится файл index.php. В 4-й строке мы обращаемся к методу call класса Crest. Это метод, который и помогает нам выполнять вызовы REST API.

Нужно лишь указать название метода. В данном случае это crm.contact.add. Также нужно указать параметры метода. В данном случае это параметр FIELDS, который является массивом с перечнем значений различных полей контакта. У других методов REST будут другие параметры, которые вы можете узнать из документации.

Результат вызова метода мы получим в массиве $result и выведем.

Давайте запустим пример. Откроем браузер и введем соответствующий адрес.

Пример отработал, результат показывает, что новый контакт с идентификатором был создан, а значит мы научились вызывать методы REST API из нашего кода!

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

Для некоторых сценариев было бы удобно, чтобы наша автоматизация срабатывала сама, если пользователь изменяет какие-то данные в Битрикс24. Для этого в локальных интеграциях есть инструмент, который называется «Исходящий вебхук».

Откроем раздел «Интегрировать с внешними системами» и выберем сценарий «Синхронизировать контрагентов». Этот заранее заготовленный сценарий позволит нам подписаться на изменение данных любого контакта в CRM и получить информацию о нем.

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

Вернемся в интерфейс Битрикс24. Вы видите, что здесь уже подготовлен для нас входящий вебхук, которым мы воспользуемся для получения подробностей об измененном контакте. Но сейчас нас больше интересует блок «Исходящий вебхук»

Указываем URL обработчика. Именно по этому адресу Битрикс24 передаст «сигнал» о том, что произошло некое событие, связанное с изменением данных.

Укажем в поле «События», какие именно изменения мы хотим отслеживать. В частности, OnCRMContactUpdate. Это значит, что при изменении любого контакта в CRM, Битрикс24 передаст информацию на указанный нами обработчик.

Итак, мы указали адрес обработчика, выбрали событие. Посмотрим внимательнее на код примера.

Сюда включен все тот же SDK, о котором я уже рассказывал ранее. Важное отличие от предыдущего примера – файл handler.php, ссылку на который мы указывали в интерфейсе настройки локальной интеграции ранее. В этот обработчик приходит POST-запрос от Битрикс24 с данными о произошедшем событии. Давайте добавим сохранение данных запроса в файл, затем перейдем в CRM, и отредактируем контакт.

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

Понимая теперь структуру данных в POST-запросе от Битрикс24 мы можем вернуться к коду примера.

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

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

Далее при помощи входящего вебхука мы выполняем запрос к Битрикс24, для получения всей информации о контакте. Идентификатор измененного контакта мы берем из POST-запроса.

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