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

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

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

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

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

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

Пример использования bx24.js:

<script>
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>

Дополнительную информацию о bx24.js можно найти в разделе Подключение и использование bx24.js. Учтите, что эта библиотека может использоваться только в рамках приложений, которые открываются во фреймах в пользовательском интерфейсе Битрикс24. Читайте об этом подробнее в разделе про виджеты.

JavaScript библиотека B24JsSDK

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

Это различие требует немного другого подхода к подключению библиотеки. Подробную информацию можно найти в Установка и использование B24JsSDK. Сейчас же приведем пример подключения B24JsSDK в качестве браузерной UMD-библиотеки.

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

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

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

<script type="module">
try
{
    const $logger = B24Js.LoggerBrowser.build('local-app', true);
    const $b24 = await B24Js.initializeB24Frame();
    $b24.setLogger(
        B24Js.LoggerBrowser.build('Core')
    );
    $logger.warn('B24Frame.init');
    const response = await $b24.callMethod(
        'crm.item.add',
        {
            entityTypeId: B24Js.EnumCrmEntityTypeId.deal,
            fields: {
                title: `New Deal`,
                typeId: 'SALE',
                stageId: 'NEW'
            }
        }
    );
    const newDeal = response.getData().result.item;
    $logger.info(
        `${B24Js.Text.getDateForLog()} crm.item.add >>`,
        {
            newId: newDeal.id,
            createdTime: B24Js.Text.toDateTime(newDeal.createdTime).toFormat('HH:mm:ss'),
            fields: newDeal
        }
    );
}
catch( error )
{
    console.error(error);
}
</script>

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

PHP библиотека B24PhpSDK

Для начала использования необходимо установить и подключить B24PhpSDK. Подробную информацию можно найти в Загрузка и использование B24PhpSDK.

Пример использования B24PhpSDK со входящим вебхуком:

declare(strict_types=1);

// подключение базового класса SDK
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();

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

Для использования PHP примеров необходимо установить и подключить CRest SDK. Подробную информацию можно найти в Загрузка и использование CRest PHP SDK.

Пример использования CRest SDK:

// подключение CRest PHP SDK
require_once('crest.php');

// выполнение запроса к REST API
$result = CRest::call(
    'crm.deal.add',
    [
        'fields' => [
            'TITLE' => 'New Deal',
            'TYPE_ID' => 'SALE',
            'STAGE_ID' => 'NEW'
        ]
    ]
);

// обработка ответа от Битрикс24
if ($result['error']) {
        echo 'Error: '.$result['error_description'];
    } else {
        print_r($result['result']);
}