Заготовка для работы с REST-API Битрикс24 на PHP

25.04.2022 Разработка

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

Было принято решение, написать немного своего кода на php, несколько классов, чтобы было удобно и просто выполнять запросы к REST-API Битрикс24. Ссылка на официальный сайт, с описанием методов https://dev.1c-bitrix.ru/rest_help/

Данное решение написано с вариантом использования «Входящий вебхук», где запросы к API выполняются по схеме представленной ниже:

По сути — это URL запрос, который содержит токен, метод и параметры для запроса, можно ее хоть в браузер вставлять и получать результат. Где в данном случае, в запросе получается список сделок по фильтру: не закрытые и с ID больше 2200. В принципе, если нужно выполнить всего 1 или 2 простых запроса и они не будут меняться, можно использовать CURL — запросы и не усложнять себе жизнь. Если же в планах есть построение сложных интеграций, с выборкой большого количества данных, то можно использовать то, что будет описано ниже. В конце статьи можно будет скачать исходники.

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

Шаг 1 — находим пункт «Разработчикам» в меню или строке поиска, переходим

Шаг 2 — в следующей вкладке выбираем «Другое»

Шаг 3 — в следующей вкладке выбираем «Входящий вебхук»

Шаг 4 — в следующей вкладке получаем ссылку-токен, настраиваем разрешения(права) нажимаем сохранить

Что стоит знать, прежде чем писать интеграции с Битрикс24:

За один запрос к API — Битрикс24 выдает не более 50 результатов и ссылку на следующие 50;
Есть ограничение по количеству запросов к API в секунду.

В примерах к этой статье разберем как быть, чтобы не испытывать сложностей из-за этих ограничений.

Первоначальная структура проекта:

Файл composer.json
Файл index.php
Директория src

—Файл B24.php

Содержимое каждого файла рассмотрим подробно. Забегая вперед, сообщу, что в данной статье не будет рассмотрен сложный роутинг, сейчас главное понять концепцию и начать ее использовать. Запросы к API будут выполняться при помощи GUZZLE, чтобы не писать большие куски кода, в случае c CURL.

Файл composer.json — Будет содержать подключение пакета GUZZLE и инструкции для подключения файлов наших классов из директории src. Его код:

{
 "require": {
        "guzzlehttp/guzzle": "^6.0"
    },
  "autoload": {
    "psr-4": { "": "src/" }
  }
}

Выполняем команду в терминале, в этой директории: composer require

Получаем примерно такой результат:

Search for a package: 
./composer.json has been updated
Running composer update 
Loading composer repositories with package information
Updating dependencies
Lock file operations: 8 installs, 0 updates, 0 removals
  - Locking guzzlehttp/guzzle (6.5.5)
  - Locking guzzlehttp/promises (1.5.1)
  - Locking guzzlehttp/psr7 (1.8.5)
  - Locking psr/http-message (1.0.1)
  - Locking ralouphie/getallheaders (3.0.3)
  - Locking symfony/polyfill-intl-idn (v1.25.0)
  - Locking symfony/polyfill-intl-normalizer (v1.25.0)
  - Locking symfony/polyfill-php72 (v1.25.0)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 8 installs, 0 updates, 0 removals
  - Installing symfony/polyfill-php72 (v1.25.0): Extracting archive
  - Installing symfony/polyfill-intl-normalizer (v1.25.0): Extracting archive
  - Installing symfony/polyfill-intl-idn (v1.25.0): Extracting archive
  - Installing ralouphie/getallheaders (3.0.3): Extracting archive
  - Installing psr/http-message (1.0.1): Extracting archive
  - Installing guzzlehttp/psr7 (1.8.5): Extracting archive
  - Installing guzzlehttp/promises (1.5.1): Extracting archive
  - Installing guzzlehttp/guzzle (6.5.5): Extracting archive
4 package suggestions were added by new dependencies, use `composer suggest` to see details.
Generating autoload files
5 packages you are using are looking for funding.
Use the `composer fund` command to find out more!

Необходимые пакеты и зависимости загрузились, а также создались дополнительные файлы(composer.lock) и директория(vendor), куда все это загрузилось. Если на данном этапе у Вас этого не произошло, то нужно проверить установлен ли composer, это можно сделать командой: composer -v

Файл index.php — на данном этапе точка входа в приложение. Пока у нас нет класса B24, то описывать его не имеет смысла, вернемся к этому чуть позже. Сейчас его можно просто создать, с открывающим тегом

Файл B24.php — Это будет основной класс, где будут описаны методы для работы с REST-API. В этом классе основных два метода, oneMethod и listMethod, первый для выполнения простых запросов, например записать что-то в лид или сделку, отправить сообщение в чат, получить конкретную сделку и тд, а второй чтобы получать массивы больших данных, например сделки по фильтру, все сделки, лиды, элементы списка и тд. Код файла:

<?php

use GuzzleHttp\Client;

/**
 *
 * Простой класс для работы с REST-API Битрикс24
 *
 */

class B24 extends Client
{

    protected $conftoken = null;
    public $arrToallDealList = array();
    protected $reqMethod = '';
    protected $reqParam = array();


    /**
     * Установка URL-адреса токена во время инициализации объекта,
     * для последующего использования, также вызываем родительский конструктор
     */

    function __construct($token) {
        parent::__construct();
        $this->conftoken = $token;
    }



    /**
     *
     * Выполнение простого метода, не списочного
     * @param array $params Параметры для запроса
     * @param string $method Название метода
     * @return array Ассоциативный массив
     * Пример использования : $obj->oneMethod(array('ID'=>245),'crm.lead.get');
     *
     */

    public function oneMethod(array $params, string $method): mixed
    {
        $init = $this->conftoken;
        if($init) {
            $response = $this->request('POST', '$this->conftoken/$method.json',['json'=>$params],['http_errors' => false]);
            return json_decode($response->getBody(),true);
        }else{
            return false;
        }
    }


    /**
     *
     * Заполнение массива для метода listMethod()
     * если результат запроса составляет более 50 элементов.
     * Вызывается методом listMethod()
     * $arrtoalldeallist свойство заполняется в цикле.
     * Происходит проверка на наличие ключа 'next' в $arrResult
     * Если такой ключ есть, то вызывается метод listMethod.
     * Ему передаются параметры, которые хранятся в свойствах $reqmethod и $reqparam
     * В противном случае возвращается свойство arrToallDealList
     * Между запросами существует интервал в 1 секунду
     * @param array $arrResult Результат метода listMethod()
     * @return array Ассоциативный массив
     *
     */

    public function arrCombine(array $arrResult): array
    {
        foreach($arrResult['result'] as $key => $value) {
            $this->arrToallDealList[] = $value;
        }
        if(array_key_exists('next', $arrResult)) {
            sleep(1);
            $this->listMethod($this->reqParam,$this->reqMethod);
        }
        return $this->arrToallDealList;
    }

    /**
     *
     * Для выполнения запросов к списочным методам.
     * Полученный результат отправляется в метод arrCombine()
     * Как параметр
     * Метод вернет все результаты в одном массиве
     * Сохраняет параметры запроса в свойстве $reqParam
     * Сохраняет имя метода в свойстве $reqMethod
     * @param array $params Параметры для запроса
     * @param string $method Метод для запроса
     * @return bool|array Ассоциативный массив с всеми результатами
     * Пример использования: $obj->listMethod(array('SELECT' => array('ID', 'TITLE'),'FILTER' => array('>OPPORTUNITY' => '50000')),'crm.deal.list');
     *
     */

    public function listMethod(array $params,string $method): bool|array
    {
        $init = $this->conftoken;
        if($init) {
            $response = $this->request('POST', '$this->conftoken/$method.json',['json'=>$params],['http_errors' => false]);
            $result = json_decode($response->getBody(),true);

            if(array_key_exists('next', $result)) {

                $params['start'] = $result['next'];
                $this->reqParam = $params;
                $this->reqMethod = $method;

            }
            return $this->arrCombine($result);
        }else {
            return false;
        }
    }

}

!!! ВАЖНО !!! Данный код написан на PHP 8, для использования его на более ранних версиях, необходимо убрать у методов описание возвращаемых результатов «: bool|array»

После создания этого файла, запускаем команду в консоле, в корне проекта composer dump-autoload -o.

После выполнения этой команды, увидим примерно такой результат:

Generating optimized autoload files
Generated optimized autoload files containing 96 classes

Я оставил комментарии в коде класса, в том числе примеры использования вызовов методом, но все же внесу несколько объяснений. При создание объекта от класса B24, в конструктор необходимо передать ссылку, с токеном, которую мы получим в системе Битрикс24, переданное значение сохраняется в свойстве conftoken, затем проверяется в каждом методе. С методом oneMethod — все просто, происходит выполнение обычного запроса, не предполагающего получение результата более 50 элементов. Сложнее становится с методом listMethod, в нем также сначала выполняется простой запрос, а затем проверяется ответ, на содержание в нем ключа ‘next’, что будет означать, что есть еще данные. Для того чтобы формировать новые запросы, нужно сохранить куда-то данные из выполненного запроса, поэтому они сохраняются в свойства объекта $reqMethod и $reqParam, а также к ним добавляется значение start, которое копируется из получаемого значения next, затем управление передается служебному методу arrCombine, который наполняет свойство объекта arrToallDealList, затем опять передает управление методу listMethod и так по кругу, пока не произойдет выборка всех элементов, можно сказать, что это работает как рекурсивная функция, в конечном итоге мы получим многомерный массив, даже если там несколько тысяч элементов, а уже с ним можно делать все что угодно. Для стартовой работы из php — этого достаточно, конечно Вы можете дополнить этот класс, при необходимости.

Примеры использования

Пример 1 — выполнение простого запроса, получить сделку по ID:

Теперь самое время изменить написать содержимое файла index.php, его код, согласно примеру:

<?php
set_include_path(__DIR__);
require 'vendor/autoload.php';

// создаем объект от класса B24, в конструктор передаем ссылку-токен
// в Вашем случае будет другая ссылка с токеном
$obj = new B24('https://my_domain.bitrix24.ru/rest/3/jsudurewurewfs/');

// в переменную $result сохраняем результат выполнения обычного метода
$result = $obj->oneMethod(array('ID'=> 4043),'crm.deal.get');

// распечатываем результат
echo '<pre>';
print_r($result);
echo '</pre>';

Получаем примерно такой результат:

В итоге мы получили ассоциативный массив, со всеми данными по конкретной сделке.

Чтобы получить все сделки по фильтру, используем списочный метод, пример кода:

<?php
set_include_path(__DIR__);
require 'vendor/autoload.php';

// создаем объект от класса B24, в конструктор передаем ссылку-токен
// в Вашем случае будет другая ссылка с токеном
$obj = new B24('https://my_domain.bitrix24.ru/rest/3/jsudurewurewfs/');

// формируем массив с параметрами для запроса
$arrToReq = array(
    'FILTER' => array(
        'CLOSED' => 'N',
        '>ID' => 2000,
    ),
    'SELECT' => array(
        'ID', 'STAGE_ID', 'PROBABILITY', 'OPPORTUNITY', 'CURRENCY_ID'
    ),

);
// в переменную $result сохраняем результат выполнения списочного метода
$result = $obj->listMethod($arrToReq,'crm.deal.list');

// распечатываем результат
echo '<pre>';
print_r($result);
echo '</pre>';

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

Результат в моем случае, я его чуть сократил, но в итоге было получено 490 элементов по фильтру

Списочный метод, для получения результатов более 50, работает, но имеет интересный эффект, если он будет вызван несколько раз, то в итоге мы получим общий массив, включающий в себя и предыдущие результаты, что не всегда нужно, тут два варианта действий: создать новый объект и вызвать у него списочный метод или добавить еще один метод и вызывать его, при повторном вызове списочного метода, для очистки свойства arrToallDealList. Добавим в файл B24.php, фрагмент кода:

    /**
     * Метод очистки свойства $arrToallDealList,
     * Необходимо вызывать, если у создаваемого объекта
     * списочный метод вызывается несколько раз.
     */

    public function cleanArr()
    {
         unset($this->arrToallDealList);

    }

Всем успехов в разработке и интеграциях.

По ссылкам ниже можно скачать файлы. Для разворачивания, необходимо будет запустить команду composer require и потом команду composer dump-autoload -o

Скачать исходники

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

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

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

Теги:pbp Битрикс24

Заготовка для работы с REST-API Битрикс24 на PHP

Примеры использования

Добавить комментарий Отменить ответ

Категории

Свежие записи

Свежие комментарии

Заготовка для работы с REST-API Битрикс24 на PHP

Примеры использования

Добавить комментарий Отменить ответ

Категории

Свежие записи

Свежие комментарии

Вам также может понравиться

Чтение excel файла в PHP

Создание excel в PHP

Приведение к числу c плавающей точкой строки в PHP