Полный цикл в digital
info@hmarketing.ru
+7 (925) 464-90-60
info@hmarketing.ru +7 (925) 464-90-60

Библиотеки для работы с REST API в Битрикс24

Взаимодействие с REST API строится по средствам http запросов, в самом простом варианте можно использовать Curl, но более правильный метод, выбрать одну из библиотек.

JavaScript библиотека bx24.js

Подробную информацию по библиотеки можно найти на официальном сайте.

Если ваше приложение реализует пользовательский интерфейс внутри Битрикс24, ваш код выводится на специальной странице или использует инструменты встройки, то вы можете воспользоваться возможностями специальной JS-библиотеки bx24.js, для внешних приложений и вебхуков, библиотека использоваться не может. Библиотека имеет ряд приимуществ:

  1. Представляет собой JS SDK для REST, что позволяет обращаться к REST прямо из front-end вашего приложения не погружаясь в реализацию авторизации по OAuth
  2. Предлагает ряд дополнительных функций, для взаимодействия пользовательского интерфейса вашего приложения с интерфейсом Битрикс24. Можно управлять размером фрейма, вызывать стандартные диалоги и т.д.

Подключается библиотека следующим образом:

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

Отправка запроса

Метод BX24.callMethod вызывает указанный метод REST API с заданными параметрам. В качестве параметров метода выступает объект params, представляющий собой ассоциативный массив, преобразуемый в строку POST запроса. Значениями элементов массива могут быть строки или ссылки на DOM-элементы полей формы. Метод BX24.callMethod обязательно должен быть обернут в метод BX24.init:

BX24.callMethod(
// название метода REST API, который будет вызван
String method,
// параметры, передаваемые в метод, должны соответствовать ожидаемым параметрам вызываемого метода
Object params[],
// функция обратного вызова, которая будет выполнена после получения ответа от сервера
Function callback
);

Боевой пример:

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

<script>
    BX24.init(() => {
        BX24.callMethod(
            "crm.deal.add",
            {
                fields: {
                    TITLE: "New Deal",
                    TYPE_ID: "SALE",
                    STAGE_ID: "NEW"
                }
            },
            function (result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.log(result.data());
                }
            }
        );
    })
</script>

Обработчиком результата запроса является функция. Она получает на вход объект ajaxResult, который предоставляет следующие методы:

  • data() возвращает данные ответа метода. Тип возвращаемых данных может быть массивом, объектом или скалярным значением, в зависимости от конкретного метода API
  • error() возвращает объект ошибки, если ошибка присутствует и undefined в противном случае. Объект ошибки содержит поля status и ex, где ex включает в себя error и error_description
  • more() возвращает true, если есть еще данные для загрузки и false в противном случае. Применимо, если метод возвращает список данных
  • total() возвращает общее количество доступных записей. Применимо, если метод возвращает список данных
  • time() возвращает объект с информацией о времени выполнения запроса. Может возвращать undefined, в случае если информация недоступна
  • next(cb: Function) запрашивает следующую страницу данных. Если передана функция cb, она будет использована в качестве обработчика результата для следующего запроса. Возвращает false, если больше нет данных для загрузки, или объект XMLHttpRequest, если запрос был инициирован

Отправка пакета запросов

В некоторых случаях возникает необходимость отправить несколько запросов подряд. Например, при создании необходимых сущностей в процессе инсталляции приложения. Для оптимизации процесса можно использовать пакетное выполнение запросов. Метод BX24.callMethod обязательно должен быть обернут в метод BX24.init:

BX24.callBatch(
// обычный или ассоциативный массив (объект) с запросами. Каждый запрос представляет собой либо массив [имя_метода, параметры_метода], либо объект {method: имя_метода, params: параметры_метода}. В параметрах методов можно использовать макросы, позволяющие получить доступ к результатам предыдущих запросов текущего пакета.
Object или Array,
// функция-обработчик результата пакетного запроса. На вход получит массив или ассоциативный массив (объект) объектов ajaxResult с ключами, соответствующими ключам из пакета запросов
Function callback,
// флаг прерывать исполнение пакета при возникновении ошибки, по умолчанию false (не прерывать)
Boolean
);

Боевой пример:

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

<script>
    BX24.init(() => {
        BX24.callBatch(
            {
                get_deal_add_object: {
                    method: 'crm.deal.add',
                    params: {
                        TITLE: "New Deal Object",
                        TYPE_ID: "SALE",
                        STAGE_ID: "NEW"
                    },
                },
                get_deal_add_array: [
                    'crm.deal.add',
                    {
                        TITLE: "New Deal Array",
                        TYPE_ID: "SALE",
                        STAGE_ID: "NEW"
                    }
                ],
            }, (result) => {
                console.log(result)
            }, true);
    });
</script>

Работа с событиями

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

//добавить событие
BX24.callBind('onCrmDealUpdate', 'https://site/controller/onCrmDealUpdate.php');
//удалить событие
BX24.callUnBind('onCrmDealUpdate', 'https://site/controller/onCrmDealUpdate.php');

JavaScript библиотека B24Js SDK

Подробную информацию по библиотеки можно найти на официальном сайте и в документации.

В отличие от bx24.js, библиотека B24Js SDK может использоваться в любых веб приложениях, как в качестве front-end, так и в качестве back-end на Node.js.

Это различие требует немного другого подхода к подключению библиотеки. Сейчас же приведем пример подключения B24Js SDK в качестве браузерной UMD версии.

Для использования JavaScript примеров необходимо подключить только следующий скрипт:

<script src="https://unpkg.com/@bitrix24/b24jssdk@latest/dist/umd/index.min.js"></script>

После подключения библиотека будет доступна через глобальную переменную B24Js.

Использование со входящими вебхуками

Библиотека также поддерживает работу с входящими вебхуками. Однако, в этом случае её следует использовать на back-end в Node.js. Вызывать REST API с помощью входящего вебхука с front-end небезопасно, так как любой пользователь, открывший такое приложение, сможет увидеть вебхук и использовать его для несанкционированного доступа к Битрикс24 с правами пользователя, создавшего вебхук.

<script src="https://unpkg.com/@bitrix24/b24jssdk@latest/dist/umd/index.min.js"></script>

<script>
    document.addEventListener('DOMContentLoaded', () => {
        try {
            const $b24 = new B24Js.B24Hook({
                b24Url: 'https://b24-tx5unf.bitrix24.ru',
                userId: 1,
                secret: 'zbxuh4sn9nvahw7m',
            })
            let promise = $b24.callMethod(
                "crm.deal.add",
                {
                    fields: {
                        TITLE: "New Deal",
                        TYPE_ID: "SALE",
                        STAGE_ID: "NEW"
                    }
                }
            );
            promise.then(value => {
                console.log(value);
            })
            promise.catch(value => {
                console.log(value);
            })
        } catch (error) {
            console.error(error);
        }
    });
</script>

Пример отправки пакета запросов:

<script src="https://unpkg.com/@bitrix24/b24jssdk@latest/dist/umd/index.min.js"></script>
    
<script>
    document.addEventListener('DOMContentLoaded', () => {
        try {
            const $b24 = new B24Js.B24Hook({
                b24Url: 'https://b24-tx5unf.bitrix24.ru',
                userId: 1,
                secret: 'zbxuh4sn9nvahw7m',
            })
            let promise = $b24.callBatch({
                get_deal_add_object: {
                    method: 'crm.deal.add',
                    params: {
                        TITLE: "New Deal Object",
                        TYPE_ID: "SALE",
                        STAGE_ID: "NEW"
                    },
                },
                get_deal_add_array: [
                    'crm.deal.add',
                    {
                        TITLE: "New Deal Array",
                        TYPE_ID: "SALE",
                        STAGE_ID: "NEW"
                    }
                ],
            }, true);
            promise.then(value => {
                console.log(value);
            })
            promise.catch(value => {
                console.log(value);
            })
        } catch (error) {
            console.error(error);
        }
    });
</script>

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

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

<script src="https://unpkg.com/@bitrix24/b24jssdk@latest/dist/umd/index.min.js"></script>

<script>
    document.addEventListener('DOMContentLoaded', async () => {
        try {
            const $b24 = await B24Js.initializeB24Frame();
            const response = await $b24.callMethod(
                'crm.item.add',
                {
                    entityTypeId: B24Js.EnumCrmEntityTypeId.deal,
                    fields: {
                        title: 'New Deal',
                        typeId: 'SALE',
                        stageId: 'NEW'
                    }
                }
            );
            console.log(response);
        } catch (error) {
            console.error(error);
        }
    });
</script>

PHP библиотека B24Php SDK

Подробную информацию по библиотеки можно найти на официальном сайте.

Для начала использования необходимо установить и подключить B24Php SDK.

Для установки, настоятельно рекомендуем использовать composer:

composer require bitrix24/b24phpsdk

Использование со входящими вебхуками

Чтобы подключить SDK внутри вашего кода, используйте минимально необходимую конструкцию. Когда объект инициирован, его можно использовать для вызова различных методов REST API. В примере ниже переменная $result получит значение идентификатора сделки в результате её создания:

<?php
declare(strict_types=1);
use Bitrix24\SDK\Services\ServiceBuilderFactory;
// следите за правильностью пути к autoload.php он может быть другим, если вы используете другую структуру папок
require_once '../vendor/autoload.php';
$B24 = ServiceBuilderFactory::createServiceBuilderFromWebhook(
    '--сюда надо вставить код вашего вебхука--'
);
$result = $B24->getCRMScope()->deal()->add([
    'TITLE' => 'New Deal',
    'TYPE_ID' => 'SALE',
    'STAGE_ID' => 'NEW'
])->getId();

Если для нужного вам метода нет готовой обёртки в SDK, вы можете использовать универсальный способ вызова методов REST API:

$result = $B24->core->call('crm.deal.add', [
    'TITLE' => 'New Deal',
    'TYPE_ID' => 'SALE',
    'STAGE_ID' => 'NEW'
]);

В этом случае не работает автокомплит кода в IDE и не происходит приведение типов в получаемых данных.

Архив с примером.

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

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

  1. BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID код приложения client_id
  2. BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET ключ приложения client_secret
  3. BITRIX24_PHP_SDK_APPLICATION_SCOPE настройка прав из соответствующих настроек локального приложения в вашем Битрикс24

Код приведенный ниже, предполагает что приложение открывается внутри Битрикс24 либо в качестве основного интерфейса, либо в качестве виджета.

Чтобы подключить SDK внутри вашего кода, используйте минимально необходимую конструкцию. Инициировав объект $B24 вы можете использовать его для вызова различных методов REST API. В примере ниже переменная $result получит значение идентификатора сделки в результате её создания:

<?php
declare(strict_types=1);
use Bitrix24\SDK\Core\Credentials\ApplicationProfile;
use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Symfony\Component\HttpFoundation\Request;
// следите за правильностью пути к autoload.php он может быть другим, если вы используете другую структуру папок
require_once 'vendor/autoload.php';
$appProfile = ApplicationProfile::initFromArray([
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID' => 'put-your-client-id-here',
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET' => 'put-your-client-secret-here',
    'BITRIX24_PHP_SDK_APPLICATION_SCOPE' => 'crm,user_basic'
]);
$B24 = ServiceBuilderFactory::createServiceBuilderFromPlacementRequest(
    Request::createFromGlobals(),
    $appProfile
);
$result = $B24->getCRMScope()->deal()->add([
    'TITLE' => 'New Deal',
    'TYPE_ID' => 'SALE',
    'STAGE_ID' => 'NEW'
])->getId();
Архив с примером.

PHP библиотека CRest SDK

Подробную информацию по библиотеки можно найти на официальном сайте.

Для использования PHP примеров необходимо установить и подключить CRest SDK.

Если в проекте используется класс CRest и кодировка отличается от UTF-8, то необходимо сделать 2 дополнительных действия:

  1. Открыть файлы из архива и изменить их кодировку на необходимую
  2. В файле settings.php объявить константу C_REST_CURRENT_ENCODING. Если проект в кодировке windows-1251 константа выглядеть должна так — define('C_REST_CURRENT_ENCODING','windows-1251');

Вызов REST с использованием входящего вебхука

Укажите URL вебхука:

settings.phpdefine('C_REST_WEB_HOOK_URL','https://xxx.bitrix24.ru/rest/1/douasdqkjxgc3mgc1/');

Вставьте текст примера:

index.phprequire_once('crest.php');
echo '<PRE>';
print_r(CRest::call(
    'crm.lead.add',
    [
        'fields' =>[
            'TITLE' => 'Название лида',
            'NAME' => 'Имя',
            'LAST_NAME' => 'Фамилия',
        ]
    ])
);
echo '</PRE>';

Укажите URL в адресной строке браузера, к примеру, https://mydomain.xxx/index.php чтобы увидеть результат работы примера.

Вызов REST из локального приложения

Настройка ключей, укажите значения параметров client_id и client_secret для авторизации OAuth в файле settings.php, взяв эти значения из карточки локального приложения:

settings.phpdefine('C_REST_CLIENT_ID','app.87816165165.35984727');
define('C_REST_CLIENT_SECRET','g5dlcj3d2772h8g5jhzou907jojage');

Вставьте текст примера:

require_once('crest.php');
echo '<PRE>';
print_r(CRest::call(
    'crm.lead.add',
    [
        'fields' =>[
            'TITLE' => 'Название лида',
            'NAME' => 'Имя',
            'LAST_NAME' => 'Фамилия',
        ]
    ])
);
echo '</PRE>';

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

  1. URL своего приложения https://mydomain.xxx/index.php
  2. URL скрипта установки https://mydomain.xxx/install.php

Вставьте текст примера:

index.phprequire_once('crest.php');
echo '<PRE>';
print_r(CRest::call(
    'crm.lead.add',
    [
        'fields' =>[
            'TITLE' => 'Название лида',
            'NAME' => 'Имя',
            'LAST_NAME' => 'Фамилия',
        ]
    ])
);
echo '</PRE>';

В списке локальных приложений нажмите правой кнопкой мыши на своё локальное приложение и выберите пункт Переустановить. Это нужно, чтобы корректно сработал install.php после того, как вы вставили корректные значения C_REST_CLIENT_ID и C_REST_CLIENT_SECRET.

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

Архив с примером.

Эйч Маркетинг
Заполните форму уже сегодня!
Для начала сотрудничества необходимо заполнить заявку или заказать обратный звонок. В ответ получите коммерческое предложение, которое будет содержать индивидуальную стратегию с учетом требований и поставленных задач
Оставить заявку
Заказать звонок
Работаем по будням с 9:00 до 18:00. Заявки, отправленные в выходные, обрабатываем в первый рабочий день до 12:00.
Спасибо, ваш запрос принят и будет обработан!
Заполните форму уже сегодня!
Для начала сотрудничества необходимо заполнить заявку или заказать обратный звонок. В ответ получите коммерческое предложение, которое будет содержать индивидуальную стратегию с учетом требований и поставленных задач
Работаем по будням с 9:00 до 18:00. Заявки, отправленные в выходные, обрабатываем в первый рабочий день до 12:00.