README

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

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

Содержание

Требования
Установка
Класс Bitrix24API
- Базовые методы класса
- Дополнительные параметры
Методы для работы с сущностями Битрикс24
Вспомогательные классы
- Класс HTTP
  - Дополнительные параметры
  - Примеры
- Класс DebugLogger
Автор
Лицензия

Требования

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:

Методы для работы с сущностями Битрикс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
Загружает все контакты с возможностью фильтрации, сортировки и выборки полей.
Реализует быстрый метод загрузки при работе с большими объемами данных.
getContactsByPhone(int|string $phone, $select = []) :array Возвращает контакты по номеру телефона.
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 сделок;
$phone - номер телефона;
$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.
getTaskList(array $filter = [], array $select = [], array $order = []): Generator Возвращает все задачи.
addTask(array $fields = []) :int Добавляет новую задачу.
addTasks(array $tasks = []) :array Пакетно добавляет задачи.
getTaskFields() :array Возвращает описание полей задачи.

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

$taskId - ID задачи;
$filter - параметры фильтрации;
$select - параметры выборки полей;
$order - параметры сортировки;
$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);

    // Получаем все задачи 
    $generator = $bx24->getTaskList();
    foreach ($generator as $result) {
        print_r($result);
    }

    // Создаем новую задачу
    $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:

Примеры

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;

    // ИЛИ  
    // убираем вывод отладочных сообщений в случае необходимости.
    // Раскомментируем строчку нижи И закоментируем рабочую строчку выше
    // $bx24->http->debugLevel = HTTP::DEBUG_NONE;

    // Устанавливаем троттлинг запросов на уровне не более 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:

Примеры

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' - полное имя класса из которого сделано сохранение в лог файл.

Автор

Лицензия

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

andrey-tech / bitrix24-api-php

Maintainers

Details

README

Содержание

Требования

Установка

Класс `Bitrix24API`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Класс `HTTP`

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

Примеры

Класс `DebugLogger`

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

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

Примеры

Формат заголовков лога

Автор

Лицензия

andrey-tech / bitrix24-api-php

Maintainers

Details

README

Содержание

Требования

Установка

Класс Bitrix24API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Класс HTTP

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

Примеры

Класс DebugLogger

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

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

Примеры

Формат заголовков лога

Автор

Лицензия

Класс `Bitrix24API`

Класс `HTTP`

Класс `DebugLogger`