Download the PHP package andrey-tech/bitrix24-api-php without Composer

Bitrix24 API PHP Wrapper

Обертка на 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:

или добавить

в секцию 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 - массив параметров товарных позиций.

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

Методы для работы с контактами находятся в трейте \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 - массив параметров компаний.

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

Методы для работы с компаниями находятся в трейте \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 - массив параметров компаний.

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

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

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

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

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

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

Методы для работы с товарами находятся в трейте \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 - массив наборов полей товара.

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

Методы для работы с разделами товаров находятся в трейте \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 - параметры сортировки.

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

Методы для работы с товарными позициями находятся в трейте \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 - включает режим администратора для получения данных о любых пользователях.

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

Методы для работы с задачами находятся в трейте \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 - массив наборов полей задач.

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

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

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

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

• $activityId - ID дела;
• $fields - набор полей дела;
• $activities - массив наборов полей дел.

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

Методы для работы с Диском находятся в трейте \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?

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

Методы для работы с лидами находятся в трейте \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 - массив параметров товарных позиций.

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

Класс HTTP

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

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

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

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

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

Примеры

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

Класс 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:

Примеры

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

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

• 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.