README

RetailCRM API PHP 客户端

这是一个 RetailCRM API 的 PHP 客户端。这个库允许使用实际 API 版本。
更多详细信息请参考 文档。

目录

• 要求
• 安装
• 使用
• 示例
• 注意
• 文档

要求

• PHP 7.3 及以上版本
• PHP 的 cURL 支持
• PHP 的 JSON 支持
• 任何兼容 PSR-18 的 HTTP 客户端（安装说明中涵盖）。
• 任何兼容 PSR-17 的 HTTP 工厂实现（安装说明中涵盖）。
• 任何兼容 PSR-7 的 HTTP 消息实现（安装说明中涵盖）。
• 其他在 composer.json 中列出的依赖项（安装说明中涵盖）

安装

按照以下步骤安装库

1. 下载并安装 Composer 包管理器。
2. 通过执行以下命令从 Packagist 安装库

composer require retailcrm/api-client-php:"~6.0"

在安装过程中，您将看到此消息。在执行时按 'y'。

civicrm/composer-compile-plugin contains a Composer plugin which is currently not in your allow-plugins config. See https://getcomposer.org.cn/allow-plugins
Do you trust "civicrm/composer-compile-plugin" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?]

之后，您可能看到一条类似的消息

The following packages have new compilation tasks:
 - retailcrm/api-client-php has 1 task

Allow these packages to compile? ([y]es, [a]lways, [n]o, [l]ist, [h]elp)

通过键入 a 并按 Enter 键选择 [a]lways。

注意：如果您使用的是 CI/CD 流水线，则应选择 'y' 和 [a]lways，因为在该环境中不可用交互式终端，这将导致依赖项安装失败。

如果在安装过程中选择了其他选项并且 API 客户端无法正常工作，请按照 这些说明 修复问题。

1. 如果没有包含自动加载器，或者您之前没有使用过 Composer，请包含它。

require 'path/to/vendor/autoload.php';

将 path/to/vendor/autoload.php 替换为 Composer 的 autoload.php 的正确路径。

注意：API 客户端使用 php-http/curl-client 和 nyholm/psr7 作为 PSR-18、PSR-17 和 PSR-7 的实现。您可以在安装过程中通过安装您选择的实现来替换这些实现，如下所示

composer require symfony/http-client guzzlehttp/psr7 retailcrm/api-client-php:"~6.0"

更多关于此的信息可以在 文档 中找到。

使用

首先，您应该初始化客户端。最简单的方法是使用 SimpleClientFactory

$client = \RetailCrm\Api\Factory\SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

客户端分为几个资源组，所有这些组都可以通过客户端的公共属性访问。您可以通过这些组调用 API 方法，如下所示

$client->api->credentials();

例如，您可以检索客户列表

$client = \RetailCrm\Api\Factory\SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');
$response = $client->customers->list();

或订单列表

$client = \RetailCrm\Api\Factory\SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');
$response = $client->orders->list();

要处理错误，您必须使用两种类型的异常

• RetailCrm\Api\Interfaces\ClientExceptionInterface 用于网络或其他运行时错误。
• RetailCrm\Api\Interfaces\ApiExceptionInterface 用于 API 错误。

有关错误处理的示例，请参阅本文件的下一节。

每个资源组负责相应的 API 部分。例如，costs 资源组提供成本操作的方法，而 loyalty 资源组允许与忠诚度计划、账户、奖金等交互。

使用注解来确定您需要哪些 DTO 用于发送请求。如果您的 IDE 没有提供注解，您可能需要配置它们。这将大大简化您使用（以及任何其他）库的工作。

有关用法和示例的更多信息，请参阅 文档。

示例

列出订单

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Model\Entity\CustomersCorporate\CustomerCorporate;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

try {
    $response = $client->orders->list();
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface and ClientExceptionInterface instance implements __toString() method.
    exit(-1);
}

foreach ($response->orders as $order) {
    printf("Order ID: %d\n", $order->id);
    printf("First name: %s\n", $order->firstName);
    printf("Last name: %s\n", $order->lastName);
    printf("Patronymic: %s\n", $order->patronymic);
    printf("Phone #1: %s\n", $order->phone);
    printf("Phone #2: %s\n", $order->additionalPhone);
    printf("E-Mail: %s\n", $order->email);

    if ($order->customer instanceof CustomerCorporate) {
        echo "Customer type: corporate\n";
    } else {
        echo "Customer type: individual\n";
    }

    foreach ($order->items as $item) {
        echo PHP_EOL;

        printf("Product name: %s\n", $item->productName);
        printf("Quantity: %d\n", $item->quantity);
        printf("Initial price: %f\n", $item->initialPrice);
    }

    echo PHP_EOL;

    printf("Discount: %f\n", $order->discountManualAmount);
    printf("Total: %f\n", $order->totalSumm);

    echo PHP_EOL;
}

通过 ID 获取特定订单

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Enum\ByIdentifier;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Model\Request\BySiteRequest;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

try {
    $response = $client->orders->get(1234, new BySiteRequest(ByIdentifier::ID, 'site'));
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

echo 'Order: ' . print_r($response->order, true);

创建新客户

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Model\Entity\Customers\Customer;
use RetailCrm\Api\Model\Request\Customers\CustomersCreateRequest;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

$request = new CustomersCreateRequest();
$request->customer = new Customer();

$request->site = 'aliexpress';
$request->customer->email = 'john.doe@example.com';
$request->customer->firstName = 'John';
$request->customer->lastName = 'Doe';

try {
    $response = $client->customers->create($request);
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

echo 'Customer ID: ' . $response->id;

为具有特定电子邮件的用户创建任务

<?php

use RetailCrm\Api\Interfaces\ClientExceptionInterface;
use RetailCrm\Api\Interfaces\ApiExceptionInterface;
use RetailCrm\Api\Factory\SimpleClientFactory;
use RetailCrm\Api\Model\Entity\Tasks\Task;use RetailCrm\Api\Model\Filter\Users\ApiUserFilter;
use RetailCrm\Api\Model\Request\Tasks\TasksCreateRequest;
use RetailCrm\Api\Model\Request\Users\UsersRequest;

$client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');

$usersRequest = new UsersRequest();
$usersRequest->filter = new ApiUserFilter();
$usersRequest->filter->email = 'john.doe@example.com';

try {
    $usersResponse = $client->users->list($usersRequest);
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

if (0 === count($usersResponse->users)) {
    echo 'User is not found.';
    exit(-1);
}

$tasksRequest = new TasksCreateRequest();
$tasksRequest->task = new Task();
$tasksRequest->task->performerId = $usersResponse->users[0]->id;
$tasksRequest->task->text = 'Do something!';
$tasksRequest->site = 'site';

try {
    $tasksResponse = $client->tasks->create($tasksRequest);
} catch (ApiExceptionInterface | ClientExceptionInterface $exception) {
    echo $exception; // Every ApiExceptionInterface instance should implement __toString() method.
    exit(-1);
}

echo 'Created task with ID: ' . $tasksResponse->id;

上面示例中的错误处理对于实际生产使用已经足够好了。您可以安全地假设 ApiExceptionInterface 是来自 API 的错误，而 ClientExceptionInterface 是客户端错误（例如网络错误或任何运行时错误，使用 HttpClientException 来仅捕获 PSR-18 客户端错误）。然而，如果您愿意，可以实施更复杂的错误处理。

此外，ApiExceptionInterface 和 ClientExceptionInterface 都实现了 __toString()。这意味着您可以将这些异常转换为字符串，并将结果放入日志中，而无需对异常数据进行特殊处理。

更多示例可以在 文档 中找到。

您可以使用兼容 PSR-14 的事件分配器来接收客户端事件。有关详细信息，请参阅 文档。

注意

此库使用 HTTPlug 抽象。有关更多信息，请访问 官方文档。