0  /  40

Приложения Битрикс24

Содержание

Приложения и интеграции с Битрикс24

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

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

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

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

Локальные приложения и вебхуки

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

Локальные приложения

Локальные приложения лучше подходят для тех задач, которые требуют создания пользовательского интерфейса:

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

Локальные приложения поддерживают все возможности REST API и вызывают REST по протоколу авторизации OAuth 2.0, но устанавливаются только на конкретном Битрикс24, без публикации в каталоге решений. Для добавления локального приложения требуется административный доступ.

Быстрый старт локального приложения.

Webhooks

Вебхуки идеально подходят:

  • для организации одноразового импорта-экспорта данных;
  • простых интеграций с внешними и внутренними системами компании (ERP, учет рабочего времени, авто-мониторинг программных и аппаратных средств и т.д.);
  • использования в автоматизации обработки лидов и сделок (триггеры и действия в CRM-роботах);

Использование вебхуков проще для технической реализации, поскольку не требует реализации протокола OAuth 2.0. Каждый пользователь может добавлять вебхуки "для себя" и REST API, вызываемый в рамках таких вебхуков, будет ограничиваться правами конкретного пользователя-владельца.

Быстрый старт с использованием веб-хуков.



Локальные приложения. Быстрый старт

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

Существует два вида локальных приложений Битрикс24:

  1. Статичные приложения на основе HTML/JS. Фактически, на основе этих технологий вы можете реализовывать приложения-одностраничники, обращаясь к REST API Битрикс24 при помощи SDK на JS. Приложение будет представлено в интерфейсе Битрикс24 в виде отдельной страницы (со ссылкой из левого меню). Статичные приложения не могут получать события Битрикс24.
  2. Серверные приложения на любых подходящих языках программирования (PHP, Python, и другие). Они могут обращаться к REST API используя протокол OAuth 2.0, а также получать события от Битрикс24 в свои обработчики. Серверные приложения могут быть представлены в интерфейсе Битрикс24 в виде отдельной страницы, а также в виде встраиваемых popup-диалогов в доступных для встраивания объектах Битрикс24. Есть вариант, когда приложение никак не проявляется себя в интерфейсе Битрикс24, но использует REST API для обмена данными или какой-то автоматической обработки данных Битрикс24.

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

Статичное приложение. Пример представляет собой готовое приложение, обращающееся к REST API и показывающее ФИО текущего пользователя.

Серверное приложение с базовым интерфейсом внутри Битрикс24. Пример приложения использует упрощенный вариант использования OAuth 2.0, выводится в виде дополнительной страницы, на которой показывает ФИО текущего пользователя.

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

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


Статичное локальное приложение

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

Скачать архив:

Для установки локального приложения нужно перейти по цепочке: Приложения 1 - Добавить приложение 2 - Добавить приложение 3:

Нажмите на рисунок, чтобы увеличить

В открывшейся форме заполнить базовые поля и указать необходимые для приложения права (для нашего примера нужны права на управление пользователями), и загрузить архив с приложением:

Нажмите на рисунок, чтобы увеличить

После сохранения новое приложение будет показано в списке локальных приложений в вашем Битрикс24:

Нажмите на рисунок, чтобы увеличить

Найдите приложение "ФИО" в левом меню или в меню "Ещё" в разделе Приложения и запустите. Запущенное приложение выведет ФИО текущего пользователя, получая его по REST API через JS-библиотеку. Поскольку статичное локальное приложение работает к интерфейсе Битрикс24, то JS SDK автоматически получает и использует авторизацию текущего пользователя, который открыл приложение, и действует исключительно только в рамках прав этого пользователя.


Серверное локальное приложение с интерфейсом в Битрикс24

Пример состоит из одного PHP-файла, который вы должны разместить на своем веб-сервере до установки в Битрикс24. Приложение использует упрощенный вариант использования OAuth 2.0, выводится в виде дополнительной страницы, на которой показывает ФИО текущего пользователя.

Скачать архив:

Для установки локального приложения нужно перейти по цепочке: Приложения 1 - Добавить приложение 2 - Добавить приложение 3:

Нажмите на рисунок, чтобы увеличить

В открывшейся форме заполнить базовые поля и указать необходимые для приложения права (для нашего примера нужны права на управление пользователями), указав [dw]URL приложения[/dw][di][/di] (это означает, что ваше приложение уже должно быть физически доступно по URL по протоколу HTTPS до того, как вы станете добавлять его в ваш Битрикс24)

Нажмите на рисунок, чтобы увеличить

После сохранения новое приложение будет показано в списке локальных приложений в вашем Битрикс24:

Нажмите на рисунок, чтобы увеличить

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


Серверное локальное приложение без интерфейса в Битрикс24

Установка

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

Скачать архив:

Для установки локального приложения нужно перейти по цепочке: Приложения 1 - Добавить приложение 2 - Добавить приложение 3:

Нажмите на рисунок, чтобы увеличить

В открывшейся форме заполнить базовые поля и указать необходимые для приложения права (для нашего примера нужны права на управление пользователями), указав [dw]URL приложения[/dw][di][/di] (это означает, что ваше приложение уже должно быть физически доступно по URL по протоколу HTTPS до того, как вы станете добавлять его в ваш Битрикс24)

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

Нажмите на рисунок, чтобы увеличить

После сохранения вы останетесь в форме добавления приложения, но Битрикс24 вам сразу покажет ключи авторизации для протокола OAuth 2.0, которые вам потребуются внутри кода приложения:

Поскольку приложение без интерфейса работает "вне" Битрикс24, то оно должно реализовывать полный протокол авторизации OAuth 2.0. Откройте код примера и замените константы с кодом приложения 1 и секретным ключом 2 полученными при сохранении формы. Не забудьте также указать точный URL, по которому вы будете размещать пример:

Нажмите на рисунок, чтобы увеличить

Загрузите измененный пример на свой сервер.

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

Нажмите на рисунок, чтобы увеличить

Использование

Откройте пример в браузере по вашему URL:

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

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


Серверное локальное приложение для чат-бота в Битрикс24

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

Скачать архив:

Чат-бот для мессенджера Битрикс24 не является отдельным "типом" приложений. Фактически, чат-бот может быть частью любого серверного приложения, которое просто будет реализовывать логику чат-бота (или даже нескольких сразу), используя соответствующие возможности REST API. При этом, REST для чат-бота в некоторых случаях позволяет обойтись без разработки полной схемы авторизации по протоколу OAuth 2.0, как того требует общий случай серверных приложений без пользовательского интерфейса внутри Битрикс24.

Предлагаемый пример как раз реализует простой кейс, когда чат-бот только отвечает на полученные от пользователей сообщения и поэтому не нуждается в самостоятельном "возобновлении" авторизации по OAuth 2.0. Посмотрев код примера, вы увидите, что все необходимые для работы REST данные, приложение получает в массиве $_REQUEST в нужных для чатбота обработчиках событий.

Для установки локального приложения нужно перейти по цепочке: Приложения 1 - Добавить приложение 2 - Добавить приложение 3:

Нажмите на рисунок, чтобы увеличить

В открывшейся форме заполнить базовые поля и указать необходимые для приложения права (для нашего примера требуются права на создание и управление чатботами), указав [dw]URL приложения[/dw][di][/di] (это означает, что ваше приложение уже должно быть физически доступно по URL по протоколу HTTPS до того, как вы станете добавлять его в ваш Битрикс24)

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

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

Нажмите на рисунок, чтобы увеличить

Обратите также внимание на то, что мы [dw]заполнили поле[/dw][di][/di] Укажите ссылку-callback для события установки. Этот URL вызывается только один раз при сохранении формы локального приложения. Именно этот URL служит обработчиком события ONAPPINSTALL, в котором мы и добавляем чатбота в наш Битрикс24. Если вы захотите добавить чатбот заново, вам нужно будет удалить и заново добавить локальное приложение.

После сохранения приложения с чатботом Битрикс24 сразу сообщит о появлении бота в общем чате:

После сохранения новое приложение будет показано в списке локальных приложений в вашем Битрикс24:

Нажмите на рисунок, чтобы увеличить

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


Веб-хуки. Быстрый старт

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

Это делает веб-хуки исключительно простым и удобным механизмом для работы с REST, но при этом надо понимать, что эта простота имеет и свои недостатки:

  1. Для формирования вебхука требуется участие пользователя (вы не сможете генерировать вебхуки автоматически);
  2. Поскольку срока действия у вебхука нет, то любая "утечка" URL вебхука чревата получением доступа к вашему Битрикс24 в рамках прав конкретного вебхука. Именно поэтому данный механизм годится для "внутренних" интеграций, но не подходит для тиражных вариантов использования;
  3. Ряд методов REST недоступен для работы через вебхуки, поскольку их логика требует "контекста" приложения, а никакого приложения в терминах Битрикс24 для вебхуков нет (в частности, методы встраивания приложений в интерфейс Битрикс24, события телефонии, часть событий чат-ботов и т.д.).

Но несмотря на эти ограничения для подавляющего большинства задач интеграции в рамках конкретного проекта вебхуки представляются идеальным вариантом работы с REST API.

Создание Входящего вебхука

  1. В выпадающем меню Добавить вебхук выберите Входящий вебхук.
  2. В открывшейся форме заполните поля:
    • Название и Описание - произвольные данные.
    • Права доступа - укажите, к каким модулям вебхук должен иметь доступ. Доступен множественный выбор.
  3. После сохранения появится код для авторизации вебхука:

    Внимание! Данный код является конфиденциальной информацией. Его необходимо держать в секрете.
  4. Вместе с кодом будет представлен образец URL, который нужно использовать при отправке данных из сторонней системы в Битрикс24:
    https://********.bitrix24.ru/rest/1/83te1pjdphsa9u15/profile/
    где:
    • ******** - имя вашего портала;
    • /rest/ - указание системе на то, что данный адрес относится в вебхукам;
    • /1/ - идентификатор пользователя, создавшего вебхук. Под правами этого пользователя будет работать этот вебхук.
    • /83te1pjdphsa9u15/ - секретный код;
    • /profile/ - метод REST, который вы хотите выполнить, обращаясь к вебхуку. Разработчик должен сам подобрать метод из REST API в зависимости от целей создания вебхука.
  5. Обратиться из сторонней системы по указанному адресу на Битрикс24.

    Рассмотрим пример такого обращения с задачей создать лид из формы. Надо сформировать URL в переменной $queryUrl, сформировать параметры для создания лида в переменной $queryData и после подготовительных шагов как раз и обратиться к Битрикс24 при помощи функции curl_exec. Полученный в виде JSON результат обработан:

    Пример кода обращения к Битрикс24
    <?
    /**
     * Write data to log file.
     *
     * @param mixed $data
     * @param string $title
     *
     * @return bool
     */
    function writeToLog($data, $title = '') {
     $log = "\n------------------------\n";
     $log .= date("Y.m.d G:i:s") . "\n";
     $log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
     $log .= print_r($data, 1);
     $log .= "\n------------------------\n";
     file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
     return true;
    }
    
    $defaults = array('first_name' => '', 'last_name' => '', 'phone' => '', 'email' => '');
    
    if (array_key_exists('saved', $_REQUEST)) {
     $defaults = $_REQUEST;
     writeToLog($_REQUEST, 'webform');
    
     $queryUrl = 'https://restapi.bitrix24.ru/rest/1/31uhq2q855fk1foj/crm.lead.add.json';
     $queryData = http_build_query(array(
     'fields' => array(
     "TITLE" => $_REQUEST['first_name'].' '.$_REQUEST['last_name'],
     "NAME" => $_REQUEST['first_name'],
     "LAST_NAME" => $_REQUEST['last_name'],
     "STATUS_ID" => "NEW",
     "OPENED" => "Y",
     "ASSIGNED_BY_ID" => 1,
     "PHONE" => array(array("VALUE" => $_REQUEST['phone'], "VALUE_TYPE" => "WORK" )),
     "EMAIL" => array(array("VALUE" => $_REQUEST['email'], "VALUE_TYPE" => "WORK" )),
     ),
     'params' => array("REGISTER_SONET_EVENT" => "Y")
     ));
    
     $curl = curl_init();
     curl_setopt_array($curl, array(
     CURLOPT_SSL_VERIFYPEER => 0,
     CURLOPT_POST => 1,
     CURLOPT_HEADER => 0,
     CURLOPT_RETURNTRANSFER => 1,
     CURLOPT_URL => $queryUrl,
     CURLOPT_POSTFIELDS => $queryData,
     ));
    
     $result = curl_exec($curl);
     curl_close($curl);
    
     $result = json_decode($result, 1);
     writeToLog($result, 'webform result');
    
     if (array_key_exists('error', $result)) echo "Ошибка при сохранении лида: ".$result['error_description']."
    "; } ?> <fo rm method="post" action=""> Имя: <input type="text" name="first_name" size="15" value="<?=$defaults['first_name']?>"><br/> Фамилия: <input type="text" name="last_name" size="15" value="<?=$defaults['last_name']?>"><br/> Телефон: <input type="phone" name="phone" value="<?=$defaults['phone']?>"<
    E-mail: <input type="email" name="email" value="<?=$defaults['email']?>"><br/> <input type="hidden" name="saved" value="yes"> <input type="submit" value="Отправить"> </form>

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

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

  1. В выпадающем меню Добавить вебхук выберите Исходящий вебхук.
  2. В открывшейся форме заполните поля:
    • Адрес обработчика - страница на стороннем ресурсе, куда будет обращаться вебхук.
    • Название и Описание - произвольные данные.
    • Тип события - нужно указать событие, на которое будет инициализироваться вебхук.
  3. После сохранения вебхука будет выведен Код авторизации в виде строки из случайных знаков. Этот код позволит внутри обработчика проверить, действительно ли обработчик вызван вашим Битрикс24.
  4. На странице обработчика размещаем код:

    Пример кода обработчика для события ONCRMDEALUPDATE

    <?
    
    print_r($_REQUEST);
    writeToLog($_REQUEST, 'incoming');
    
    /**
     * Write data to log file.
     *
     * @param mixed $data
     * @param string $title
     *
     * @return bool
     */
    function writeToLog($data, $title = '') {
     $log = "\n------------------------\n";
     $log .= date("Y.m.d G:i:s") . "\n";
     $log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
     $log .= print_r($data, 1);
     $log .= "\n------------------------\n";
     file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
     return true;
    } 

    Для проверки откройте любую сделку на редактирование и сохраните изменения, в логе отобразится примерно такая история:

    2017.01.17 12:58:29
    incoming
    Array
    (
        [event] => ONCRMDEALUPDATE
        [data] => Array
            (
                [FIELDS] => Array
                    (
                        [ID] => 662
                    )
    
            )
    
        [ts] => ххх
        [auth] => Array
            (
                [domain] => ххх.bitrix24.ru
                [client_endpoint] => https://ххх.bitrix24.ru/rest/
                [server_endpoint] => https://oauth.bitrix.info/rest/
                [member_id] => ххх
                [application_token] => ххх
            )
    
    )

Смотрите подробный мастер-класс о вебхуках:

Рекомендуем также посмотреть код, использованный в примерах.


Публичные тиражные решения для Битрикс24

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

Необходимость публикации в каталоге накладывает на приложения ряд дополнительных технических и организационных требований:

  1. Необходимо стать технологическим партнером 1С-Битрикс или быть участником стандартной партнерской программы;
  2. Приложение, которое вы собираетесь опубликовать, должно будет пройти модерацию на соответствие требованиям к функционалу и оформлению;
  3. У приложения всегда есть версии, каждая из которых может запрашивать свои права на доступ к модулям Битрикс24. В связи с этим, модерация запрашивается для каждой новой версии приложения, начиная с 1-й;
  4. Автор решения несет ответственность за сохранность и конфиденциальность персональной информации, к которой получает доступ его приложение;

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

Чтобы продолжить рассказывать о разработке и публикации приложений считаем, что вы уже обладаете доступом в партнерский кабинет 1С-Битрикс, а потому ответим последовательно на основные вопросы:

Как стать технологическим партнером

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

Обратите внимание на поле Код партнера - это префикс, который будет подставляться в дальнейшем в символьный код, идентифицирующий ваши решения в нашем каталоге. Если взять в качестве примера решение по интеграции со Stripe (https://www.bitrix24.ru/apps/?app=integrations24ru.stripe), то integrations24ru является как раз этим кодом партнера (разработчика решения), а код stripe является кодом конкретного решения, который вы укажите в дальнейшем при заполнении формы регистрации решения.

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

Разработка публичных решений. Быстрый старт

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

Статичное приложение. Пример - это готовое приложение, обращающееся к REST API и показывающее ФИО текущего пользователя. Как создать и установить такое приложение в своем Битрикс24?

Серверное приложение с базовым интерфейсом внутри Битрикс24. Пример приложения использует упрощенный вариант использования OAuth 2.0, выводится в виде дополнительной страницы, на которой показывает ФИО текущего пользователя.

Серверное приложение встраиваемое в стандартный интерфейс Битрикс24. Пример приложения состоит из двух PHP-файлов, которые вы должны разместить на своем веб-сервере. Приложение умеет добавлять пункт в контекстное меню списка контактов и списка компаний, использует упрощенный вариант использования OAuth 2.0, выводится в виде слайдера, в котором показывает ФИО текущего пользователя.

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


Статичное тиражное приложение

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

Скачать архив:

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Приложения24 необходимо в партнерском кабинете перейти [dw]по цепочке[/dw][di][/di] Кабинет партнера > Приложения24 для Битрикс24 > Добавить приложение. В открывшейся форме необходимо заполнить 7 обязательных полей:

Нажмите на рисунок, чтобы увеличить

Описание обязательных полей (Нажмите на плюсик)

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

Версии приложения

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

Добавим первую версию приложения. Перейдите [dw]на закладку[/dw][di][/di] Версии и нажмите Добавить новую версию. В открывшейся форме заполните базовые поля, укажите необходимые для приложения права (для нашего примера нужны права на управление пользователями) и загрузите архив с приложением:

Нажмите на рисунок, чтобы увеличить

После сохранения вы увидите сообщение Решение успешно изменено, а нажав кнопку Версии, увидите [dw]версию в списке[/dw][di][/di].

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

Откройте добавленную версию для редактирования. Нажмите на ссылку [dw]Установить на свой портал Битрикс24[/dw][di][/di] и в открывшемся диалоге укажите адрес любого Битрикс24, доступного вам в роли администратора (это может быть как облачный, так и коробочный Битрикс24).

Процедура установки на портале полностью воспроизводит последовательность действий пользователей, устанавливающих уже опубликованные решения:

После установки приложения Битрикс24 сразу откроет его интерфейс. Вы также сможете переходить в приложение из соответствующего пункта левого меню или меню Еще в разделе Приложения:

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


Серверное приложение с базовым интерфейсом внутри Битрикс24

Архив с примером содержит один файл и представляет собой готовое приложение, обращающееся к REST API и показывающее ФИО текущего пользователя. Другой пример такого приложения описан в уроке REST для sms.

Скачать архив:

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Приложения24 необходимо в партнерском кабинете перейти [dw]по цепочке[/dw][di][/di] Кабинет партнера > Приложения24 для Битрикс24 > Добавить приложение. В открывшейся форме необходимо заполнить 12 обязательных полей:

Нажмите на рисунок, чтобы увеличить

Описание обязательных полей (Нажмите на плюсик)

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

Версии приложения

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

Добавим первую версию приложения. Перейдите [dw]на закладку[/dw][di][/di] Версии и нажмите Добавить новую версию. В открывшейся форме заполните базовые поля, укажите необходимые для приложения права (для нашего примера нужны права на управление пользователями), а также URL текущего примера, размещенного на вашем сервере:

Нажмите на рисунок, чтобы увеличить

После сохранения версии, вы останетесь на странице с описанием версии, но увидите появившуюся ссылку [dw]Установить на свой портал Битрикс24[/dw][di][/di]. Ссылка позволяет устанавливать еще неопубликованное приложение на любой Битрикс24, к которому у вас есть административный доступ.

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

После установки приложения Битрикс24 сразу откроет его интерфейс. Вы также сможете переходить в приложение из соответствующего пункта левого меню или меню Еще в разделе Приложения:

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


REST для SMS

Универсальный механизм отправки сообщений

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

Авторам интеграций с SMS-провайдерами рекомендуется перевести свои приложения на новый REST, чтобы у пользователей не было проблем с установкой на бесплатном тарифе. И, несмотря на прозрачность вызовов существующих провайдеров для бизнес-процессов и роботов CRM, лучше работать с методами REST для службы сообщений. Тем более, что только эти методы позволят не только отправлять SMS, но и сообщать Битрикс24 о статусе отправленных сообщений. Этот статус пользователи видят прямо в карточке CRM (а в будущем увидят и в отчетах инструментов CRM-маркетинга).

Рассмотрим практический пример того, как можно быстро сделать интеграцию с SMS-провайдером.

Скачать архив примера:


Для начала

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

Обратите внимание на поле Код партнера - это префикс, который будет подставляться в дальнейшем в символьный код, идентифицирующий ваши решения в нашем каталоге. Если взять в качестве примера решение по интеграции со Stripe (https://www.bitrix24.ru/apps/?app=integrations24ru.stripe), то integrations24ru является как раз этим кодом партнера (разработчика решения), а код stripe является кодом конкретного решения, который вы укажите в дальнейшем при заполнении формы регистрации решения.

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

После заполнения анкеты вы сразу получите доступ в партнерский кабинет [link=]https://partners.1c-bitrix.ru/personal/[/link]. Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Приложения24 необходимо в партнерском кабинете перейти [dw]по цепочке[/dw][di][/di] Кабинет партнера > Приложения24 для Битрикс24 > Добавить приложение. В открывшейся форме необходимо заполнить 5 обязательных полей.

Описание обязательных полей (Нажмите на плюсик)

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

Версии приложения

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

Добавим первую версию приложения. Перейдите [dw]на закладку[/dw][di][/di] Версии и нажмите Добавить новую версию. В открывшейся форме заполните базовые поля, укажите необходимые для приложения права (для нашего примера нужны права на управление пользователями), а также URL текущего примера, размещенного на вашем сервере:

Нажмите на рисунок, чтобы увеличить

Про URL приложения

В поле Права укажите, что приложению нужен доступ к модулю [dw]Сервис сообщений[/dw][di][/di]. Битрикс24 в этом случае будет сам вызывать наш провайдер из нужных точек в интерфейсе: из бизнес-процессов, из роботов CRM, из карточки CRM и так далее.

Остается только указать номер версии и указать что-нибудь в описании версии. (Когда дело дойдет до подачи на модерацию, здесь нужно будет вводить реальный осмысленный текст с описанием функционала версии). Галочку Отправить на модерацию сейчас не включайте. Сохраните версию.


Общая логика приложения

Приложение регистрирует в конкретном Битрикс24 некий обработчик. Когда пользователь (или автоматический процесс) на стороне Битрикс24 хочет отправить SMS, он дергает этот обработчик и передает в него текст и номер телефона получателя. Обработчик (зная параметры вызова API SMS-оператора) отправляет SMS. Вот такая простая схема:

В нашем примере, скрипт install.php запросит у пользователя параметры для подключения API SMS-оператора и сохраняет их на своей стороне в привязке к конкретному Битрикс24. В таблице БД, например. Этот же скрипт регистрирует так называемый "провайдер сообщений" в Битрикс24, обращаясь к соответствующему методу REST. Фактически, это и будет регистрацией обработчика, который реализуется в примере в файле handler.php по адресу https://mydomain.ru/sms/handler.php. Если регистрация прошла успешно, install.php должен завершить установку.

В дальнейшем приложение ожидает, когда Битрикс24 обратиться к нему:

Обращение произойдет, если пользователь, допустим, решит отправить SMS из карточки CRM. В этом случае, handler.php получит целую кучу данных в массиве $_REQUEST:

requestArray
(
    [module_id] => crm
    [bindings] => Array
        (
            [0] => Array
                (
                    [OWNER_TYPE_ID] => 1
                    [OWNER_ID] => 5783
                )

        )

    [properties] => Array
        (
            [phone_number] => +9172012345
            [message_text] => тест
        )

    [type] => SMS
    [code] => fastsms
    [message_id] => e35864edce3eaad987d32f8955c1177b
    [message_to] => +9172012345
    [message_body] => тест
    [ts] => 1513177809
    [auth] => Array
        (
            [access_token] => x4o81wfl4g57qur2u8sjrlcha76zn0tj
            [expires_in] => 3600
            [scope] => messageservice
            [domain] => restapi.bitrix24.ru
            [server_endpoint] => https://oauth.bitrix.info/rest/
            [status] => F
            [client_endpoint] => https://restapi.bitrix24.ru/rest/
            [member_id] => da45a03b265edd8787f8a258d793cc5d
            [user_id] => 1
            [application_token] => 127acc1c34feccc4da8fbf5020856f12
        )

)

Нас интересует:

  • адресат message_to,
  • текст сообщения message_body,
  • внутренний идентификатор сообщения message_id, который потребуется для того, чтобы в дальнейшем отдельно сообщать в Битрикс24 о статусе доставки,
  • параметры авторизации в массиве auth для работы с REST Битрикс24.

Обработчик, получив данные о сообщении, должен:

  1. обратиться к API SMS провайдера, чтобы отправить сообщение,
  2. запомнить id-сообщения и привязку к конкретному Битрикс24 где-то у себя в некой очереди.

Можно и не запоминать, но тогда приложение не сможет во всей полноте реализовать хорошие пользовательские сценарии. Так как статус доставки SMS-сообщения становится известным только через некоторое время (иногда это могут быть часы), мы не сможем прямо из handler.php тут же сообщить в Битрикс24 о результате доставки. Приложению придется делать это отдельно, и для этого в архиве примера есть файл statuses.php. Подразумевается, что какой-то менеджер заданий обращается к этому файлу с некой периодичностью и этот скрипт «смотрит» на очередь отправленных SMS и по каждому из них пытается узнать статус доставки, обращаясь к API SMS-провайдера:

О результатах он сообщает в Битрикс24, и удаляет из очереди обработанные сообщения.


Установка приложения без публикации

Разработкой и отладкой приложения можно заниматься до публикации приложения в каталоге Приложения24. Откройте сохраненную версию приложения, и вы увидите там [dw]специальную ссылку[/dw][di][/di]. По клику на ссылке укажите адрес любого своего Битрикс24 в котором у вас есть административные права, и [dw]установите приложение[/dw][di][/di].

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

Нажмите на рисунок, чтобы увеличить

Нажмите “Сохранить”, приложение будет считаться установленным (о техническом завершении - ниже), и Битрикс24 автоматически откроет уже основной интерфейс приложения app.php. В архиве примера этот интерфейс не сильно отличается от интерфейса установки и должен «подхватывать» сохраненные параметры авторизации SMS-провайдера. Но, поскольку это просто «заготовка» для приложения, а не работающая интеграция с конкретным провайдером, то мы увидим просто форму для ввода ключа.


Волшебный код

Начнем с install.php. Когда Битрикс24 показывает во фрейме скрипт приложения (это касается как скрипта установки, так и основного скрипта приложения), то он передает в массив $_REQUEST все необходимые для OAuth 2.0 параметры авторизации. Следовательно, мы их можем схватить и сохранить на стороне приложения для дальнейшего использования. Именно это и происходит в коде при формировании hidden-полей:

<fo rm id="sms-settings">
    <input type="hidden" name="save" value="Y">
    <input type="hidden" name="access_token" value="<?=$_REQUEST['AUTH_ID'];?>">
    <input type="hidden" name="refresh_token" value="<?=$_REQUEST['REFRESH_ID'];?>">
    <input type="hidden" name="domain" value="<?=$_REQUEST['DOMAIN'];?>">
    <input type="hidden" name="member_id" value="<?=$_REQUEST['member_id'];?>">
    <div class="form-group">
        <label for="sms_token">Укажите API-ключ для интеграции с FastSMS</label>
        <input type="text" class="form-control" name="sms_token" id="sms_token" placeholder="FastSMS API token">
    </div>
    <button type="submit" class="btn btn-primary btn-lg btn-save">Сохранить</button>
</form>

Далее, мы делаем обработчик onsubmit, который позволит перехватить нажатие на кнопку "Сохранить".

$('#sms-settings').submit(function(e){

    e.preventDefault();
    // 1. сохраняем данные авторизации на стороне приложения, чтобы в
    // дальнейшем использовать их для отправки смс


    // 2. прописываем обработчик для провайдера
    var params = {
        CODE: 'fastsms',
        TYPE: 'SMS',
        HANDLER: 'https://mydomain.ru/sms/handler.php',
        NAME: 'Провайдер FastSMS.ru',
        DESCRIPTION: 'Провайдер FastSMS.ru'
    };

    BX24.callMethod(
        'messageservice.sender.add',
        params,
        function(result)
        {
            if(result.error())
                alert("Error: " + result.error());
            else {
                // Обработчик для провайдера прописан успешно

                // 3. заканчиваем процедуру установки на стороне Битрикс24
                BX24.installFinish();
            }
        }
    );
});

В этом обработчике можно прописать свой механизм сохранения нужных параметров. А далеезарегистрируйте тот самый обработчик, обращаясь для этого к методу messageservice.sender.add. Если регистрация прошла успешно, мы вызываем метод installFinish, который сообщает Битрикс24 об успешном завершении установки.

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

В app.php все то же самое, та же форма настроек, та же обработка события onsumbit, в которой вам придется писать свой код сохранения настроек и параметров авторизации. Но тут уже нет никакого installFinish, потому что приложение уже установлено:

$('#sms-settings').submit(function(e){

    e.preventDefault();
    // сохраняем данные авторизации на стороне приложения, чтобы в
    // дальнейшем использовать их для отправки смс


});

Код в handler.php. В примере просто сохраняется то, что нам передает Битрикс24 в лог:

writeToLog($_REQUEST, 'request');
print_r($_REQUEST); 

Но вы можете здесь обращаться к API провайдера SMS, инициируя отправку SMS теми средствами, которые вам предоставит оператор. Пример содержимого массива $_REQUEST есть выше.

Самое сложое находится в файле statuses.php. Подразумевается, что этот файл будет вызываться с некой периодичностью и он должен уметь обращаться к некой очереди, которую вы должны сделать самостоятельно. И получая из этой очереди информацию об отправленных SMS-сообщениях, он должен дергать API SMS-провайдера, получать от него статус доставки и передавать его обратно в Битрикс24. Для этого придется в очереди запоминать как ID-сообщения, который присылает Битрикс24, так и соответствующий ему ID-сообщения на стороне SMS-оператора. Посмотрим на код:

include ('rest.php');

// скрипт, который работает с заданной периодичностью, проверяет статусы отправленных
// сообщений и передает эту информацию в Битрикс24

// 1. логика обработки одного сообщения из очереди

// откуда из базы получаем идентификатор оотправленного сообщения - это id, который
// нам передал Битрикс24 в обработчик handler.php
$bx24_message_id = 'e35864edce3eaad987d32f8955c1177b';

// находим запись о соответствующем Битрикс24 в сохраненных данных
// для аутентификации по OAuth 2.0, которые мы сохраняли в install.php или app.php
$bx24_domain = 'restapi.bitrix24.ru';
$bx24_access_token = 'x4o81wfl4g57qur2u8sjrlcha76zn0tj';
$bx24_refresh_token = 'g06ete91nmfa14ew5s2gt432l4in6q6h';

// берем через API провайдера информацию о статусе сообщения и выбираем соответствующий
// ему статус в Битрикс24: delivered, undelivered, failed
$status = 'delivered';

// 2. сообщаем Битрикс24 о статусе сообщения
$result = restCommand ('messageservice.message.status.update',
   array(
      'CODE' => 'fastsms',
      'message_id' => $bx24_message_id,
      'status' => $status
   ),
   array(
      'access_token' => $bx24_access_token,
      'refresh_token' => $bx24_refresh_token,
      'domain' => $bx24_domain
   ),
   true
);

echo "<pre>"; print_r($result); echo "</pre>";

if (isset($result['error'])) {
   // что-то пошло не так, анализируем ошибку и реагируем на нее
}

Представим, что на каждом шаге цикла обработки очереди мы получили из очереди $bx24_message_id, потом вытащили оттуда же название домена Битрикс24 $bx24_domain и токены $bx24_access_token и $bx24_refresh_token. Домен и access_token нам нужны, чтобы обратиться к REST Битрикс24. Это простой HTTP-запрос, в котором указывается домен Битрикс, название нужного метода (в нашем случае это метод messageservice.message.status.update для обновления статуса доставки), параметры метода и токен авторизации access_token.

А вот с токеном авторизации могут возникнуть сложности. Дело в том, что access_token живет только 60 минут. Поскольку SMS-сообщения нам могут прийти в любой момент, в том числе и раз в неделю, то может оказаться, что сохраненный нами access_token уже устарел.

Если быть точным, то в обработчик передается совершенно новый access_token пользователя, который отправляет SMS из интерфейса Битрикс24. Но если говорить про очередь обработки статуса сообщения, то он все равно может успеть перестать быть валидным к моменту, как мы до соответствующего сообщения доберемся. Поэтому на стороне приложения хранится refresh_token – он актуален целый месяц, и он позволяет в любой момент в течение этого периода запрашивать новый access_token без участия пользователя. Заодно при этом обновляя и сам refresh_token. Напишите скрипт, который будет ежедневно пробегаться по сохраненным refresh_token, брать те из них, которые получены 29 дней назад, и запрашивать для них обновление вместе с access_token.

Как можно обращаться к REST, одновременно обновляя токены при необходимости? Используйте этот же механизм просто для обновления refresh_token. У нас есть файл rest.php. Начинается он с двух констант: CLIENT_ID и CLIENT_SECRET. Значения для [dw]этих констант[/dw][di]Такая пара ключей действует на всех Битрикс24, на которых потом будет устанавливаться ваше приложение.[/di] вам нужно взять из карточки приложения:

Используйте функцию restCommand. Она получает название нужного метода REST, параметры для этого метода, массив с данными аутентификации (токены авторизации и домен Битрикс24), а также ключ $authRefresh.

Дальше формируется http-запрос:

$queryUrl = "https://".$auth["domain"]."/rest/".$method;
$queryData = http_build_query(array_merge($params, array("auth" => $auth["access_token"])));

и обращаемся к нему при помощи функций по работе с curl:

$result = curl_exec($curl);

Если наш access_token в этот момент уже невалидный, то в этом случае обращение к REST вернет нам ошибку. Ошибка обрабатывается и если параметр authRefresh задан в true (в архиве примера он именно такой), то тут же прозрачно обновляются токены, обращаясь к функции restAuth. Эта функция тоже обращается к REST, но не просто REST Битрикс24, а к методам непосредственно сервера аутентификации OAuth 2.0.

$queryUrl = 'https://oauth.bitrix.info/oauth/token/';
$queryData = http_build_query($queryParams = array(
   'grant_type' => 'refresh_token',
   'client_id' => CLIENT_ID,
   'client_secret' => CLIENT_SECRET,
   'refresh_token' => $auth['refresh_token']
));

При этом сервер использует те же самые константы CLIENT_ID и CLIENT_SECRET. Если все прошло успешно, то нужно сохранить на стороне приложения новые токены, а затем уже, с новым актуальным access_token, снова вызвать messageservice.message.status.update. Для сохранения токенов в примере сделана заготовка в виде вызова некой функции saveParams($auth).

Используйте стандартную заготовку в виде архива примера, адаптируйте к реальному оператору SMS и публикуйте решения в каталоге Приложения24.


Серверное публичное приложение, встраиваемое в интерфейс Битрикс24

Архив с примером содержит содержит два файла и представляет собой готовое приложение, обращающееся к REST API, встраивающее всплывающие диалоги в списки контактов и компаний CRM, и выводящее данные объекта CRM, выбранного пользователем.

Скачать архив:

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Приложения24 необходимо в партнерском кабинете перейти [dw]по цепочке[/dw][di][/di] Кабинет партнера > Приложения24 для Битрикс24 > Добавить приложение. В открывшейся форме необходимо заполнить 11 обязательных полей:

Нажмите на рисунок, чтобы увеличить

Описание обязательных полей (Нажмите на плюсик)

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

Версии приложения

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

Добавим первую версию приложения. Перейдите [dw]на закладку[/dw][di][/di] Версии и нажмите Добавить новую версию. В открывшейся форме заполните базовые поля, укажите необходимые для приложения права (для нашего примера нужны права на CRM и "Встраивание приложений"), URL текущего примера (файл embedded.php) и URL страницы установки приложения (файл install.php), которые должны быть размещены на вашем сервере:

Нажмите на рисунок, чтобы увеличить

После сохранения версии, вы останетесь на странице с описанием версии, но увидите появившуюся ссылку [dw]Установить на свой портал Битрикс24[/dw][di][/di]. Ссылка позволяет устанавливать еще неопубликованное приложение на любой Битрикс24, к которому у вас есть административный доступ.

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

После установки приложения Битрикс24 выдаст сообщение "Приложение не найдено". Это нормальная ситуация, поскольку у нашего примера включена опция "Использовать только API" и оно ещё не опубликовано в публичном каталоге. Когда ваше приложение будет доступно в каталоге Приложения24, то Битрикс24 после установки будет оставлять пользователя на странице с описанием приложения.

Перейдите в список контактов. В контекстном меню любого контакта в подменю "Приложения" теперь доступен пункт "Public embedded form":

Нажмите на рисунок, чтобы увеличить

при нажатии на который откроется слайдер с приложением:

Нажмите на рисунок, чтобы увеличить

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


Серверное приложение без интерфейса в Битрикс24

Создание записи приложения в Маркетплейсе

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

Скачать архив:

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Приложения24 необходимо в партнерском кабинете перейти [dw]по цепочке[/dw][di][/di] Кабинет партнера > Приложения24 для Битрикс24 > Добавить приложение. В открывшейся форме необходимо заполнить 5 обязательных полей:

Нажмите на рисунок, чтобы увеличить

Описание обязательных полей (Нажмите на плюсик)

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

Версии приложения

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

Добавим первую версию приложения. Перейдите [dw]на закладку[/dw][di][/di] Версии и нажмите Добавить новую версию. В открывшейся форме заполните базовые поля, укажите необходимые для приложения права (для нашего примера нужны права на управление пользователями), а также URL текущего примера, размещенного на вашем сервере:

Нажмите на рисунок, чтобы увеличить

После сохранения версии, вы останетесь на странице с описанием версии, но увидите появившуюся ссылку [dw]Установить на свой портал Битрикс24[/dw][di][/di]. Ссылка позволяет устанавливать еще неопубликованное приложение на любой Битрикс24, к которому у вас есть административный доступ.

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

После установки приложения Битрикс24 выдаст сообщение "Приложение не найдено". Это нормальная ситуация, поскольку у нашего примера включена опция Использовать только API и оно ещё не опубликовано в публичном каталоге. Когда ваше приложение будет доступно в каталоге Приложения24, то Битрикс24 после установки будет оставлять пользователя на странице с описанием приложения.

Укажите эти значения в соответствующих константах, задайте точный URL (APP_REG_URL) к приложению:

Нажмите на рисунок, чтобы увеличить

и обновите скрипт на вашем сервере.

Откройте пример в браузере по вашему URL:

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

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


Как опубликовать решение в каталоге Приложения24

Для создания решения, которое в дальнейшем может быть опубликовано в каталоге Приложения24 необходимо в партнерском кабинете перейти [dw]по цепочке[/dw][di][/di] Кабинет партнера > Приложения24 для Битрикс24 > Добавить приложение. В открывшейся форме необходимо заполнить обязательные поля:

Нажмите на рисунок, чтобы увеличить

Поясним некоторые поля.

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

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

Для простоты стоит указать, что приложение бесплатное (2). Перед подачей на модерацию вы сможете поменять этот и другие описательные параметры своего приложения.

Если решение платное, то укажите один из режимов работы платного решения:

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

Можно сразу привязать свое решение к нужной категории решений (6). Эти категории служат для навигации пользователей по [dw]каталогу решений[/dw][di][/di].

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

Ознакомьтесь с правилами публикации (7). Это необходимо для понимая требований, которые накладываются на тиражные решения.

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

Версии приложения

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

Добавим первую версию приложения. Перейдите [dw]на закладку[/dw][di][/di] Версии и нажмите Добавить новую версию. В открывшейся форме заполните базовые поля и укажите необходимые для приложения права. (Нужно выбирать только права на те модули Битрикс24, которые фактически используются вашим решением) Далее загрузите архив с приложением, или укажите URL внешнего приложения (подробнее о вопросах разработки приложений читайте в соответствующем разделе):

Нажмите на рисунок, чтобы увеличить

После сохранения вы увидите сообщение Решение успешно изменено, а нажав кнопку Версии, увидите [dw]версию в списке[/dw][di][/di].

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

Для этого откройте карточку версии и включите галочку Отправить на модерацию. Ваше решение попадет в соответствующую очередь и будет рассмотрено модераторами. Если они найдут какие-то недочеты или несоответствие правилам, они свяжутся с вами через механизм "Обсуждений", находящийся в карточке вашего решения. Вы получите соответствующие нотификации на свой контактный e-mail.


Как обновлять существующее решение

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

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

Для обновления существующего решения, найдите его в партнерском кабинете [dw]по цепочке[/dw][di][/di] Кабинет партнера > Приложения24 для Битрикс24 > Добавить приложение. В открывшейся форме необходимо заполнить обязательные поля:

Фактически, обновление с точки зрения Битрикс24 - это новая версия приложения. Следовательно, вам нужно опубликовать новую версию, а пользователям в дальнейшем ее установить на своих Битрикс24.

[dw]На закладке[/dw][di][/di] Версии в списке решений найдите нужное и дважды нажмите на него. В открывшейся форме нажмите на кнопку Добавить новую версию. В открывшейся форме заполните базовые поля и укажите необходимые для приложения права. (Нужно выбирать только права на те модули Битрикс24, которые фактически используются вашим решением.) Далее загрузите архив с приложением, или укажите URL внешнего приложения (подробнее о вопросах разработки приложений читайте в соответствующем разделе):

Нажмите на рисунок, чтобы увеличить

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

После сохранения вы увидите сообщение Решение успешно изменено, а нажав кнопку Версии, увидите [dw]версию в списке[/dw][di] [/di].

Когда ваша версия будет полностью готова к публикации: будет находиться на рабочем сервере, вы сами удостоверитесь в её работоспособности, проверите описания и материалы на соответствие регламентам Приложений24 и т.д.), необходимо подать её на модерацию.

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

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

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


Общие вопросы разработки

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

Типы приложений

Все приложения для Битрикс24 можно разделить на 2 типа:

  • Статичные приложения, размещаемые в облаке 1С-Битрикс. Обычно загружаются в виде архива, который содержит в себе весь необходимый html, стили, javascript, картинки. Точкой входа такого приложения считается файл index.html. Инсталлятором - install.html, при его наличии.

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

    Если приложение размещается на стороннем сервере, то имя хоста приложения должно содержать точку. Для разработки и тестирования приложение может размещаться в локальной сети, но, например, localhost для этих целей не подойдет, лучше указать прямой IP. (Локальный адрес будет открываться в iframе на странице приложения на портале. Браузерное ограничение - общение между порталом и содержимым фрейма реализовано через postMessage. Замечено, что некоторые версии браузеров некорректно обрабатывают сообщения, если они исходят от localhost.)

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

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


Взаимодействие с пользовательским интерфейсом Битрикс24

Приложение имеет два варианта добавления пользовательского интерфейса в Битрикс24. 

Базовый 

Этот вариант состоит в том, что если у вашего приложения не включена опция "Использовать только API", то внутри Битрикс24, на котором установлено приложение, будет добавлена отдельная страница, на которой в IFRAME будет выводиться index.html статичного приложения или открываться URL вашего серверного приложения. 

Из IFRAME нельзя получить доступ к родительскому окну. Это большой плюс с точки зрения безопасности, но минус с точки зрения усложнения разработки. Снять ограничения работы в IFRAME помогает JavaScript-библиотека функций. Например:

В случае серверного приложения на точку входа (или инсталлятор) Битрикс24 автоматически передает данные авторизации текущего пользователя и некоторые дополнительные параметры в виде POST-запроса.

Встраивание

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

Для этого установите обработчик места встраивания при помощи placement.bind. Одно приложение может установить произвольное число обработчиков, даже для одного и того же места встраивания (например, если вам нужно добавить несколько разных операций в контекстное меню лида в CRM).

Обработчик ограничен условиями:

  • запрос на установку обработчика должен выполняться с авторизацией администратора,
  • обработчик лежит в том же домене, что и зарегистрированный redirect_uri приложения
  • каждый placement привязан к праву доступа (scope). Чтобы установить обработчик места встраивания в интерфейсе CRM, дайте приложению доступ к CRM. Кроме этого у приложения должен быть указан непосредственно scope механизма встраивания - placement.
Важно: Следствием вышеуказанных пунктов является то, что механизм встраивания доступен только для серверных приложений! 

Метод при установке обработчика определяет места встраивания приложения. При разработке контекстных приложений учитывайте, что у каждого места встраивания могут быть свои особенности отображения и свой js-интерфейс. Например, места встраивания CRM_*_LIST_MENU представляют собой слайдеры, открывающиеся из контекстного меню соответствующих сущностей CRM, а CALL_CARD будет представлять собой переключатель приложений в виде табов в карточке звонка.

Текущий доступный список мест для встраивания описан в справочнике по REST API.

Пример вызова:

http://portal.bitrix24.com/rest/placement.bind/?access_token=sode3flffcmv500fuagrprhllx3soi72
    &PLACEMENT=CRM_CONTACT_LIST_MENU
    &HANDLER=http%3A%2F%2Fwww.applicationhost.com%2Fplacement%2F
    &TITLE=Тестовое приложение

HTTP/1.1 200 OK

{
    "result": true
}

Результат вызова - в контекстном меню списка контактов появляется пункт меню Приложения с подпунктом Тестовое приложение.

Нажмите на рисунок, чтобы увеличить

Как работает встроенное приложение

В примере выше при клике по пункту приложения будет открыт слайдер с приложением. В слайдере будет отображен фрейм, в который будет загружено приложение по заданному адресу обработчика. Работа в этом фрейме мало чем отличается от работы приложения на отдельной странице (базовый вариант добавления интерфейса), за несколькими небольшими исключениями:

  • Не везде будет разрешено менять размер фрейма или влиять на родительское окно, методы BX24.resizeWindow, BX24.fitWindow, BX24.scrollParentWindow, BX24.reloadWindow заблокированы.
  • Данные о контексте вызова обработчика плейсмента будут переданы в POST-данных при вызове обработчика и доступны через js-библиотеку посредством метода BX24.placement.info.

Вот что получится для простейшего обработчика с кодом:

echo '<pre>'; print_r($_REQUEST); echo '</pre>';

При встраивании в меню приложению не предоставляется никакого дополнительного интерфейса. Это неудивительно, учитывая, что слайдер перекрывает интерфейс под собой и не дает никак с ним работать, пока приложение открыто.

JS методы встраивания приложений доступны и при встраивании в интерфейс и на обычной странице приложения с фреймом. В этом случае места встраивания передается как DEFAULT, а параметры контекста вызова - GET-параметры страницы.

Для открытия приложение используйте метод BX24.openApplication, для закрытия - BX24.closeApplication

Помимо прямой встройки в конкретные места интерфейса, существует специфический вариант добавления своего пользовательского интерфейса в карточки различных объектов (в частности, в карточки лида, контакта и .т.д) в виде пользовательских типов полей.

Встраивание приложений в виде пользовательских типов полей

Создание типа поля и поля.

Зарегистрируйте тип поля.

Создайте пользовательское поле вручную либо, через API. Например, для Лидов CRM используется crm.lead.userfield.add.

Обработка данных во фрейме пользовательского типа поля

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

Вот пример POST-данных, пришедших в фрейм:

Array
(
    [DOMAIN] => sometestportal.bitrix24.com
    [PROTOCOL] => 1
    [LANG] => ru
    [APP_SID] => 14d2c95b446cb049375e4a045dc2a177
    [AUTH_ID] => xomlj71xez3p4q8bqsb5icqjcgjetf0p
    [AUTH_EXPIRES] => 3600
    [REFRESH_ID] => 51556ja184k22cqot442w0lp1quxg0p2
    [member_id] => 6f61b5484aff6f8aa3fef768153d0226
    [status] => L
    [PLACEMENT] => USERFIELD_TYPE
    [PLACEMENT_OPTIONS] => {"MODE":"view","ENTITY_ID":"CRM_LEAD","FIELD_NAME":"UF_CRM_1511508634350","ENTITY_VALUE_ID":"2","VALUE":["\u0435\u0445\u0430\u043b \u0433\u0440\u0435\u043a\u0430 \u0447\u0435\u0440\u0435\u0437 \u0440\u0435\u043a\u0443","\u0432\u0438\u0434\u0438\u0442 \u0433\u0440\u0435\u043a\u0430 \u0432 \u0440\u0435\u043a\u0435 \u0440\u0430\u043a","c\u0443\u043d\u0443\u043b \u0433\u0440\u0435\u043a\u0430 \u0440\u0443\u043a\u0443 \u0432 \u0440\u0435\u043a\u0443","\u0440\u0430\u043a \u0437\u0430 \u0440\u0443\u043a\u0443 \u0433\u0440\u0435\u043a\u0430 \u0446\u0430\u043f"],"MULTIPLE":"Y","MANDATORY":"N","XML_ID":null}
)

Детально разберём json-строку PLACEMENT_OPTIONS:

Array
(
    [MODE] => view
    [ENTITY_ID] => CRM_LEAD
    [FIELD_NAME] => UF_CRM_1511508634350
    [ENTITY_VALUE_ID] => 2
    [VALUE] => Array
        (
            [0] => ехал грека через реку
            [1] => видит грека в реке рак
            [2] => cунул грека руку в реку
            [3] => рак за руку грека цап
        )

    [MULTIPLE] => Y
    [MANDATORY] => N
    [XML_ID] => 
)

Ключи:

Ключ Описание
MODE Режим, в котором вызвано поле. Значения: view - просмотр, edit - редактирование
ENTITY_ID Идентификатор сущности, к которой привязано поле
FIELD_NAME Идентификатор пользовательского поля
ENTITY_VALUE_ID Идентификатор элемента сущности, значение поля которого редактируется
VALUE Текущее значение поля. Для множественного поля массив значений.
MULTIPLE Флаг множественности поля
MANDATORY Флаг обязательности поля
XML_ID Внешний код поля

js-интерфейс

Для поля также доступен js-интерфейс получения и установки значения:

BX24.placement.call('getValue', function(value){console.log(value)});

["ехал грека через реку", "видит грека в реке рак", "cунул грека руку в реку", "рак за руку греку цап"]

BX24.placement.call('setValue', ["ехал грека через реку", "видит грека в реке рак", "cунул грека руку в реку", "рак за руку греку цап"], function(){console.log('value set')});

value set

Нужно учитывать, что js-интерфейс служит исключительно для передачи данных в форму. Пока форма тем или иным способом не будет сохранена пользователем, значение в базу не попадет.

Демо-приложение

Демо-приложение, которое регистрирует обычное текстовое поле со своим интерфейсом ввода и вывода. Скачать


Поддержка приложений в коробочном Битрикс24

Битрикс24 существует как в виде облачного сервиса, так и в виде коробочных установок на стороне клиента.

Преимущество приложений на REST в том, что они могут работать и там, и там одинаковым образом, особенно, если при разработке приложения заранее учитывать некоторые нюансы, которые могут возникнуть.

Вариативность версий коробочного Битрикс24

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

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

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

Работа с сервером авторизации Битрикс24

Если ваше приложение возобновляет токены авторизации при помощи refresh_token, то есть два варианта: получать новую пару токенов, делая запрос к

xxx.bitrix24.xxx/oauth/token/?
grant_type=authorization_code... либо к серверу авторизации oauth.bitrix.info/oauth/token/?
grant_type=authorization_code...


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

Поэтому рекомендация номер 2 - для обновления токенов всегда обращайтесь только напрямую к серверу авторизации. Это будет работать и для облака, и для коробки.

Сетевые ограничения

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

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

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

Есть альтернативный вариант, когда вы специально для конкретного клиента на стороне его коробочного Битрикс24 подключите свой механизм авторизации и событий. Подробнее о таком способе было рассказано в докладе Максима Сидоренко:



Провайдеры авторизации

Работа приложений в коробочном Битрикс24, закрытом от внешней сети

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

Примечание: Описанное ниже решение (исключение из процесса авторизации сервера oauth.bitrix.info) рекомендуется к использованию только в крайнем случае, поскольку в этом случае вы самостоятельно должны будете решать вопросы безопасного использования приложений и управления авторизацией


Какие существуют обращения к внешним ресурсам из Битрикс24

В работе Rest-приложения есть три момента, когда происходит обращение из портала во вне:

1 - Валидатор авторизации
2 - Провайдер авторизации
3 - Провайдер событий

Нажмите на рисунок, чтобы увеличить

Рассмотрим способы, которые позволят избежать обращений к внешним ресурсам.

Примечание: В примере рассматривается ситуация, когда необходимо только какое одно, конкретное приложение пустить в обход основной цепочки.

Валидатор авторизации

Создадим свой обработчик событий

<?php
namespace Demo\AuthProvider;

class AuthSimple
{
	const AUTH_TYPE = 'demo_simple';

	const AUTH_PARAM_NAME = 'secret_word';
	const AUTH_PARAM_VALUE = 'MySuperSecurePassword123456';

	public static function onRestCheckAuth(array $query, $scope, &$res)
	{
		if(array_key_exists(static::AUTH_PARAM_NAME, $query))
		{
			$res = array('error' => 'INVALID_CREDENTIALS', 'error_description' => 'Invalid request credentials');

			return false;
		}

		return null;
	}
}

На вход валидатор получает все полные данные запроса приложения. Если в запросе нет параметра secret_word, то он отвечает return now, то есть: "не мой запрос". Если этот параметр в запросе присутствует, то обработчик проверяет запрос по значению. Если значение существует, но не соответствует сохранённому, то в ответ сообщается: "да, запрос мой, но неверное значение". Если значение верное, то он сообщает ID пользователя, список доступных скоупов, указывает какие параметры нужно удалить прежде чем отдавать запрос разработчику и сообщает идентификатор типа авторизации, так как некоторые методы имеют ограничение по типам авторизации.

После этого обработчиком вызывается метод модуля REST, который авторизует на данном хите пользователя. Если всё прошло хорошо, то возвращается true.

Провайдер событий

Отнаследуем оригинальный класс провайдера событий и укажем что он реализует интерфейс провайдера событий. В своём классе мы переопределим только одну функцию send, которая и занимается отправкой. В данном примере мы покажем, как в случае необходимости вызвать внешний обработчик мы вместо обращения к внешней очереди событий, будем выполнять прямой http-запрос обработчика ($http->post(...))

<?php
namespace Demo\AuthProvider;

use Bitrix\Rest\Event\ProviderInterface;
use Bitrix\Rest\Event\ProviderOAuth;
use Bitrix\Rest\Event\Sender;

class EventProvider extends ProviderOAuth implements ProviderInterface
{
	public static function onEventManagerInitialize()
	{
		Sender::setProvider(static::instance());
	}

	public function send(array $queryData)
	{
		$http = new \Bitrix\Main\Web\HttpClient();
		foreach($queryData as $key => $item)
		{
			if($this->checkItem($item))
			{
				$http->post($item['query']['QUERY_URL'], $item['query']['QUERY_DATA']);
				unset($queryData[$key]);
			}
		}

		if(count($queryData) > 0)
		{
			parent::send(array_values($queryData));
		}
	}

	protected function checkItem(array $item)
	{
		return AuthProvider::instance()->checkClient($item['client_id']);
	}
}

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

Провайдер авторизации

Самая сложная часть.

Принцип прежний: отнаследуется оригинальный класс провайдера и создаётся свой класс провайдера, реализующий нужный нам альтернативный интерфейс провайдера авторизации.

<?php
namespace Demo\AuthProvider;


use Bitrix\Main\Context;
use Bitrix\Main\NotImplementedException;
use Bitrix\Main\ObjectNotFoundException;
use Bitrix\Main\Security\Random;
use Bitrix\Rest\Application;
use Bitrix\Rest\AppTable;
use Bitrix\Rest\AuthProviderInterface;
use Bitrix\Rest\OAuth\Provider;
use Bitrix\Rest\RestException;

class AuthProvider extends Provider implements AuthProviderInterface
{
	const TOKEN_TTL = 3600;
	const TOKEN_PREFIX = 'demo.';

	protected $applicationList = array();

	/**
	 * @var AuthProvider
	 */
	protected static $instance = null;

	/**
	 * @var AuthStorageInterface
	 */
	protected $storage;

	/**
	 * @return AuthProvider
	 */
	public static function instance()
	{
		if(static::$instance === null)
		{
			static::$instance = new static();
		}

		return static::$instance;
	}

	public static function onApplicationManagerInitialize()
	{
		Application::setAuthProvider(static::instance());
	}

	public function get($clientId, $scope, $additionalParams, $userId)
	{
		if(!$this->checkClient($clientId))
		{
			return parent::get($clientId, $scope, $additionalParams, $userId);
		}

		if($userId > 0)
		{
			$applicationData = AppTable::getByClientId($clientId);

			if($applicationData)
			{
				$authResult = array(
					'access_token' => $this->generateToken(),
					'user_id' => $userId,
					'client_id' => $clientId,
					'expires' => time() + static::TOKEN_TTL,
					'expires_in' => static::TOKEN_TTL,
					'scope' => $applicationData['SCOPE'],
					'domain' => Context::getCurrent()->getServer()->getHttpHost(),
					'status' => AppTable::STATUS_LOCAL,
					'client_endpoint' => \CRestUtil::getEndpoint(),
					'member_id' => \CRestUtil::getMemberId(),
				);

				$this->store($authResult);

				return $authResult;
			}
			else
			{
				$authResult = array('error' => RestException::ERROR_OAUTH, 'Application not installed');
			}

			return $authResult;
		}

		return false;
	}

	public function authorizeClient($clientId, $userId, $state = '')
	{
		if(!$this->checkClient($clientId))
		{
			return parent::authorizeClient($clientId, $userId, $state);
		}

		throw new NotImplementedException('Full OAuth authorization is not implemented in this demo');
	}

	public function checkClient($clientId)
	{
		return in_array($clientId, $this->applicationList);
	}

	protected function store(array $authResult)
	{
		$this->getStorage()->store($authResult);
	}

	public function checkToken($token)
	{
		return substr($token, 0, strlen(static::TOKEN_PREFIX)) === static::TOKEN_PREFIX;
	}

	protected function generateToken()
	{
		return static::TOKEN_PREFIX.Random::getString(32);
	}

	/**
	 * @return AuthStorageInterface
	 * @throws ObjectNotFoundException
	 */
	public function getStorage()
	{
		if($this->storage === null)
		{
			throw new ObjectNotFoundException('No token storage set. Use '.__CLASS__.'::instance()->setStorage().');
		}

		return $this->storage;
	}

	/**
	 * @param AuthStorageInterface $storage
	 * @return AuthProvider
	 */
	public function setStorage(AuthStorageInterface $storage)
	{
		$this->storage = $storage;

		return $this;
	}

	/**
	 * @param string $clientId
	 * @return AuthProvider
	 */
	public function addApplication($clientId)
	{
		$this->applicationList[] = $clientId;

		return $this;
	}
}

Основной метод - метод get, который служит для выдачи авторизации приложению. Метод получает на вход приложение, которое "затребовало" авторизацию и проверяет, является ли это приложение тем самым, которое мы хотим "пустить в обход" стандартного механизма авторизации. Далее получаются данные о приложении и формируется структура, схожая со структурой, которую получают все приложения от стандартного OAuth-сервера Битрикс24. В массиве:

  • access_token - созданный токен.
  • user_id - пользователь для которого нужно дать авторизацию.
  • client_id - приложение. Обратите внимание, что можно указать любое время жизни токена, а не только час времени, используемый по умолчанию в обычной авторизации.
  • expires - дата истечения токена.
  • scope - требуемые скоупы.
  • служебные данные.

Далее эти данные сохраняются на портале. Далее сформированная структура возвращается.

Дополнительные методы

Далее регистрируем наш провайдер в качестве текущего провайдера авторизации:

\Bitrix\Rest\Application::setAuthProvider(
      Demo\AuthProvider\AuthProvider::instance()
);

Если теперь совершить запрос с этим авторизационным токеном и вызвать метод \Bitrix\Rest\AppInfo, то мы получим данные приложения в текущем Битрикс24:

Делаем свой валидатор авторизации.

<?php
namespace Demo\AuthProvider;

use Bitrix\Rest\OAuth\Auth;

class AuthFull extends Auth
{
	protected static function check($accessToken)
	{
		if(!AuthProvider::instance()->checkToken($accessToken))
		{
			return parent::check($accessToken);
		}

		$authResult = AuthProvider::instance()->getStorage()->restore($accessToken);

		if($authResult === false)
		{
			$authResult = array('error' => 'invalid_token', 'error_description' => 'Token expired or invalid');
		}

		return $authResult;
	}

}

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

\Bitrix\Main\EventHandler::getInstance()
      ->registerEventHadler(
             "rest", "onRestCheckAuth", "demo.authprovider", "\\Demo\\AuthProvider\\AuthFull", "onRestCheckAuth", 90
         );

Последний параметр - сортировка. Необходимо встроиться до того как сработает оригинальный обработчик.

Если теперь совершить запрос с этим авторизационным токеном и вызвать метод \Bitrix\Rest\AppInfo и получить данные приложения на этом портале.

Осталось только дополнить провайдер событий, чтобы передавать приложению авторизационные данные в обработчики событий:

if($item['additional']['sendAuth'])
				{
					$item['query']['QUERY_DATA']['auth'] = AuthProvider::instance()->get(
						$item['client_id'],
						'',
						$item['auth'],
						$item['auth'][AuthFull::PARAM_LOCAL_USER]
					);
				}
Полный код провайдера событий

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

Небольшое замечание по поводу производительности. Код, добавленный в провайдер событий в нашем примере выше, выполняется непосредственно в обработчике события. В коде есть post запрос к стороннему серверу. Следовательно, если сторонний сервер "тормозит", то будет "тормозить" и весь портал. Если производится какая-то массовая операция, например: импорт данных в CRM, то этот код серьёзно может замедлить работу портала.

Обойти эту проблему производительности можно двумя способами:

  • Построение очереди. Вместо отправки post запроса складывать данные в какую-то таблицу и какими-то дополнительными процессами выбирать из неё данные. По сути - кастомная реализация очереди.
  • Воспользоваться механизмом офлайн событий

Заключение

Таким образом можно заставить работать портал и приложение работать друг с другом без обращения "во вне" из локальной сети. Однако такое решение (исключение из процесса авторизации сервера oauth.bitrix.info) рекомендуется только в крайнем случае.


Сценарии получения приложением доступа к REST API

Под получением доступа к REST API мы всегда подразумеваем исключительно технические аспекты. Разработчик не должен спрашивать какого-то специального "разрешения" на использование REST у компании 1С-Битрикс.

Фактически, под "получением доступа" подразумевается способ, как приложение получит авторизационный токен для вызова конкретного метода REST API.

И тут есть несколько вариантов:
  • разработчик может создать локальное приложение для конкретного Битрикс24, обладая для этого правами администратора, и тогда приложение получит токены по протоколу OAuth 2.0;
  • любой пользователь Битрикс24 может воспользоваться механизмом вебхуков, представляющих собой простой способ получения токенов;
  • разработчик может создать приложение (локальное своем собственном Битрикс24 или публичное тиражное решение, став технологическим партнером 1С-Битрикс и зарегистрировав решение в партнерском кабинете) и тогда это решение получит возможность работать с любыми Битрикс24, получая токены по протоколу OAuth 2.0.



Полный протокол OAuth 2.0

OAuth - открытый протокол авторизации, который позволяет предоставить третьей стороне ограниченный доступ к защищенным ресурсам пользователя без необходимости передавать ей (третьей стороне) логин и пароль.

Примечание: Реализация полного протокола необходима только для серверных приложений со включенной опцией "Использовать только API". Статические приложения и серверные приложения с интерфейсом внутри Битрикс24 получают авторизацию при подключении js-библиотеки, а также в данных POST-запроса на URL-приложения при открытии приложения.

Как работает протокол

Протокол очень распространён, используется огромным количеством сервисов по всему миру, поскольку позволяет приложению получить доступ к API от имени конкретного пользователя конкретного портала.

Для сервера авторизация - это указание на то, что пользователь дал доступ приложению, приложение предоставляет свой секрет. Портал это всё объединяет и выдаёт приложению соответствующий тип доступа.

Протокол состоит из двух шагов:

  • Пользователь сообщает порталу, что он авторизован. Приложение добавляет свой идентификатор: client id. В ответ сервер передаёт пользователю, а через него и приложению, первый авторизационный код: code.
  • Этот код приложение, уже скрыто от пользователя, передаёт обратно порталу, присоединяя к нему свой секретный ключ: client secret. Приложение таким образом подтверждает, что оно то самое приложение, которое известно порталу и которое может с ним работать. В ответ портал сообщает два параметра: access_token - параметр, который собственно требуется для доступа к авторизации и refresh_token - токен, который требуется для продления авторизации.
  • После использования refresh_token и выданный вместе с ним access_token становятся недействительными. Для доступа к REST API следует использовать новый полученный access_token, а для продления доступа - новый refresh_token.

Внимание! Время жизни первого авторизационного кода code составляет всего 30 секунд, то есть, он должен быть использован сразу после получения.

Общий порядок работы с OAuth

  • добавляется и устанавливается тиражное приложение, либо локальное в своем отдельном Битрикс24;
  • запрашиваются с удаленного сервера ключи;
  • сервер перенаправляет браузер на зарегистрированный приложением URL;
  • обрабатывается ответ;
  • подписываются полученным ключом все запросы к Rest API.

Полная OAuth-авторизация в Битрикс24

В качестве сервера данных и держателя пользовательской авторизации выступает конкретный Битрикс24. В качестве держателя авторизации приложения служит сервер авторизации, доступный по адресу https://oauth.bitrix.info/.

Полный сценарий OAuth-авторизации проходит в несколько шагов:

  1. Авторизация пользователя в Битрикс24.

    Приложение запрашивает у пользователя адрес Битрикс24 и переадресует его на специально сформированный URL, например, такой:

    https://portal.bitrix24.com/oauth/authorize/?
        client_id=app.573ad8a0346747.09223434
        &state=JJHgsdgfkdaslg7lbadsfg

    Параметры:

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

    По данной ссылке пользователю будет выведена форма авторизации. После авторизации (либо при наличии авторизованной сессии), если приложение с переданным client_id установлено на портале, портал вернет пользователя на redirect_uri приложения. Если же приложение на портал не установлено, пользователю будет выведено соответствующее сообщение об ошибке.

    Итогом успешной пользовательской авторизации должен стать возврат пользователя на зарегистрированный адрес приложения с дополнительными параметрами:

    https://www.applicationhost.com/application/?
        code=avmocpghblyi01m3h42bljvqtyd19sw1
        &state=JJHgsdgfkdaslg7lbadsfg
        &domain=portal.bitrix24.com
        &member_id=a223c6b3710f85df22e9377d6c4f7553
        &scope=crm%2Centity%2Cim%2Ctask
        &server_domain=oauth.bitrix.info

    Параметры:

    • code - первый авторизационный код, см. ниже;
    • state - значение переданное в первом запросе;
    • domain - домен портала, на котором происходит авторизация;
    • member_id - уникальный идентификатор портала, на котором происходит авторизация;
    • scope - разделенный запятыми список прав доступа к REST API, которые портал предоставляет приложению;
    • server_domain - домен сервера авторизации.

    Внимание! В партнерском кабинете можно зарегистрировать приложение, которое не будет иметь "обратного адреса" redirect_uri. (По redirect_uri получаются авторизационные данные.) Такой сценарий возможен для тиражных решений, которые не имеют постоянного адреса. В этом случае предполагается, что пользователь вручную передает первый авторизационный код приложению. Упрощенный первый авторизационный код будет выведен пользователю непосредственно на странице, а приложение должно предоставить пользователю поле для ввода значения кода.

  2. Авторизация приложения

    Внимание! Предыдущая реализация протокола предполагала отдачу client_secret приложения непосредственно Битрикс24. В связи с расширением механизма REST API на коробочные установки Битрикс24 такое действие становится небезопасным. Все операции, предполагающие участие секретного кода приложения должны проводиться исключительно с сервером авторизации oauth.bitrix.info. По той же причине этот сервер авторизации должен быть единственным доверенным источником информации о платежном статусе приложения на портале.

    Получив тем или иным способом первый авторизационный код code приложение должно совершить второй шаг OAuth-авторизации и сделать скрытый от пользователя запрос вида:

    https://oauth.bitrix.info/oauth/token/?
        grant_type=authorization_code
        &client_id=app.573ad8a0346747.09223434
        &client_secret=LJSl0lNB76B5YY6u0YVQ3AW0DrVADcRTwVr4y99PXU1BWQybWK
        &code=avmocpghblyi01m3h42bljvqtyd19sw1

    Параметры (все - обязательны):

    • grant_type - параметр, показывающий тип авторизационных данных, подлежащих валидации. Должен иметь значение authorization_code;
    • client_id - код приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
    • client_secret - секретный ключ приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
    • code - значение параметра code, переданного приложению в конце предыдущего шага.

    Внимание! Время жизни первого авторизационного кода code - всего 30 секунд, и он должен быть использован сразу после получения.

    В ответ на такой запрос приложение получит json следующего содержания:

    GET /oauth/token/
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "access_token": "s1morf609228iwyjjpvfv6wsvuja4p8u",  
        "client_endpoint": "https://portal.bitrix24.com/rest/",  
        "domain": "oauth.bitrix.info",  
        "expires_in": 3600,  
        "member_id": "a223c6b3710f85df22e9377d6c4f7553",  
        "refresh_token": "4f9k4jpmg13usmybzuqknt2v9fh0q6rl",  
        "scope": "app",  
        "server_endpoint": "https://oauth.bitrix.info/rest/",  
        "status": "T"
    }

    Значимые параметры:

    • access_token - основной авторизационный токен, требуемый для доступа к REST API;
    • refresh_token - дополнительный авторизационный токен, служащий для продления сохраненной авторизации;
    • client_endpoint - адрес REST-интерфейса портала;
    • server_endpoint - адрес REST-интерфейса сервера;
    • status - статус приложения на портале.

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

    {
        "error": "PAYMENT_REQUIRED",  
        "error_description": "Payment required"
    }
Примеры, реализующие полный протокол OAuth 2.0 были даны в разделах "Быстрый старт" для локального и публичного приложений.

Упрощенный вариант получения токенов OAuth 2.0

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

Приложение получает следующий массив POST-данных:

array (
  'DOMAIN' => 'portal.bitrix24.com', // домен портала
  'PROTOCOL' => '1', // протокол обращения: 0 - http, 1 - https
  'LANG' => 'ru', // текущий язык, на котором пользователь просматривает портал
  'APP_SID' => 'dd8cec11e347088fe87c44870a9f1dba', // служебный параметр для связи js-библиотеки с окружением приложения
  'AUTH_ID' => 'ahodg4h37n89vo17gbkgq0x1l825nnb5', // основной авторизационный токен, требуемый для доступа к REST API
  'AUTH_EXPIRES' => '3600', // время жизни авторизационного токена
  'REFRESH_ID' => '2lg086mxijlpvwh0h7r4nl19udm4try5', // дополнительный авторизационный токен, служащий для продления сохраненной авторизации
  'member_id' => 'a223c6b3710f85df22e9377d6c4f7553', // уникальный идентификатор портала, не зависящий от доменного имени
  'status' => 'P', // статус приложения на портале. значение поля служит чисто для информации, чтобы получить доверенное значение, используйте метод oauth.bitrix.info/rest/app.info
)

При помощи значения параметра AUTH_ID можно сразу совершать запросы к API.

И как написано выше, приложения в интерфейсе могут совершать запросы к API на стороне клиента, то есть, браузера пользователя, подключив js-библиотеку и используя методы BX24.callMethod и BX24.callBatch. В этом случае работа с авторизацией будет происходить автоматически.

Таким образом, становится доступным простой сценарий получения авторизационных токенов пользователя при установке приложения. Как вы знаете (это было продемонстрировано в соответствующем примере раздела "Быстрый старт"), у публичного тиражного решения существует возможность задать отдельный скрипт установки, который будет показываться пользователю, устанавливающему ваше решение, во фрейме один раз - в момент установки решения. И в этот фрейм Битрикс24 передает те же самые данные в POST-запросе, что и в обычном случае. Следовательно, вы можете так разработать скрипт установки, чтобы сохранять токены (что самое важное - refresh_token в том числе) на стороне своего приложения, чтобы в дальнейшем реализовать сценарий автоматического возобновления токенов

Событие установки приложения

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

Для приложений, не имеющих страницы в интерфейсе Битрикс24 (параметр Использует только API в форме редактирования приложения в партнерском кабинете или на портале), доступен вот такой способ авторизации. В форме редактирования версии (или в форме редактирования локального приложения на портале) можно указать значение параметра Ссылка-callback для события установки. Если указать в этом поле ссылку на обработчик на стороне приложения, то при установке приложения обработчик получит POST-запрос со следующими данными (application/x-www-form-urlencoded):

array(
  'event' => 'ONAPPINSTALL',
  'data' => array(
    'VERSION' => '1',
    'LANGUAGE_ID' => 'ru',
  ),
  'ts' => '1466439714',
  'auth' => array(
    'access_token' => 's6p6eclrvim6da22ft9ch94ekreb52lv',
    'expires_in' => '3600',
    'scope' => 'entity,im',
    'domain' => 'portal.bitrix24.com',
    'server_endpoint' => 'https://oauth.bitrix.info/rest/',
    'status' => 'F',
    'client_endpoint' => 'https://portal.bitrix24.ru/rest/',
    'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
    'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8',
    'application_token' => '51856fefc120afa4b628cc82d3935cce',
  ),
)

Поля запроса содержат информацию о событии (event), данные события (data), а также, авторизационные данные для доступа к REST API (auth) от имени пользователя, установившего приложение.

Значимые параметры:

  • access_token - основной авторизационный токен, требуемый для доступа к REST API;
  • refresh_token - дополнительный авторизационный токен, служащий для продления сохраненной авторизации;
  • client_endpoint - адрес REST-интерфейса портала;
  • server_endpoint - адрес REST-интерфейса сервера;
  • status - статус приложения на портале.

Смотри События

Примечание: Обычно авторизационные данные, передаваемые обработчикам событий, не содержат данных для продления авторизации (refresh_token). Некоторые важные события,например, событие установки приложения ONAPPINSTALL, являются исключениями.


Автоматическое продление авторизации OAuth 2.0

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

В любой момент до истечения refresh_token приложение может совершить следующий запрос:

https://oauth.bitrix.info/oauth/token/?
    grant_type=refresh_token
    &client_id=app.573ad8a0346747.09223434
    &client_secret=LJSl0lNB76B5YY6u0YVQ3AW0DrVADcRTwVr4y99PXU1BWQybWK
    &refresh_token=nfhxkzk3gvrg375wl7u7xex9awz6o3k8

Параметры (все - обязательные):

  • grant_type - параметр, показывающий тип авторизационных данных, подлежащих валидации. Должен иметь значение refresh_token;
  • client_id - код приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
  • client_secret - секретный ключ приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
  • refresh_token - значение сохраненного токена продления авторизации

В ответ приложение получит json следующего вида:

GET /oauth/token/

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "ydtj8pho532wydb5ixk78ol7uqlb7sch",  
    "client_endpoint": "http://portal.bitrix24.com/rest/",  
    "domain": "oauth.bitrix.info",  
    "expires_in": 3600,  
    "member_id": "a223c6b3710f85df22e9377d6c4f7553",  
    "refresh_token": "3s6lr4kr3cv2od4v853gvrchb875bwxb",  
    "scope": "app",  
    "server_endpoint": "http://oauth.bitrix.info/rest/",  
    "status": "T"
}

Значимые параметры:

  • access_token - основной авторизационный токен, требуемый для доступа к REST API (Время жизни - 1 час.);
  • refresh_token - новое значение дополнительного авторизационного токена, служащего для продления сохраненной авторизации;
  • client_endpoint - адрес REST-интерфейса портала;
  • server_endpoint - адрес REST-интерфейса сервера;
  • status - статус приложения на портале.

Внимание! После совершения указанного запроса refresh_token и выданный вместе с ним access_token становятся невалидными! Для совершения запросов к REST API и для продления авторизации следует использовать новые access_token и refresh_token. При этом параллельно может существовать неограниченное количество таких цепочек продления авторизации для одного пользователя портала и одного приложения, но каждая должна инициироваться одним из вышеперечисленных способов получения авторизации, без возможности ветвления.

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

{
    "error": "PAYMENT_REQUIRED",  
    "error_description": "Payment required"
}

Если сценарий вашего приложения требует постоянного фонового обмена данными с Битрикс24 без участия пользователя, то необходимо продумать хранение refresh-токенов и механизм их использования. Как уже было указано выше, refresh_token сохраняет свою актуальность в течение 28 дней. Это значит, что если ваше приложение по каким-то причинам не обращается к Битрикс24 чаще "само по себе" для реализации функционала приложения, то вам достаточно раз в 28 дней обращаться к серверу авторизации, только чтобы обновить сохраненные токены.

Мы сталкивались со случаями, когда разработчики приложений "на всякий случай" перед каждым обращением к REST сначала "дергали" сервер авторизации для обновления токена. Это неправильный сценарий, создающий лишнюю нагрузку. Тоже самое касается сценариев с автоматическим "обновлением токенов" раз в час, или раз в сутки - это лишнее.

Если вы сохраняете пару токенов - access_token и refresh_token - на стороне приложения, то вы просто делаете запрос к REST, указав сохраненный access_token (предположим, что вы, сохранив access_token, не сохранили дату и время его "протухания"). Если токен уже неактуален, в ответ вы получите соответствующую ошибку. Вот в этот момент надо сделать запрос с сохраненным refresh_token на сервер авторизации для получения нового access_token, и получив в ответ оба новых токена - сохранить их на стороне приложения, а затем выполнить свой REST запрос с новым access_token

Cписок доступных значений SCOPE

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

Например, если ваше решение интегрирует Битрикс24 с внешней телефонией и пользуетесь методами telephony.externalcall.register и telephony.externalcall.finish, которые добавляют в том числе лиды в CRM, но при этом не обращаетесь явно к методам CRM вроде crm.lead.add и crm.activity.add, то SCOPE telephony вам нужен, а вот SCOPE crm - нет.

Значения
calendar Календарь
crm CRM
disk Диск
department Структура компании
entity Хранилище данных
im Чат и уведомления
imbot Создание и управление Чат-ботами
lists Списки
log Живая лента
sonet_group Рабочие группы
task Задачи
telephony Телефония
call Телефония (совершение звонков)
В скоуп входят методы:
voximplant.infocall.startwithsound voximplant.infocall.startwithtext
user Пользователи
imopenlines Открытые линии
placement Встраивание приложений
messageservice Служба сообщений
pay_system Платёжные системы
landing Сайты
faceid Распознавание лиц
userconsent Работа с соглашениями
mobile Мобильное приложение


Интерактивность в приложениях

Интерактивность в приложениях доступна с версии 18.5.500 модуля Push & Pull.

Благодаря подключению к RT-серверам вы сможете:

  • создать действительно интерактивное приложение,
  • менять состояния,
  • мгновенно обновлять интерфейс без необходимости обновления страницы в режиме реального времени.

Если вы создаёте своего клиента, то ознакомьтесь со Схемой работы с Push & Pull server. Если вам нужно только добавить интерактивность в существующее приложение, то почитайте про Работу с Push & Pull в рамках браузера


Работа с Push & Pull в рамках браузера

Рассмотрим как работать со штатным Push & Pull клиентом в рамках приложения. Пример страницы для приложения с веб-интерфейсом:

<!DOCTYPE html>
<html>
<head>
	<title>Bitri24 application with Push & Pull</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

	<script src="//api.bitrix24.com/api/v1/"></script>
	<script src="//api.bitrix24.com/api/v1/pull/"></script>
</head>
<body>
	<script>
		
		window.appPullClient = new BX.PullClient({
			restApplication: 'myApplication',
			restClient: BX24,
			userId: 1
		});

		window.appPullClient.subscribe({
			moduleId: 'application',
			callback: function (data) {
				console.warn(data); // {command: '...', params: {...}, extra: {...}}
			}.bind(this)
		});
		
		window.appPullClient.start();
				
	</script>
</body>
</html>

При инициализации BX.PullClient необходимо указать следующие параметры:

  • restApplication - укажите произвольный строковый идентификатор приложения
  • userId - укажите идентификатор текущего авторизованного пользователя

Если веб-страницу у вас создаёт "1С-Битрикс: Управление сайтом" и вашу редакцию входит модуль Push & Pull, рекомендуется вместо подключения:

<script src="//api.bitrix24.com/api/v1/pull/"></script> 

[dw]подключать встроенную библиотеку[/dw][di]Минимальная версия модуля pull 18.5.500[/di] через:

\Bitrix\Main\UI\Extension::load("pull.client");

Подключение PullClient позволит front-end вашего приложения получать события из канала, которые туда будет отправлять back-end вашего же приложения при помощи метода pull.application.event.add.


Схема работы с Push & Pull server

Интерактивное приложения

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

С помощью подключения к RT-серверам создаётся действительно интерактивное приложение: меняется состояние приложения, мгновенно обновляется интерфейс без необходимости ajax запросов. Прочитать про технологию вы можете в курсе Администратор. Модули.


Разработка приложения, основные сведения

Для работы с сервисом есть два способа подключения: [ds]Long polling и websocket[/ds][di]Когда пользователь входит на сайт, его браузер, настольное или мобильное приложение устанавливают и держат постоянное соединение с Push-сервером.
Обычно это делается с помощью WebSocket , который используют 95% современных браузеров. А если технология WebSocket не поддерживается браузером, то используется Long Polling — постоянный долгий опрос.

Подробнее ...[/di]. Основным методом подключения рекомендуется использовать websocket. Long polling используется только для устройств у которых нет поддержки websocket, или если при подключении к websocket у клиента часто возникают проблемы.

Для получения данных о сервере и адресах подключения используйте REST команду pull.application.config.get

Для подключения к серверу, возьмите в настройках сервера (поле server) адрес подключения нужного типа (например, websocket_secure) и [dw]добавьте[/dw][di]Каналы перечисляются в GET параметре CHANNEL_ID.[/di] к нему все доступные каналы через /.

Пример подключения для websocket:

wss://rt.bitrix24.com/sub/?CHANNEL_ID=46a437d2336d4a88e4e9b3cd956ecf45:6221e0eb48981fce67cf4756e82e8102.7910bb25e660bf211fdec15e33c5e25e4c3b644a/fb9f7e13dc3d595c5aefe1a0216c27a2.2887eebc6ae160713a732893462dce9d8e23a7b0

Время работы каждого канала ограничено 12 часами. Необходимо отслеживать время окончания и делать повторный запрос к pull.application.config.get когда у одного из каналов завершилось время работы.

Для доступа к истории в канала к указанному выше адресу добавьте специальные get-метки: &tag= и &time= (для версии сервера 2 и ниже) или &mid= (для версии 3 и выше). Все необходимые данные для get-меток вы получите при разборе каждой команды из канала. После подключения с данными метками, вам будут одноразово доступны сообщения, которые для текущей сессии не были доступны.


Общий формат поступающих команд от сервера

Для сервера версии 3 и ниже при поступлении команд, приходит текст вида:

#!NGINXNMS!#{"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}}#!NGINXNME!#
#!NGINXNMS!#{"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}#!NGINXNME!#

Для работы с командой, необходимо получить её содержимое и преобразовать в JSON. Текст команды располагается между управляющими фразами #!NGINXNMS!# и #!NGINXNME!#.

Начиная с версии сервера 4, используйте добавление GET-параметра &format=json при подключении и при поступлении команд, он будет вам отдан в формате JSON:

[
    {"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}},
    {"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}
]

JSON структура команды имеет следующий унифицированный вид:

{
    "id" : 320146,
    "mid" : "14526134350000000000320146",
    "channel" : "6221e0eb48981fce67cf4756e82e8102",
    "tag" : "672",
    "time" :"Mon, 03 Oct 2017 06:36:01 GMT",
    "text" : {
        "module_id" : "main",
        "command" : "user_online",
        "params" : {
            ...
        },
    "extra" : {
        "server_time": "2017-10-03T08:36:01+02:00",
        "server_time_unix": 1507012561,
        "server_time_ago": 0,
        'revision': 16,
		'revisionMobile': 1,
        "channel" : "6221e0eb48981fce67cf4756e82e8102"
    }
}

Где:

  • id - идентификатор сообщения
  • mid - идентификатор сообщения (только для версии сервера 3 и выше, используется для восстановления истории с определенного сообщения)
  • channel - идентификатор канала (только для версии сервера 3 и выше, для более ранних, используйте extra.channel )
  • tag - E-tag (для версии сервера 2 и ниже, используется для восстановления истории с определенного сообщения)
  • time - время сообщения (для версии сервера 2 и ниже, используется для восстановления истории с определенного сообщения)
  • text - структура, описывающая действие команды, содержит следующие ключи:
    • module_id - идентификатор модуля отправившего команду (для приложений marketplace - appId)
    • command - идентификатор команды
    • params - дополнительные данные для выполнения команды
  • extra - структура, описывающая дополнительные сведения:
    • server_time - Время сервера на момент формирования команды (формат ATOM)
    • server_time_unix - Время сервера на момент формирования команды (в формате Unix timestamp с часовым поясом браузера)
    • server_time_ago - Количество секунд прошедших с момента отправки команды
    • server_name - имя сервера отправившего команду
    • revision - ревизия модуля push & pull для браузерного скрипта
    • revisionMobile - ревизия модуля push & pull для мобильного клиента
    • channel - идентификатор канала (только для версии сервера 1)


Работа с ошибками сервера

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

Если подключение к серверу приводит к ошибкам, необходимо инкрементально увеличивать время подключения:

  • При возникновении ошибки в первый раз, задержка при подключении - 100мс.
  • При повторной ошибке - 15 секунд.
  • От 3 до 5 ошибок - 45 секунд.
  • От 5 до 10 ошибок - 10 минут.
  • Более 10 ошибок подряд - 1 час.

При работе с websocket при возникновении ошибок более 4х раз, рекомендуется переходить на работу с Long polling. Очень вероятна ситуации что на компьютере клиента заблокирована работа websocket протокола (код завершения websocket 1006 и 1008).

Полный переход на Long polling, имеет смысл если вы ни разу не смогли подключится по websocket, если ранее были успешные подключения то имеет смысл переключится временно на 10 - 30 минут.


Формат поступающих команд для управления подключением

Для собственной реализации работы с протоколом Push & Pull предусмотрите обработку управляющих команд.

channel_expire

Команда о истечении времени работы канала.

{
    "module_id" : "pull",
    "command" : "channel_expire",
    "params" : {
        "action" : "reconnect",
        "channel" : {
            "id" : "46a437d2336d4a88e4e9b3cd956ecf45.7910bb25e660bf211fdec15e33c5e25e4c3b644a",
            "type": "shared"
        },
        "new_channel": {
            "id": "fb9f7e13dc3d595c5aefe1a0216c27a2.2887eebc6ae160713a732893462dce9d8e23a7b0",
            "start": "2017-06-28T09:57:48+02:00",
            "end": "2017-06-28T21:57:48+02:00",
            "type": "shared"
        }
    }
}

Параметры

ПараметрОписание
action Описание необходимого действия.
channel Информация о канале для которого получена команда.
new_channel Информация о новом канале. Доступна только если action == reconnect.

Описание работы с командой

При поступлении команды channel_expire, в зависимости от значения action, выполните:

  • Если action == reconnect, то данными из new_channel замените информацию о [dw]текущем канале[/dw][di]Информация о каком канале речь есть в channel[/di]. После чего переустановите подключение к серверу заново.
  • Если action == get_config, то отключитесь от сервера, запросите новые данные о каналах через REST [link=9668049]pull.application.config.get[/link]. После чего установите подключение к серверу заново.

config_expire и server_restart

Команда о изменении настроек сервера

{
    "module_id" : "pull",
    "command" : "config_expire",
    "params" : {}
}

Описание работы с командой

Если поступила команда config_expire или server_restart, то отключитесь от сервера, и через случайный промежуток времени (от 10 до 120 секунд), запросите новые данные о каналах через REST pull.application.config.get. После чего установите подключение к серверу заново.


События REST

REST API позволяет устанавливать свои обработчики событий в Битрикс24.

Обработчиком служит URL, который будет вызван после того, как пользователь произведет запрошенное действие в Битрикс24, на котором установлено приложение. Поскольку запросы будут идти с серверов Битрикс, то URL обработчика должен быть доступен для GET/POST запросов извне.

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

Текущие адреса сервера.

Как работают события

Сначала приложение при помощи REST-метода event.bind устанавливает обработчик события. Под обработчиком события подразумевается URL, на который будет передана информация о том, что на портале произошло отслеживаемое событие.

Спустя какое-то время пользователь совершает какое-то действие (создаёт задачу, изменяет задачу и так далее). Битрикс24 автоматически уведомляет об этом приложение.

Подробнее механизм событий описан в справочнике REST

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

Механизм оффлайн-событий

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

Механизм оффлайн события используется для работы со сторонними информационными системами, например, с 1С. Выпуск планируется на начало-середину марта.

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

Внимание! Все методы работы с событиями, будь то установка/удаление обработчиков или чтение очереди, требуют наличия административных прав и доступны для выполнения только с авторизацией приложения. То есть вебхуки с этими методами работать не будут.

Записи в очереди аккумулируются по данным событий. Например, если в очереди уже ожидает событие ONCRMLEADUPDATE для лида с ID=10, то следующее обновление лида 10 не добавит новую запись, а только изменит дату существующей.

Установка обработчика события

Используется метод /rest/event.bind со значением event_type=offline. В этом случае параметр handler становится не обязательным, а параметр auth_type - бессмысленным.

Пример вызова:

https://myportal.bitrix24.com/rest/event.bind
  ?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36
  &event=ONCRMLEADUPDATE
  &event_type=offline

HTTP/1.1 200 OK

{
    "result": true 
}

После вызова установки обработчика метод /rest/event.get выдает нам вот такую картину (обычный обработчик события добавил для сравнения):

https://myportal.bitrix24.com/rest/event.get
  ?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36

HTTP/1.1 200 OK

{
    "result": [
        {
            "connector_id": "", 
            "event": "ONCRMLEADUPDATE", 
            "offline": 1
        }, 
        {
            "auth_type": "0", 
            "event": "ONCRMLEADUPDATE", 
            "handler": "http://apphost.com/handler/", 
            "offline": 0
        }
    ]
}

Для отписки от события используется тот же самый метод /rest/event.unbind, вызываемый с теми же параметрами, что и event.bind.

Далее происходит разбор очереди событий.

Простая схема

Если приложение вызывает метод /rest/event.offline.get, то портал отдаст первые 50 событий, удовлетворяющих фильтру и в заданном порядке сортировки, и сразу вычистит их из базы.

https://myportal.bitrix24.com/rest/event.offline.get
  ?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36

HTTP/1.1 200 OK

{
    "result": {
        "events": [
            {
                "EVENT_ADDITIONAL": {
                    "user_id": "1"
                }, 
                "EVENT_DATA": {
                    "FIELDS": {
                        "ID": 28
                    }
                }, 
                "EVENT_NAME": "ONCRMLEADUPDATE", 
                "ID": "40", 
                "MESSAGE_ID": "438d4ec3d329464c4bb9909db4c7a19b", 
                "TIMESTAMP_X": "2018-02-14T14:20:19+02:00"
            }
        ], 
        "process_id": null
    }
}

Поля записей массива events
ID Идентификатор записи очереди событий
TIMESTAMP_X Дата последнего срабатывания события
EVENT_NAME Имя события
EVENT_DATA Данные события
EVENT_ADDITIONAL Дополнительные параметры события. Пока содержит единственный параметр - ID пользователя, спровоцировавшего последнее срабатывание события.
MESSAGE_ID Уникальные идентификатор "срабатывания" события. Представляет собой хэш от типа события и данных события. То есть, все события ONCRMLEADUPDATE с данными {FIELDS:{ID:28}} будут иметь один и тот же MESSAGE_ID, и по нему будут объединены в одну запись. Используется в контроле ошибок по усложнённой схеме

Метод event.offline.get поддерживает многопоточный разбор. То есть допускается несколько параллельных запросов к методу (с соблюдением ограничений на количество запросов в единицу времени), и каждый из них получит разные наборы записей.

Усложнённая схема

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


Получение записей

Включается эта схема добавлением параметра clear=0 к вызову event.offline.get.

https://myportal.bitrix24.com/rest/event.offline.get
  ?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36
  &clear=0

HTTP/1.1 200 OK

{
    "result": {
        "events": [
            {
                "EVENT_ADDITIONAL": {
                    "user_id": "1"
                }, 
                "EVENT_DATA": {
                    "FIELDS": {
                        "ID": 28
                    }
                }, 
                "EVENT_NAME": "ONCRMLEADUPDATE", 
                "ID": "45", 
                "MESSAGE_ID": "438d4ec3d329464c4bb9909db4c7a19b", 
                "TIMESTAMP_X": "2018-02-14T14:43:13+02:00"
            }
        ], 
        "process_id": "5xcvetmo5zm5li73qxnj8qu72e2qrxw8"
    }
}

Обратите внимание на поле process_id в ответе. После такого вызова записи остаются в базе, но помечаются как обрабатываемые процессом с этим идентификатором. И далее не учитываются ни при каких последующих выборках и при добавлении новых событий.

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


Очистка записей

Очистка производится вызовом метода /rest/event.offline.clear, который принимает на вход process_id и массив идентификаторов записей, которые нужно удалить.

https://myportal.bitrix24.com/rest/event.offline.clear
  ?auth=0534845a0000cd7a0000cd5d00000001000003bc52a2dde6b58915beb0a09fcc57ed36
  &process_id=5xcvetmo5zm5li73qxnj8qu72e2qrxw8

HTTP/1.1 200 OK

{
    "result": true
}
Внимание! В параметре id ожидается массив идентификаторов записей из очереди событий, а не, например, идентификаторов лидов CRM. То есть, в примере выше, result.events[].ID, а не result.events[].EVENT_DATA.FIELDS.ID.

Обработка ошибок

При создании сложных интеграций, для которых и предназначена усложнённая схема, вполне возможна ситуация, когда возникает конфликт данных различных систем. В этом случает требуется человеческий контроль или использование какого-то другого способа разрешения конфликтов. Чтобы при этом не стопорить процесс и не копить ошибки, некоторые записи о событиях можно оставлять в базе с пометкой об их ошибочности. Для этого используется метод /rest/event.offline.error.

https://myportal.bitrix24.com/rest/event.offline.error
  ?auth=4742845a0000cd7a0000cd5d0000000100000386a97f24a7f515e9ec5e242fed727af4
  &process_id=cal3dm2qg31gb3g8uatca6huqjdtdn6u
  &message_id[]=438d4ec3d329464c4bb9909db4c7a19b

HTTP/1.1 200 OK

{
    "result": true
}

После выставления флага об ошибке помеченные записи перестанут отдаваться приложению при вызове event.offline.get. Перестают отдаваться как сама помеченная запись, так и все последующие срабатывания события с этими данными. Иными словами, изменения этой сущности на стороне Битрикс24 перестанут передаваться в приложение, пока приложение не даст разрешение на передачу. Также, запись отвяжется от текущего процесса, и не будет удалена при вызове event.offline.clear. Если за время обработки были срабатывания события с такими данными, они также передаются приложению, даже если уже были захвачены другим процессом.


Разрешение ошибок

Чтобы снять пометку об ошибке с записи, нужно вычистить ее из базы при помощи event.offline.get с указанием параметра error=1. И, при необходимости, с дополнительным фильтром, если нужно обработать только часть ошибок. Сразу после вызова ошибочные записи будут вычищены из базы (если указать clear=1), либо помечены как обрабатываемые (если указать clear=0). В обоих случаях новые события с такими данными снова начнут регистрироваться и отдаваться приложению.


Простое получение состояния очереди

Иногда может потребоваться считать текущую очередь, не внося изменений в ее состояние, как это делает event.offline.get, и не завися от сложной логики пометки ошибочных событий или раскидывания событий по процессам. Для этого сделан простой списочный метод /rest/event.offline.list:

https://myportal.bitrix24.com/rest/event.offline.list
  ?auth=4742845a0000cd7a0000cd5d0000000100000386a97f24a7f515e9ec5e242fed727af4

HTTP/1.1 200 OK

{
    "result": [
        {
            "ERROR": "0", 
            "EVENT_ADDITIONAL": {
                "user_id": "1"
            }, 
            "EVENT_DATA": {
                "FIELDS": {
                    "ID": 28
                }
            }, 
            "EVENT_NAME": "ONCRMLEADUPDATE", 
            "ID": "60", 
            "MESSAGE_ID": "438d4ec3d329464c4bb9909db4c7a19b", 
            "PROCESS_ID": "", 
            "TIMESTAMP_X": "2018-02-14T15:34:34+02:00"
        }, 
        {
            "ERROR": "0", 
            "EVENT_ADDITIONAL": {
                "user_id": "1"
            }, 
            "EVENT_DATA": {
                "FIELDS": {
                    "ID": 27
                }
            }, 
            "EVENT_NAME": "ONCRMLEADUPDATE", 
            "ID": "65", 
            "MESSAGE_ID": "7bf367ea2e4c9b6a8c3adac4a416627c", 
            "PROCESS_ID": "", 
            "TIMESTAMP_X": "2018-02-14T15:34:55+02:00"
        }
    ]
}


Rest и доступ в сеть

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

Для Битрикс24 необходимо открыть:

  • Исходящие запросы на oauth.bitrix.info (для механизма приложений) и http://www.1c-bitrix.ru (для работы витрины приложений).
  • Входящие запросы от серверов приложения (адреса зависят от конкретных приложений).

Для приложения, если на своем сервере ведётся разработка приложения, необходимо открыть:

  • Исходящие на oauth.bitrix.info.
  • Исходящие запросы на конкретный сервер коробочного Битрикс24.
  • Входящие запросы от серверов mp_actions.*, если приложение использует механизмы событий, роботов или кастомные действия бизнес-процессов.

Текущие IP:

oauth.bitrix.info:

46.235.53.68
176.34.103.175

mp-actions.bitrix.info и mp-actions-us.bitrix.info:

195.208.187.23
35.170.160.36

Примечание: Компания "1С-Битрикс" указанные адреса старается не менять, но теоретически такая смена возможна. Лучше ориентироваться на IP адреса в которые резолвятся указанные доменные имена.

Для администраторов при настройке фаервола - резолв доменного в IP и добавление правила - это не всегда однозначный и корректный кейс. Но другого выхода на данный момент нет.



Рекомендации для разработчиков

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

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

Дополнительные материалы и источники

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

  • Посмотрите видеокурс для разработчиков приложений, в котором от простого к сложному демонстрируется создание готового решения на REST API
  • Мы постоянно проводим вебинары для разработчиков, на которых можно также задать вопросы ведущим. Подключайтесь в онлайн или смотрите записи.
  • Существует отдельный курс по чат-ботам на REST API.
  • Новинки и дополнительные материалы для разработчиков публичных тиражных решений можно почитать в блоге о приложениях
  • Интересные новости, анонсы и полезные материалы мы также раздаем через нашего чатбота "Весёлый лодочник", подключенного к открытой линии. Вы можете подписаться на бота через Битрикс24.Network, Telegram, FB и VK.
  • Существует открытое сообщество разработчиков тиражных решений, в котором можно обменяться опытом или пообщаться с разработчиками Битрикс24.
  • Неофициальный канал Bitrix24Dev в Telegram
  • Статья про создание действий бизнес-процессов в Битрикс24

Вопросы производительности

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

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

Посмотрите вебинар, целиком посвященный этой теме:



Архив с примером кода

Разработка решений для мобильного приложения Битрикс24

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

Смотрите вебинар про разработку таких приложений:



Архив с примером кода

Консоль REST API для разработчиков

При работе с API очень удобно использовать специально созданное бесплатное приложение, которое выводит документацию в вашем портале Битрикс24.

Установив такое приложение, вы будете постоянно иметь "под рукой" актуальную версию REST API.

Приложение позволяет выполнять код, приведённые в доке, копировать его в панель и видоизменять под ваши задачи.