README

RetailCRM API PHP客户端

这是PHP RetailCRM API客户端。这个库允许使用实际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。

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

如果安装过程中选择了其他选项，并且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抽象。有关更多信息，请访问官方文档。