Skip to content

Обертка на PHP7+ для работы с REST API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов к API и логированием в файл.

License

Notifications You must be signed in to change notification settings

Leonid74/bitrix24-api-php

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

20 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bitrix24 API PHP Wrapper

Bitrix24 logo

Latest Stable Version Total Downloads GitHub stars GitHub forks GitHub watchers License

Обертка на PHP7+ для работы с REST API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов и логированием в файл.

Разработчики на JavaScript могут воспользоваться классом-оберткой andrey-tech/bx24-wrapper-js.

Содержание

Требования

  • PHP >= 7.0;
  • класс HTTP >= 3.0 - НТТР(S) клиент с троттлингом запросов, поддержкой маркера BOM в теле сообщения формата JSON и выводом отладочной информации о запросах и ответах в STDOUT;
  • класс DebugLogger >= 2.0 - логгер, сохраняющий отладочную информацию в файл вместе с данными об объеме используемой оперативной памяти и прошедшем времени;
  • произвольный автозагрузчик классов, реализующий стандарт PSR-4, необходимый в том случае, если не используется Composer.

Установка

Установка через composer:

$ composer require andrey-tech/bitrix24-api-php:"^1.6"

или добавить

"andrey-tech/bitrix24-api-php": "^1.6"

в секцию require файла composer.json.

Класс Bitrix24API

Для работы с REST API Битрикс24 используется класс \App\Bitrix24\Bitrix24API.
При возникновении ошибок выбрасывается исключение класса \App\Bitrix24\Bitrix24APIException.
В настоящее время в классе реализованы методы для работы со следующими сущностями Битрикс24:

Базовые методы класса

Базовые методы находятся в классе \App\Bitrix24\Bitrix24API:

  • __construct(string $webhookURL) Конструктор класса.
  • request(string $function, array $params = []) :?array Отправляет запрос в API.
  • getList(string $function, array $params = []) :\Generator Загружает все сущности заданного типа.
  • fetchList(string $function, array $params = []) :\Generator Загружает все сущности быстрым методом.
  • batchRequest(array $commands, $halt = true) :array Отправляет пакет запросов в API.
  • buildCommands(string $function, array $items) :array Создает массив команд для пакетного запроса.
  • buildCommand(string $function, array $params) :string Возвращает команду для пакетного запроса.
  • getLastResponse() :?array Возвращает последний ответ от API.
  • setLogger($logger) Устанавливает объект класса, выполняющего логирование отладочной информации в файл.

Параметры методов:

  • $webhookURL - URL входящего вебхука;
  • $function - имя метода (функции) запроса;
  • $params - параметры запроса;
  • $commands - пакет команд;
  • $items - массив полей запросов;
  • $halt - прерывать последовательность запросов в случае ошибки;
  • $logger - объект класса, реализующего интерфейс \App\DebugLogger\DebugLoggerInterface.

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

Дополнительные параметры настройки доступны через публичные статические и нестатические свойства класса \App\Bitrix24\Bitrix24API:

Нестатическое свойство По умолчанию Описание
$batchSize 50 Устанавливает количество команд в одном пакете запросов (batch)
$logger null Хранит объект класса \App\DebugLogger\DebugLogger, выполняющего логирование запросов и ответов к API в файл. Если null, то логирование не выполняется.
$http \App\HTTP\HTTP Хранит объект класса \App\HTTP\HTTP, отправляющего запросы к API
Статическое свойство По умолчанию Описание
$WITH_CONTACTS 'CONTACTS' Имя поля для массива возвращаемых связанных сущностей типа контакт
$WITH_COMPANIES 'COMPANIES' Имя поля для массива возвращаемых связанных сущностей типа компания
$WITH_PRODUCTS 'PRODUCTS' Имя поля для массива возвращаемых связанных сущностей типа товар

Методы для работы с сущностями Битрикс24

Методы работы со сделками

Методы для работы со сделками находятся в трейте \App\Bitrix24\Deal:

  • getDeal($dealId, array $with = []) :array Возвращает сделку по ее ID.
  • addDeal(array $fields = [], array $params = []) :int Добавляет сделку и возвращает ее ID.
  • updateDeal($dealId, array $fields = [], array $params = []) :int Обновляет сделку и возвращает ее ID.
  • deleteDeal($dealId) :int Удаляет сделку и возвращает ее ID.
  • getDealList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все сделки с возможностью фильтрации, сортировки и выборки полей.
  • fetchDealList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все сделки с возможностью фильтрации, сортировки и выборки полей.
    Реализует быстрый метод загрузки при работе с большими объемами данных.
  • addDeals(array $deals = [], array $params = []) :array
    Пакетно добавляет сделки со связанными товарными позициями, возвращает массив ID сделок.
  • updateDeals(array $deals = [], array $params = []) :array
    Пакетно обновляет сделки со связанными товарными позициями, возвращает массив ID сделок.
  • deleteDeals(array $dealIds = []) :array Пакетно удаляет сделки, возвращает массив ID сделок.
  • setDealFile($dealId, $userFieldId, string $fileName, string $fileContent, bool $isBase64FileData = true) :int
    Устанавливает файл в НЕ множественное пользовательское поле типа файл (файл нельзя удалить) и возвращает ID сделки.
  • setDealFiles($dealId, $userFieldId, array $files = [], bool $isBase64FileData = true) :int
    Устанавливает файлы во множественное пользовательское поле типа файл (файлы можно удалить) и возвращает ID сделки.
  • getDealContactItems($dealId) :array Возвращает массив параметров контактов, связанных со сделкой.
  • setDealContactItems($dealId, array $contacts) :array Устанавливает контакты, связанные со сделкой.
  • setDealProductRows($dealId, array $products) :array Устанавливает товарные позиции, связанные со сделкой.
  • getDealProductRows($dealId) :array Возвращает массив параметров товарных позиций, связанных со сделкой.
  • getDealFields() :array Возвращает описание полей сделки, в том числе пользовательских.

Параметры методов:

  • $dealId - ID сделки;
  • $dealIds - массив ID сделок;
  • $with - имена связанных сущностей, возвращаемых вместе со сделкой:
    • \App\Bitrix24\Bitrix24API::$WITH_CONTACTS - контакты (возвращаются в виде массива в поле с именем, заданным публичным статическим свойством Bitrix24API::$WITH_CONTACTS);
    • \App\Bitrix24\Bitrix24API::$WITH_PRODUCTS - товарные позиции (возвращаются в виде массива в поле с именем, заданным публичным статическим свойством Bitrix24API::$PRODUCTS);
  • $fields - набор полей сделки;
  • $params - набор параметров сделки;
  • $filter - параметры фильтрации;
  • $order - параметры сортировки;
  • $select - параметры выборки полей;
  • $userFieldId ID НЕ множественного пользовательского поля в сделке ('UF_CRM_XXXXXXXXXX');
  • $files - массив параметров файлов ([ [ < Имя файла >, < RAW данные файла > ], ... ]) (пустой массив для удаления всех файлов);
  • $isBase64FileData - RAW данные файла закодированы в BASE64?;
  • $contacts - массив параметров контактов;
  • $products - массив параметров товарных позиций.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Добавляем новую сделку
    $dealId = $bx24->addDeal([
        'TITLE'      => 'Новая сделка №1',
        'COMPANY_ID' => 6,
        'CONTACT_ID' => 312
    ]);
    print_r($dealId);

    // Устанавливаем набор связанных контактов
    $bx24->setDealContactItems($dealId, [
        [ 'CONTACT_ID' => 313 ],
        [ 'CONTACT_ID' => 454 ]
    ]);

    // Устанавливаем набор связанных товарных позиций
    $bx24->setDealProductRows($dealId, [
        [ 'PRODUCT_ID' => 1689, 'PRICE' => 1500.00, 'QUANTITY' => 2 ],
        [ 'PRODUCT_ID' => 1860, 'PRICE' => 500.00, 'QUANTITY' => 15 ]
    ]);

    // Обновляем существующую сделку
    $bx24->updateDeal($dealId, [
        'TITLE' => 'Новая сделка №12'
    ]);


    // При необходимости, изменяем значение по умолчанию 'PRODUCTS' на '_PRODUCTS' для имени поля
    // со списком товарных позиций, возвращаемых вместе со сделкой
    Bitrix24API::$WITH_PRODUCTS = '_PRODUCTS';

    // Загружаем сделку по ID вместе со связанными товарами и контактами одним запросом
    $deal = $bx24->getDeal($dealId, [ Bitrix24API::$WITH_PRODUCTS, Bitrix24API::$WITH_CONTACTS ]);
    print_r($deal);

    // Удаляем существующую сделку
    $bx24->deleteDeal($dealId);

    // Загружаем все сделки используя быстрый метод при работе с большими объемами данных
    $generator = $bx24->fetchDealList();
    foreach ($generator as $deals) {
        foreach($deals as $deal) {
            print_r($deal);
        }
    }

    // Пакетно добавляем сделки вместе с товарными позициями
    $dealIds = $bx24->addDeals([
        [
            'TITLE' => 'Новая сделка №1121',
            'COMPANY_ID' => 6,
            'CONTACT_ID' => 312,
            'PRODUCTS' => [
                [ "PRODUCT_ID" => 27, "PRICE" => 100.00, "QUANTITY" => 11 ],
            ]

        ],
        [
            'TITLE' => 'Новая сделка №1122',
            'COMPANY_ID' => 6,
            'PRODUCTS' => [
                [ "PRODUCT_ID" => 28, "PRICE" => 200.00, "QUANTITY" => 22 ],
                [ "PRODUCT_ID" => 27, "PRICE" => 200.00, "QUANTITY" => 11 ],
            ]
        ]
    ]);
    print_r($dealIds);

    // Пакетно удаляем сделки
    $bx24->deleteDeals($dealIds);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы для работы с контактами

Методы для работы с контактами находятся в трейте \App\Bitrix24\Contact:

  • getContact($contactId, array $with = []) :array Возвращает контакт по его ID.
  • addContact(array $fields = [], array $params = []) :int Добавляет контакт и возвращает его ID.
  • updateContact($contactId, array $fields = [], array $params = []) :int Обновляет контакт и возвращает его ID.
  • deleteContact($contactId) :int Удаляет контакт и возвращает его ID.
  • getContactList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все контакты с возможностью фильтрации, сортировки и выборки полей.
  • fetchContactList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все контакты с возможностью фильтрации, сортировки и выборки полей.
    Реализует быстрый метод загрузки при работе с большими объемами данных.
  • addContacts(array $contacts = [], array $params = []) :array Пакетно добавляет контакты.
  • updateContacts(array $contacts = [], array $params = []) :array Пакетно обновляет контакты.
  • deleteContacts(array $contactIds = []) :array Пакетно удаляет контакты.
  • getContactCompanyItems($contactId) :array Возвращает компании, связанные с контактом по ID.
  • setContactCompanyItems($contactId, array $companies) :array Устанавливает компании, связанные с контактом по ID.
  • getContactFields() :array Возвращает описание полей контакта.

Параметры методов:

  • $contaxctId - ID контакта;
  • $contactIds - массив ID сделок;
  • $with - имена связанных сущностей, возвращаемых вместе с контактом:
    • \App\Bitrix24\Bitrix24API::$WITH_COMPANIES - компании (возвращаются в виде массива в поле с именем, заданным публичным статическим свойством Bitrix24API::$WITH_COMPANIES);
  • $fields - набор полей сделки;
  • $params - набор параметров сделки;
  • $filter - параметры фильтрации;
  • $order - параметры сортировки;
  • $select - параметры выборки полей;
  • $contacts - массив параметров контактов;
  • $companies - массив параметров компаний.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Добавляем новый контакт
    $contactId = $bx24->addContact([
        'NAME'        => 'Иван',
        'COMPANY_ID'  => 332,
        'SECOND_NAME' => 'Васильевич',
        'LAST_NAME'   => 'Петров'
    ]);
    print_r($contactId);

    // Устанавливаем набор связанных компаний
    $bx24->setContactCompanyItems($contactId, [
        [ 'COMPANY_ID' => 8483 ],
        [ 'CONPANY_ID' => 4094 ]
    ]);

    // Обновляем существующий контакт
    $bx24->updateContact($contactId, [
        'NAME' => 'Фёдор'
    ]);

    // Загружаем контакт по ID вместе со связанными компаниями
    $contact = $bx24->getContact($contactId, [ Bitrix24API::$WITH_COMPANIES ]);
    print_r($contact);

    // Удаляем существующий контакт
    $bx24->deleteContact($contactId);

    // Загружаем все контакты используя быстрый метод при работе с большими объемами данных
    $generator = $bx24->fetchContactList();
    foreach ($generator as $contacts) {
        foreach($contacts as $contact) {
            print_r($contact);
        }
    }

    // Пакетно добавляем контакты
    $contactIds = $bx24->addContacts([
        [
            'NAME'        => 'Владимир',
            'COMPANY_ID'  => 3322,
            'SECOND_NAME' => 'Вадимович',
            'LAST_NAME'   => 'Владимиров'
        ],
        [
            'NAME'        => 'Андрей',
            'COMPANY_ID'  => 1332,
            'SECOND_NAME' => 'Васильевич',
            'LAST_NAME'   => 'Иванов'
        ]
    ]);
    print_r($contactIds);

    // Пакетно удаляем контакты
    $bx24->deleteContacts($contactIds);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы для работы с компаниями

Методы для работы с компаниями находятся в трейте \App\Bitrix24\Company:

  • getCompany($companyId, array $with = []) Возвращает компанию по ID.
  • addCompany(array $fields = [], array $params = []) :int Добавляет компанию и возвращает ее ID.
  • updateCompany($companyId, array $fields = [], array $params = []) :int Обновляет компанию и возвращает ее ID.
  • deleteCompany($companyId) :int Удаляет компанию и возвращает ее ID.
  • getCompanyList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все компании с возможностью фильтрации, сортировки и выборки полей.
  • fetchCompanyList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все компании с возможностью фильтрации, сортировки и выборки полей.
    Реализует быстрый метод загрузки при работе с большими объемами данных.
  • addCompanies(array $companies = [], array $params = []) :array Пакетно добавляет компании.
  • updateCompanies(array $companies = [], array $params = []) :array Пакетно обновляет компании.
  • deleteCompanies(array $companyIds = []) :array Пакетно удаляет компании.
  • getCompanyContactItems($companyId) :array Возвращает контакты, связанные с компанией.
  • setCompanyContactItems($companyId, array $contacts) :array Устанавливает контакты, связанные с компанией.

Параметры методов:

  • $companyId - ID компании;
  • $companyIds - массив ID компаний;
  • $with - имена связанных сущностей, возвращаемых вместе с компанией:
    • \App\Bitrix24\Bitrix24API::$WITH_CONTACTS - контакты (возвращаются в виде массива в поле с именем, заданным публичным статическим свойством Bitrix24API::$WITH_CONTACTS);
  • $filter - параметры фильтрации;
  • $order - параметры сортировки;
  • $select - параметры выборки полей;
  • $contacts - массив параметров контактов;
  • $companies - массив параметров компаний.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Добавляем новую компанию
    $companyId = $bx24->addCompany([
        'TITLE' => 'OOO Рога и Копыта'
    ]);
    print_r($companyId);

    // Устанавливаем набор связанных контактов
    $bx24->setCompanyContactItems($companyId, [
        [ 'CONTACT_ID' => 4838 ],
        [ 'CONTACT_ID' => 8583 ]
    ]);

    // Обновляем существующую компанию
    $bx24->updateCompany($companyId, [
        'TITLE' => 'ИП Рога и Копыта'
    ]);

    // Загружаем компанию по ID вместе со связанными контактами
    $company = $bx24->getCompany($companyId, [ Bitrix24API::$WITH_CONTACTS ]);
    print_r($company);

    // Удаляем существующую компанию
    $bx24->deleteCompany($companyId);

    // Загружаем все компании используя быстрый метод при работе с большими объемами данных
    $generator = $bx24->fetchCompanyList();
    foreach ($generator as $companies) {
        foreach($companies as $company) {
            print_r($company);
        }
    }

    // Пакетно добавляем компании
    $companyIds = $bx24->addCompanies([
        [ 'TITLE' => 'ПАО Абракадабра' ],
        [ 'TITLE' => 'ЗАО Моя компания' ]
    ]);
    print_r($companyIds);

    // Пакетно удаляем компании
    $bx24->deleteCompanies($companyIds);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы для работы с каталогами

Методы для работы с товарными каталогами находятся в трейте \App\Bitrix24\Catalog:

  • getCatalogList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все каталоги с возможностью фильтрации, сортировки и выборки полей.
  • fetchCatalogList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все каталоги с возможностью фильтрации, сортировки и выборки полей.
    Реализует быстрый метод загрузки при работе с большими объемами данных.
  • getCatalogFields() :array Возвращает описание полей каталога товаров.

Параметры методов:

  • $filter - параметры фильтрации;
  • $order - параметры сортировки;
  • $select - параметры выборки полей.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Загружаем все товарные каталоги используя быстрый метод при работе с большими объемами данных
    $generator = $bx24->fetchCatalogList();
    foreach ($generator as $catalogs) {
        foreach($catalogs as $catalog) {
            print_r($catalog);
        }
    }

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы для работы с товарами

Методы для работы с товарами находятся в трейте \App\Bitrix24\Product:

  • getProduct($productId) :array Возвращает товар по ID.
  • addProduct(array $fields = []) :int Добавляет товар и возвращает его ID.
  • updateProduct($productId, array $fields = []) :int Обовляет товар и возвращает его ID.
  • deleteProduct($productId) :int Удаляет товар и возвращает его ID.
  • getProductList(array $filter = [], array $select = [ '*', 'PROPERTY_*' ], array $order = []) :\Generator
    Загружает все товары с возможностью фильтрации, сортировки и выборки полей.
  • fetchProductList(array $filter = [], array $select = [ '*', 'PROPERTY_*' ], array $order = []) :\Generator
    Загружает все товары с возможностью фильтрации, сортировки и выборки полей.
    Реализует быстрый метод загрузки при работе с большими объемами данных.
  • addProducts(array $products = []) :array Пакетно добавляет товары.
  • updateProducts(array $products = []) :array Пакетно обновляет товары.
  • deleteProducts(array $productIds = []) :array Пакетно удаляет товары.
  • getProductFields() :array Возвращает описание полей товара, в том числе пользовательских.

Параметры методов:

  • $productId - ID товара.
  • $productIds - массив ID товаров.
  • $fields - набор полей товара.
  • $filter - параметры фильтрации;
  • $select - параметры выборки полей;
  • $order - параметры сортировки.
  • $products - массив наборов полей товара.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Получаем товар по его ID
    $product = $bx24->getProduct(2396);
    print_r($product);

    // Обновляем товар
    $bx24->updateProduct(2396, [
        "PRICE" => 4900
    ]);

    // Удаляем товар
    $bx24->deleteProduct(2396);

    // Загружаем все товары c фильтрацией по полю SECTION_ID
    $generator = $bx24->fetchProductList([ 'SECTION_ID' => 13 ]);
    foreach ($generator as $users) {
        foreach($users as $user) {
            print_r($user);
        }
    }
       
    // Пакетно обновляем товары
    $bx24->updateProducts([
        [   
            "ID"          => 27,
            "NAME"        => "Тестовый товар 11",
            "CURRENCY_ID" => "RUB",
            "PRICE"       => 4900,
            "SORT"        => 500,
            "SECTION_ID"  => 13
        ],
        [ 
            "ID"          => 28,
            "NAME"        => "Тестовый товар 12",
            "CURRENCY_ID" => "RUB",
            "PRICE"       => 900,
            "SORT"        => 100,
            "SECTION_ID"  => 13
        ],
        [
            "ID"          => 29,
            "NAME"        => "Тестовый товар 13",
            "CURRENCY_ID" => "RUB",
            "PRICE"       => 2900,
            "SORT"        => 300,
            "SECTION_ID"  => 13
        ]
    ]);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы работы с разделами товаров

Методы для работы с разделами товаров находятся в трейте \App\Bitrix24\ProductSection:

  • getProductSection($productSectionId) :array Возвращает раздел товаров по ID.
  • addProductSection(array $fields = []) :int Добавляет раздел товаров и возвращает его ID.
  • updateProductSection($productSectionId, array $fields = []): int Обновляет раздел товаров и возвращает его ID.
  • deleteProductSection($productSectionId) :int Удаляет раздел товаров и возвращает его ID.
  • getProductSectionList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все разделы товаров с возможностью фильтрации, сортировки и выборки полей.
  • fetchProductSectionList(array $filter = [], array $select = [], array $order = []) :\Generator
    Загружает все разделы товаров с возможностью фильтрации, сортировки и выборки полей. Реализует быстрый метод загрузки при работе с большими объемами данных.
  • addProductSections(array $productSections = []) :array Пакетно добавляет разделы товаров.
  • updateProductSections(array $productSections = []) :array Пакетно обновляет разделы товаров.
  • deleteProducts(array $productSectionIds = []) :array Пакетно удаляет разделы товаров.
  • getProductSectionFields() :array Возвращает описание полей раздела товара.

Параметры методов:

  • $productSectionId - ID раздела товаров;
  • $productSectionIds - массив ID разделов товаров;
  • $fields - набор полей раздела товаров;
  • $filter - параметры фильтрации;
  • $select - параметры выборки полей;
  • $order - параметры сортировки.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Получаем раздел товаров по его ID
    $productSection = $bx24->getProductSection(16);
    print_r($productSection);

    // Обновляем раздел товаров
    $bx24->updateProductSection(16, [
        'NAME' => 'Раздел товаров 1'
    ]);

    // Удаляем раздел товаров
    $bx24->deleteProductSection(16);

    // Загружаем все разделы товаров c фильтрацией по полю CATALOG_ID
    $generator = $bx24->fetchProductSectionList([ 'CATALOG_ID' => 2 ]);
    foreach ($generator as $productSections) {
        foreach($productSections as $productSection) {
            print_r($productSection);
        }
    }
      
    // Пакетно добавляем разделы товаров
    $productSectionIds = $bx24->addProductSections([
        [   
            "NAME"       => "Раздел товаров 3",
            'CATALOG_ID' => 2
        ],
        [   
            "NAME"       => "Раздел товаров 4",
            'CATALOG_ID' => 2
        ]
    ]);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы работы с товарными позициями

Методы для работы с товарными позициями находятся в трейте \App\Bitrix24\ProductRow:

  • getProductRowFields() :array Возвращает описание полей товарных позиций.

Методы для работы с пользователями

Методы для работы с пользователями находятся в трейте \App\Bitrix24\User:

  • getUser($userId) ?:array Возвращает пользователя по ID.
  • getUsers(array $filter = [], string $order = 'ASC', string $sort = '', bool $adminMode = false) :\Generator
    Загружает всех пользователей с возможностью фильтрации, сортировки и выборки полей.
  • getUserFields() :array Возвращает описание полей пользователя.

Параметры методов:

  • $userId - ID пользователя;
  • $filter - параметры фильтрации;
  • $order - направление сортировки (ASC|DESC);
  • $sort - поле, по которому сортируются результаты;
  • $select - параметры выборки полей;
  • $adminMode - включает режим администратора для получения данных о любых пользователях.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Получаем пользователя по ID
    $user = $bx24->getUser(34782);
    print_r($user);

    // Получаем всех пользователей типа сотрудник с сортировкой по имени
    $generator = $bx24->getUsers(
        [ 'USER_TYPE' => 'employee' ],
        $order = 'ASC',
        $sort = 'NAME' 
    );
    foreach ($generator as $users) {
        foreach($users as $user) {
            print_r($user);
        }
    }

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы работы с задачами

Методы для работы с задачами находятся в трейте \App\Bitrix24\Task:

  • getTask($taskId, array $select = []) :?array Возвращает задачу по ID.
  • addTask(array $fields = []) :int Добавляет новую задачу.
  • addTasks(array $tasks = []) :array Пакетно добавляет задачи.
  • getTaskFields() :array Возвращает описание полей задачи.

Параметры методов:

  • $taskId - ID задачи;
  • $select - параметры выборки полей;
  • $fields - набор полей задачи;
  • $tasks - массив наборов полей задач.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Получаем задачу по ID
    $task = $bx24->getTask(4325);
    print_r($task);

    // Создаем новую задачу
    $taskId = $bx24->addTask([
        'TITLE'           => 'Новая задача №123', // Название задачи
        'DESCRIPTION'     => 'Описание задачи', // Описание задачи
        'RESPONSIBLE_ID'  => 43242, // ID ответственного пользователя
        'UF_CRM_TASK'     => [ 'D_' . 38492 ], // Привязка задачи к сделке ('D_' - сущность сделка, 38492 - ID сделки)
        'START_DATE_PLAN' => '09.08.2005', // Плановая дата начала.
        'END_DATE_PLAN'   => '09.09.2005', // Плановая дата завершения
        'DEADLINE'        => '2005-09-09T18:31:42+03:30' // Крайний срок
    ]);
    print_r($taskId);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы для работы с делами

Методы для работы с делами (активностями) находятся в трейте \App\Bitrix24\Activity:

  • getActivity($activityId) :?array Возвращает дело по ID.
  • addActivity(array $fields = []) :int Создает новое дело и возвращает его ID.
  • addActivities(array $activities = []) :array Пакетно создает дела.
  • getActivityFields() :array Возвращает описание полей дела.

Параметры методов:

  • $activityId - ID дела;
  • $fields - набор полей дела;
  • $activities - массив наборов полей дел.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Добавляем новое дело типа письмо
    $activityId = $bx24->addActivity([
        'SUBJECT'          => 'Заголовок письма', // Email subject
        'DESCRIPTION'      => 'Описание активности', // Email body
        'DESCRIPTION_TYPE' => 2, // Тип тела email: 1- Plain text, 2 - bbCode, 3 - HTML (crm.enum.contenttype)
        'COMPLETED'        => 'N', // Флаг немедленной отправки: Y|N
        'DIRECTION'        => 2, // Направление: 1 - входящее, 2 - исходящее (crm.enum.activitydirection)
        'OWNER_TYPE_ID'    => 2, // Тип сущности: 2 - Сделка, 3 - контакт, 4 - Компания,... (crm.enum.ownertype)
        'OWNER_ID'         => 39293, // ID сущности (сделки)
        'TYPE_ID'          => 4, // Тип активности: 4 - Письмо (crm.enum.activitytype)
        'RESPONSIBLE_ID'   => 4852, // ID ответственного пользователя
        'START_TIME'       => '2005-08-09T18:31:42+03:30', // Время начала
        'END_TIME'         => '2005-09-10T18:31:42+03:30', // Время окончания
        'COMMUNICATIONS' => [ // Параметры получателей письма
            [
                'VALUE'          => 'test@example.com', // Email компании
                'ENTITY_ID'      => 58938, // ID компании
                'ENTITY_TYPE_ID' => 4 // Тип сущности: 4 - Компания ('crm.enum.ownertype');
            ]
        ],
        'SETTINGS' => [
            'MESSAGE_FROM' => 'from@example.com'
        ]
    ]);
    print_r($activityId);

    // Получаем дело по ID
    $activity = $bx24->getActivity($activityId);
    print_r($activity);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы для работы с диском

Методы для работы с Диском находятся в трейте \App\Bitrix24\Disk:

  • getDiskStorageList(array $filter = []) :\Generator
    Загружает список доступных хранилищ с возможностью фильтрации.
  • getDiskStorageChildren($storageId, array $filter = []) :array
    Возвращает список файлов и папок, которые находятся непосредственно в корне хранилища с возможностью фильтрации.
  • uploadfileDiskFolder($folderId, string $fileContent, array $data, bool $isBase64FileData = true) :array Загружает новый файл в указанную папку на Диск.

Параметры методов:

  • $filter - параметры фильтрации;
  • $storageId - ID хранилища;
  • $filter - параметры фильтрации;
  • $folderId - ID папки;
  • $fileContent - RAW данные файла;
  • $data - набор параметров, описывающих файл (обязательное поле NAME - имя нового файла);
  • $isBase64FileData - RAW данные файла закодированы в BASE64?
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Загружаем список доступных хранилищ
    $generator = $bx24->getDiskStorageList();
    foreach ($generator as $storages) {
        foreach ($storages as $storage) {
            print_r($storage);
        }
    }

    // Загружаем список файлов и папок, которые находятся непосредственно в корне хранилища
    $files = $bx24->getDiskStorageChildren($storageId = 2);
    foreach ($files as $file) {
        print_r($file);
    }

    // Загружаем файл в указанную папку на Диск
    $bx24->uploadfileDiskFolder(
        $filderId = 4709,
        $rawFile = file_get_contents('./schet.pdf'),
        [ 'NAME' => 'schet.pdf' ],
        $isBase64FileData = false
    );

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Методы для работы с лидами

Методы для работы с лидами находятся в трейте \App\Bitrix24\Lead:

  • getLeadFields() :array Возвращает описание полей лида, в том числе пользовательских.
  • getLead($leadId, array $with = []) :array Возвращает лид по его ID.
  • addLead(array $fields = [], array $params = []) :int Добавляет лид и возвращает его ID.
  • updateLead($leadId, array $fields = [], array $params = []) :int Обновляет лид и возвращает его ID.
  • deleteLead($leadId) :int Удаляет лид по его ID.
  • getLeadList(array $filter = [], array $select = [], array $order = []): Generator
    Загружает все лиды с возможностью фильтрации, сортировки и выборки полей.
  • fetchLeadList(array $filter = [], array $select = [], array $order = []): Generator
    Загружает все лиды с возможностью фильтрации, сортировки и выборки полей.
    Реализует быстрый метод загрузки при работе с большими объемами данных.
  • getLeadProductRows($leadId) :array Возвращает массив параметров товарных позиций, связанных с лидом.
  • setLeadProductRows($leadId, array $products) :array Устанавливает товарные позиции, связанные с лидом.

Параметры методов:

  • $leadId - ID лида;
  • $with - имена связанных сущностей, возвращаемых вместе с лидом:
    • \App\Bitrix24\Bitrix24API::$WITH_PRODUCTS - товарные позиции (возвращаются в виде массива в поле с именем, заданным публичным статическим свойством Bitrix24API::$PRODUCTS);
  • $fields - набор полей лида;
  • $params - набор параметров лида;
  • $filter - параметры фильтрации;
  • $order - параметры сортировки;
  • $select - параметры выборки полей;
  • $products - массив параметров товарных позиций.
use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;

try {

    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Добавляем новый лид
    $leadId = $bx24->addLead([
        'TITLE'      => 'Новый лид №1'
    ]);
    print_r($leadId);

    // Устанавливаем набор связанных товарных позиций
    $bx24->setLeadProductRows($leadId, [
        [ 'PRODUCT_ID' => 1689, 'PRICE' => 1500.00, 'QUANTITY' => 2 ],
        [ 'PRODUCT_ID' => 1860, 'PRICE' => 500.00, 'QUANTITY' => 15 ]
    ]);

    // Обновляем существующий лид
    $bx24->updateLead($leadId [
        'TITLE' => 'Новый лид №12'
    ]);

    // При необходимости, изменяем значение по умолчанию 'PRODUCTS' на '_PRODUCTS' для имени поля
    // со списком товарных позиций, возвращаемых вместе с лидом
    Bitrix24API::$WITH_PRODUCTS = '_PRODUCTS';

    // Загружаем лид по ID вместе со связанными товарными позициями
    $lead = $bx24->getLead($leadId, [ Bitrix24API::$WITH_PRODUCTS ]);
    print_r($lead);

    // Удаляем существующий лид
    $bx24->deleteLead($leadId);

    // Загружаем все лиды используя быстрый метод при работе с большими объемами данных
    $generator = $bx24->fetchLeadList();
    foreach ($generator as $leads) {
        foreach($leads as $lead) {
            print_r($lead);
        }
    }

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}    

Вспомогательные классы

Класс HTTP

Класс \App\HTTP\НТТР обеспечивает:

  • формирование POST запросов к API Битрикс 24 по протоколу HTTPS;
  • троттлинг запросов к API на требуемом уровне - не более 2-х запросов в секунду;
  • вывод отладочной информации о запросах к API в STDOUT.

При возникновении ошибок выбрасывается исключение класса \App\HTTP\HTTPException.

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

Дополнительные параметры устанавливаются через публичные свойства объекта класса \App\HTTP\HTTP:

Свойство По умолчанию Описание
$debugLevel \App\HTTP\HTTP::DEBUG_NONE Устанавливает уровень вывода отладочной информации о запросах в STDOUT (битовая маска, составляемая из значений DEBUG_NONE, DEBUG_URL, DEBUG_HEADERS, DEBUG_CONTENT)
$throttle 0 Максимальное число HTTP запросов в секунду (0 - троттлинг отключен)
$addBOM false Добавлять маркер ВОМ UTF-8 (EFBBBF) к запросам в формате JSON
$useCookies false Использовать cookies в запросах
$cookieFile 'temp/cookies.txt' Путь к файлу для хранения cookies
$verifySSLCertificate true Включить проверку SSL/TLS-сертификата сервера
$SSLCertificateFile 'cacert.pem' Устанавливает файл SSL/TLS-сертификатов X.509 корневых удостоверяющих центров (CA) в формате РЕМ (установка в null означает использовать файл, указанный в параметре curl.cainfo файла php.ini)
$userAgent 'HTTP-client/3.x.x' Устанавливает НТТР заголовок UserAgent в запросах
$curlConnectTimeout 60 Устанавливает таймаут соединения, секунды
$curlTimeout 60 Устанавливает таймаут обмена данными, секунды
$successStatusCodes [ 200 ] Коды статуса НТТР, соответствующие успешному выполнению запроса

Примеры

use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;
use App\HTTP\HTTP;

try {
    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Устанавливаем максимальный уровень вывода отладочных сообщений в STDOUT
    $bx24->http->debugLevel = HTTP::DEBUG_URL |  HTTP::DEBUG_HEADERS | HTTP::DEBUG_CONTENT;

    // Устанавливаем троттлинг запросов на уровне не более 1 запроса в 2 секунды
    $bx24->http->throttle = 0.5;

    // Устанавливаем таймаут обмена данными в 30 секунд
    $bx24->http->curlTimeout = 30;

    // Получаем компанию по ID
    $results = $bx24->getCompany(20);

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Примеры отладочных сообщений:

[1] ===> POST https://www.example.com/rest/1/u7ngxagzrhpuj31a/crm.company.get.json
POST rest/1/u7ngxagzrhpuj31a/crm.company.get.json HTTP/1.1
Host: www.example.com
User-Agent: HTTP-client/2.x.x
Accept: */*
Content-Length: 5
Content-Type: application/x-www-form-urlencoded

id=20

[1] <=== RESPONSE 0.5348s (200)
HTTP/1.1 200 OK
Server: nginx/1.16.1
Date: Mon, 15 Jun 2020 13:11:33 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
P3P: policyref="/bitrix/p3p.xml", CP="NON DSP COR CUR ADM DEV PSA PSD OUR UNR BUS UNI COM NAV INT DEM STA"
X-Powered-CMS: Bitrix Site Manager (bc2cad9153cb418bb2dfd5602c3c3754)
Set-Cookie: PHPSESSID=uSBxTO1tiaVfYPd7I7BhvjPLc2H2RhuD; path=/; secure; HttpOnly
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Set-Cookie: qmb=.; path=/
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: origin, content-type, accept
X-Content-Type-Options: nosniff
X-Bitrix-Rest-Time: 0.0098488331
X-Bitrix-Rest-User-Time: 0.0042990000
X-Bitrix-Rest-System-Time: 0.0000030000
Set-Cookie: BITRIX_SM_SALE_UID=4; expires=Thu, 10-Jun-2021 13:11:33 GMT; Max-Age=31104000; path=/
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubdomains
X-Bitrix-Times: 0.104/0.104/0.000
X-Bitrix-TCP: 32250/6750/20/14480
X-Bitrix-RI: 3b51dd618cb995cfc06d2016cc4c0c94
X-Bitrix-LB: lb-ru-04

{"result":{"ID":"20","COMPANY_TYPE":"CUSTOMER","LOGO":null,"LEAD_ID":null,"HAS_PHONE":"N","HAS_EMAIL":"Y"}}

Класс DebugLogger

Класс \App\DebugLogger\DebugLogger обеспечивает логирование запросов и ответов к API Битрикс24 в файл.
При возникновении ошибок выбрасывается исключение класса \App\DebugLogger\DebugLoggerException.

Методы класса

  • static instance(string $logFileName = 'debug.log') :self
    Возвращает единственный объект данного класса для заданного лог-файла $logFileName.
    • $logFileName - имя лог-файла.
  • save(mixed $info, object $object = null, string $header = null) :void Сохраняет подлежащую логированию информацию в файл.
    • $info - строка, массив или объект для логирования;
    • $object - ссылка на объект класса в котором выполняется логирование;
    • $header - строка заголовка для сохраняемой в лог файл информации.

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

Дополнительные параметры устанавливаются через публичные свойства класса \App\DebugLogger\DebugLogger:

Нестатическое свойство По умолчанию Описание
$isActive false Включает или выключает логирование для конкретного файла, задаваемого параметром $logFileName метода instance()
Статическое свойство По умолчанию Описание
$logFileDir temp/ Устанавливает каталог, в котором сохраняются лог-файлы
mkdirMode 0755 Устанавливает режим доступа для создаваемых каталогов для хранения лог файлов в виде восьмеричного числа
$uniqIdLength 7 Длина уникального буквенно-цифрового [a-z0-9]+ идентификатора объекта класса DebugLogger для сохранения в лог файле, позволяющего находить записи, созданные одним и тем же процессом

Примеры

use App\Bitrix24\Bitrix24API;
use App\Bitrix24\Bitrix24APIException;
use App\DebugLogger\DebugLogger;

try {
    $webhookURL = 'https://www.example.com/rest/1/u7ngxagzrhpuj31a/';
    $bx24 = new Bitrix24API($webhookURL);

    // Устанавливаем каталог для сохранения лог файлов
    DebugLogger::$logFileDir = 'logs/';

    // Создаем объект класса логгера
    $logFileName = 'debug_bitrix24api.log';
    $logger = DebugLogger::instance($logFileName);

    // Включаем логирование
    $logger->isActive = true;

    // Устанавливаем логгер
    $bx24->setLogger($logger);

    // Загружаем все компании
    $bx24->fetchCompanyList();

} catch (Bitrix24APIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (Exception $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Пример результатов логирования:

*** 92qshr5 [2020-06-14 13:32:44.993285 +00:00 Δ0.012308 s, 0.70/2.00 MiB] ********************
* Class: App\Bitrix24\Bitrix24API
ЗАПРОС: crm.company.list.json
{
    "order": {
        "ID": "ASC"
    },
    "filter": {
        ">ID": 0
    },
    "select": [],
    "start": -1
}


*** 92qshr5 [2020-06-14 13:32:46.900518 +00:00 Δ1.907233 s, 1.14/2.00 MiB] ********************
ОТВЕТ: crm.company.list.json
{
    "result": [
        {
            "ID": "2",
            "COMPANY_TYPE": "PARTNER",
            "TITLE": "ООО",
            "LOGO": {
                "id": 112,
                "showUrl": "\/bitrix\/components\/bitrix\/crm.company.show\/show_file.php?ownerId=2",
                "downloadUrl": "\/bitrix\/components\/bitrix\/crm.company.show\/show_file.php?auth=&ownerId=2"
            }
        }
    }
}

*** 92qshr5 [2020-06-14 13:32:46.902085 +00:00 Δ0.001567 s, 1.30/2.00 MiB] ********************
* Class: App\Bitrix24\Bitrix24API
По запросу (fetchList) crm.company.list получено сущностей: 50, всего получено: 50

Формат заголовков лога
*** 92qshr5 [2020-06-14 13:32:46.902085 +00:00 Δ0.001567 s, 1.30/2.00 MiB] ********************
* Class: App\Bitrix24\Bitrix24API
  • 92qshr5 - уникальный буквенно-цифровой [a-z0-9]+ идентификатор объекта класса DebugLogger, позволяющий находить в лог файле записи, созданные одним и тем же процессом;
  • 2020-06-14 13:32:46.902085 - дата и время сохранения информации с точностью до микросекунд;
  • Δ0.001567 s - время, прошедшее с момента предыдущего сохранения информации в секундах и микросекундах;
  • 1.30/2.00 MiB - данные об используемой оперативной памяти в единицах количества информации с двоичными приставками:
    • 1.30 - максимальный объем памяти, который был выделен PHP-скрипту системой;
    • 2.00 - реальный объем памяти, выделенный PHP-скрипту системой;
  • 'Class: App\Bitrix24\Bitrix24API' - полное имя класса из которого сделано сохранение в лог файл.

Автор

© 2019-2021 andrey-tech

Лицензия

Данная библиотека распространяется на условиях лицензии MIT.

About

Обертка на PHP7+ для работы с REST API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов к API и логированием в файл.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 100.0%