Bitrix24 API - разбор демо приложения третьего типа

Вводная

Пользователям CRM Bitrix24 зачастую хочется передавать накапливаемые в этой системе данные на какой-то сторонний ресурс для дальнейшей их обработки. Так, мне, например, понадобилось наладить экспорт закрытых сделок на сайт, который занимается учётом затрат на производство. В данном случае можно поступить двумя способами: во-первых, можно на стороннем сайте сделать кнопку, которая запрашивала бы из битрикса сделки (пока не рассматриваем реализацию); во-вторых, можно заставить битрикс самостоятельно отправлять данные по сделке сразу при её закрытии (по событию). Второй вариант более привлекателен, - всё работает в реальном времени без участия человека (никаких кнопок для передачи данных нажимать не нужно).

Бизнес-процесс

Встал вопрос, как реализовать выгрузку данных из битрикс24 по событию. Первый вариант, который я проверял, это сделать отправку через так называемый "бизнес процесс". На момент написания статьи добраться до бизнес процессов стало довольно сложно: в разделе меню "CRM" пункт "Настройки", на открывшейся странице ссылка "Бизнес-процессы", затем в разделе "Сделка" есть кнопки "Добавить шаблон" и "Список шаблонов".
В редакторе шаблона есть блок "PHP код" из группы "Прочее". Казалось бы вот оно! Но нет. Эта штука не работает. А жаль. Можно было бы вписать в неё что-то типа такого:

if( $curl = curl_init() ) {
    curl_setopt($curl, CURLOPT_URL, 'http://<SomeSite>/integration/index.php');
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $post_headers = array('Content-type: application/x-www-form-urlencoded charset=utf-8',
                         'X_ASCCPE_USERNAME: логин',
                         'X_ASCCPE_PASSWORD: пароль',
                         '');
    curl_setopt($curl, CURLOPT_HEADER, $post_headers);
    curl_setopt($curl, CURLOPT_POST, true);
    $data = array('name' => {=Document:TITLE}, 'date' => {=Document:CLOSEDATE}, 'accounting' => 1, 'amount' => {=Document:OPPORTUNITY}, 'cost' => 0);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
    $out = curl_exec($curl);
    echo $out;
    curl_close($curl);
}

Здесь и далее <SomeSite> означает URL вашего сайта.
И отправлялись бы данные на нужный сайт каждый раз при закрытии сделки. В реальности блок "PHP код" при попытке сохранить выдаёт ошибку "У вас нет прав на изменение PHP кода"

API Bitrix24

Второй вариант организовать выгрузку данных из битрик24 на сторонний сайт - это воспользоваться API Bitrix24. API есть, документация есть:
1) Документция для разработчиков Битрикс24
2) "Разработчик Bitrix Framework" раздел "Маркетплейс Битрикс24"
Вроде всё есть, но вот вникнуть в тему не так-то и просто. В документации нет никаких практических примеров. На форумах люди делятся строго на два лагеря: те кто ничего не понял, как работать с этим API и спрашивают у знатоков (но никто не отвечает); и те, кто постиг это тайное знание и не делится им, а предлагает за деньги выполнить разработку. Я же в данной статье попробую подробно разложить по полочкам создание приложения "третьего типа" - внешние приложения, которые только используют API битрикса, но в его интерфейсе никак не участвуют. Т.е. можно запрашивать, редактировать и добавлять данные битрикса из стороннего сайта или упросить битрикс24 самостоятельно отправлять куда-либо данные при срабатывании определённых событий.
Все эти возможности представлены в демо-приложении, которое можно скачать прямо из документации. Никакого описания, что делает это приложение и как - нет: ни в документации, ни в комментариях к коду. Восполню этот пробел.

Разбор демо-приложения третьего типа

Расположение приложения

В архиве содержится основной файл index.php и ряд вспомогательных файлов. Перед человеком, который первый раз пытается сделать приложение для Битрикс24, сразу возникнет вопрос: где эти файлы нужно расположить. Я пробовал экспериментировать на локальном сайте, но то ли у меня что-то не донастроено, то ли нельзя так сделать на локальном сайте (без внешнего доступа из интернета), - ничего не вышло - авторизация на последнем шаге не срабатывает. Итак, располагаем эти файлы на сайте в интернете. Например, создаём в корне сайта каталог integration и в него извлекаем архив. В результате путь к демо-приложению получится http://<SomeSite>/integration/index.php. Можно работать как с протоколом HTTP, так и с HTTPS. Лучше, конечно, использовать защищённый протокол.

Авторизация

Стороннее для Битрикс24 приложение должно получать (или передавать) данные, которые не должны быть похищены злоумышленниками. Чтобы этого достичь, нужно установить доверие между битриксом и сторонним сайтом. Для этого применяется протокол OAuth 2.0. Суть в том, что каждый запрос будет сопровождаться неким секретным набором символов (access_token). А чтобы злоумышленник не перехватил секретный код, этот код довольно быстро портится и очень строго получается: во время его генерации проверяется, что запрашивающий код сайт известен битриксу и является действительно тем сайтом, за кого себя выдаёт. Чтобы этого достичь, в Битрикс24 нужно создать некий секрет, который должен быть известен только администратору портала Битрикс24, настраивающему интеграцию. Для этого в битриксе создаётся приложение.
Раньше создание приложений было очень затруднено, но с недавних пор сделать это можно прямо в интерфейсе портала Битрикс24: слева в меню в группе "Приложения" нажимаем кнопку "Добавить приложение".

Слева как раз блок "Для личного использования" - нажимаем там "Добавить". Заполняем название, включаем флажок "Приложение использует только API", даём права "CRM", "Пользователи" и "Живая лента", указываем ссылку на своё демо-приложение http://<SomeSite>/integration/index.php

После сохранения сгенерируется нужный нам секрет, состоящий из двух частей: "Код приложения" и "Ключ приложения" (т.е. никакого приложения не создаётся на самом деле, - просто указывается ссылка на него).

Полученные данные нужно занести в настройки демо-приложения (include/config.php). Код приложения вписываем в строку

define('CLIENT_ID', 'local.55fa7d514738b5.63819847');

Ключ приложения в строку

define('CLIENT_SECRET', '9768f9ccc5b198837cab9b7f2f233e1e');

Прописываем свой относительный путь к приложению:

define('PATH', '/integration/index.php');

Прописываем адрес своего сайта (он должен совпадать с тем, что указано в созданном приложении в Битрикс24)

define('REDIRECT_URI', 'http://<SomeSite>' . PATH);

На этом настройки демо-приложения завершены.
Открываем наше приложение (http://<SomeSite>/integration/index.php) в браузере. Должна появиться форма для ввода названия портала Битрикс24 (по форме my.bitris24.ru):

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

На этом настройка и проверка демо-приложения оканчивается

Разбираемся, как это работает

Страница несколько раз передаёт и получает различные данные из Битрикс24.

Всё это можно было бы проделать вручную, вводя длинные URL в браузере (как, например, делает автор статьи "Мой опыт использования Bitrix24 REST API"). Главная цель этих действий получить access_token. Зная этот код, можно взаимодействовать с битриксом через его API. В скрипте демо-приложения index.php с начала файла и до строки 61 как раз и происходит авторизация. Затем в строках 65 - 91 описывается метод обновить истекшую авторизацию. Далее идёт непосредственно функционал демо-страницы, где пользователю показываются несколько ссылок, нажатия которых приводят к выполнению определённых методов API Bitrix24 и, в свою очередь, взаимодействию с вашим порталом Битрикс24.
Все ссылки ведут на ту же страницу, только к URL дописываются параметры GET запроса, который тут же в скрипте обрабатывается в конструкции switch case.
Первая ссылка "Информация о пользователе" выполняет код:

$data = call($_SESSION["query_data"]["domain"], "user.current", array(
    "auth" => $_SESSION["query_data"]["access_token"])
);

Т.е. запрашивает у вашего портала разрешение на выполнение метода API user.current и передаёт access_token, полученный на предыдущем этапе. Это пример получения данных из Битрикс24.
Другая ссылка "Установить обработчик события" призвана привязать к определённому событию в Битрикс24 (в данном случае к добавлению лида) выполнение определённого скрипта на внешнем сайте (в данном случае ссылку на обработчик нужно исправить, чтобы прописать обработчик event.php). Чтобы обработчик с нашими настройками заработал, нужно исправить строку

"HANDLER" => REDIRECT_URI."event.php",

на

"HANDLER" => "http://<SomeSite>/integration/event.php"

В целом обработка клика по данной ссылке (в скрипте index.php) должна выглядеть так:

case 'event.bind': // bind event handler
    $data = call($_SESSION["query_data"]["domain"], "event.bind", array(
        "auth" => $_SESSION["query_data"]["access_token"],
        "EVENT" => "ONCRMLEADADD",
        "HANDLER" => "http://<SomeSite>/integration/event.php"
    ));
break;

После этих исправлений можно нажать ссылку и обработчик привяжется. Т.е. где-то на стороне вашего портала Битрикс24 в "облачном" фоне будет висеть наблюдатель и ждать события - добавление лида. Как только событие произойдёт, выполнится вызов обработчика с вашего сайта (скрипт event.php).
Какие обработчики каких событий уже привязаны к вашему порталу посмотреть в пользовательском интерфейсе нигде нельзя. Но можно добавить к скрипту index.php свою ссылку для обращения к методу API event.get, который отобразит все установленные обработчики. Добавляем ссылку:

<li><a href="<?=PATH?>?test=event.get">Просмотр установленных обработчиков событий</a>

и добавляем в существующий switch обработку, которая запросит метод event.get:

case 'event.get':
    $data = call($_SESSION["query_data"]["domain"], "event.get", array(
        "auth" => $_SESSION["query_data"]["access_token"])
    );
break;

Если потребуется удалить обработку события, то можно к этому демо-приложению добавить ссылку

<li><a href="<?=PATH?>?test=event.unbind">Удаление установленного обработчика события</a>

и обработку (метод event.unbind); только изменить адрес HANDLER на требуемый:

case 'event.unbind':
    $data = call($_SESSION["query_data"]["domain"], "event.unbind", array(
        "auth" => $_SESSION["query_data"]["access_token"],
        'EVENT' => 'ONCRMLEADADD',
        'HANDLER' => REDIRECT_URI . "event.php"
    ));
break;

Для того, чтобы посмотреть, к каким событиям можно подписаться, можно добавить ссылку

<li><a href="<?=PATH?>?test=event.list">Просмотр всех доступных событий</a>

и обработчик (метод events):

case 'event.list':
    $data = call($_SESSION["query_data"]["domain"], "events", array(
        "auth" => $_SESSION["query_data"]["access_token"])
    );
break;

Этих знаний уже достаточно для начала работы с API Bitrix24. В следующей статье я опишу, как сделать выгрузку сделок на внешний сайт при изменении сделки в Битрикс24.
Добавлено 23.10.2016: Вот ссылка на полный код с дополнениями из статьи.

Полезные ссылки

Вопрос выгрузки данных из Битрикс24 периодически возникает на различных ресурсах (например, Тостер). Но материалов по конкретным реализациям крайне мало. Например, есть статья "Использование REST API Bitrix24". На github'е есть некий набор заготовок, но опять же проблема, как и с самим API Bitrix24 - нет описаний, как пользоваться и что есть. Общее представление о работе API Bitrix24 даёт презентация "Маркетплейс Битрикс24".