andrey-tech/bitrix24-api-php

PHP7+版本的Bitrix24 API包装器，使用内置的webhook机制，请求节流和文件日志记录。

维护者

详细信息

github.com/andrey-tech/bitrix24-api-php

主页

源代码

问题

安装数: 44,912

依赖: 0

建议者: 0

安全: 0

星标: 92

关注者: 11

分支: 30

开放问题: 1

1.8.1 2024-04-07 07:39 UTC

Requires

MIT dded740f573a05058c2ef70761355e307518af59

loggingapithrottlingwebhookbitrixBitrix24api-wrapper

This package is auto-updated.

Last update: 2024-09-05 06:58:10 UTC

README

Bitrix24 logo

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

PHP7+版本的REST API Bitrix24包装器，使用内置的webhook机制、请求节流和文件日志记录。

JavaScript开发者可以使用andrey-tech/bx24-wrapper-js类包装器。

内容

要求

  • PHP >= 7.0;
  • 类 HTTP >= 3.0 - 支持请求节流、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"

到composer.json文件的require部分。

类 Bitrix24API

用于处理Bitrix24 REST API的类是 \App\Bitrix24\Bitrix24API。
发生错误时，抛出\App\Bitrix24\Bitrix24APIException类的异常。
目前类中实现了以下Bitrix24实体的处理方法

类的基本方法

基本方法位于\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 - 入站Webhook的URL；
  • $function - 请求方法的名称（函数）；
  • $params - 请求参数；
  • $commands - 命令包；
  • $items - 请求字段数组；
  • $halt - 发生错误时中断请求序列；
  • $logger - 实现接口 \App\DebugLogger\DebugLoggerInterface 的类对象。

额外参数

通过类 \App\Bitrix24\Bitrix24API 的公共静态和非静态属性可以访问更多的配置参数。

处理Bitrix24实体的方法

处理交易的方法

处理交易的方法位于 \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 - 文件参数数组 ([ [ < 文件名 >, < 文件原始数据 > ], ... ]) （空数组用于删除所有文件）；
  • $isBase64FileData 文件原始数据是否以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 设置与联系人关联的公司。
  • 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 - 文件原始数据；
  • $data - 描述文件的参数集（必需字段 NAME - 新文件名）；
  • $isBase64FileData - 文件原始数据是否已编码为 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\НТТР 提供

  • 按 HTTPS 协议向 Bitrix 24 API 发送 POST 请求；
  • 对 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 提供将 Bitrix24 API 的请求和响应记录到文件的功能。
出现错误时抛出 \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 - 由类 DebugLogger 的唯一字母数字 [a-z0-9]+ 标识符，允许在日志文件中找到由同一进程创建的记录；
  • 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许可协议下分发。