andrey-tech / bitrix24-api-php
Обертка на PHP7+ для работы с API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов и логированием в файл
Installs: 66 759
Dependents: 0
Suggesters: 0
Security: 0
Stars: 98
Watchers: 12
Forks: 30
Open Issues: 0
pkg:composer/andrey-tech/bitrix24-api-php
Requires
- php: >=7.0
- ext-json: *
- andrey-tech/debug-logger-php: ^2.0
- andrey-tech/http-client-php: ^3.0
This package is auto-updated.
Last update: 2025-10-20 15:01:49 UTC
README
Обертка на PHP7+ для работы с REST API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов и логированием в файл.
Разработчики на JavaScript могут воспользоваться классом-оберткой andrey-tech/bx24-wrapper-js.
Содержание
- Требования
- Установка
- Класс Bitrix24API
- Методы для работы с сущностями Битрикс24
- Методы работы со сделками
- Методы для работы с контактами
- Методы для работы с компаниями
- Методы для работы с каталогами
- Методы для работы с товарами
- Методы работы с разделами товаров
- Методы работы с товарными позициями
- Методы для работы с пользователями
- Методы работы с задачами
- Методы для работы с делами
- Методы для работы с диском
- Методы для работы с лидами
 
- Вспомогательные классы
- Автор
- Лицензия
Требования
- 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- параметры выборки полей;
- $userFieldIdID НЕ множественного пользовательского поля в сделке ('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:
| Свойство | По умолчанию | Описание | 
|---|---|---|
| $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; // ИЛИ // убираем вывод отладочных сообщений в случае необходимости. // Раскомментируем строчку нижи И закоментируем рабочую строчку выше // $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:
| Нестатическое свойство | По умолчанию | Описание | 
|---|---|---|
| $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-2022 andrey-tech
Лицензия
Данная библиотека распространяется на условиях лицензии MIT.
