README

此客户端库为 PHP 应用程序提供了与 Penny Black 平台通信的可重用 API 接口。SDK 将方法封装起来，简化了请求、授权、错误处理，并通过模型提供可用参数的指导。它遵循 PSR-7、PSR-17 和 PSR-18 标准，依赖经过验证的外部库来提供 HTTP 客户端和消息工厂。

对于开发，我们捆绑了 Guzzle，但您可以选择自己的，或者使用平台中包含的客户端，只要它支持这些标准即可。

请参阅 Penny Black API 文档 以获取可用端点的完整详细信息。

前置条件

• PHP >=7.2
• Composer

安装

对于生产环境，您可以使用 Composer 将库作为项目依赖项包含。

composer require pennyblack/php-sdk

您还需要确保您有满足虚拟 psr/http-client-implementation 和 psr/http-factory-implementation 要求的包。如果没有，则可以要求安装 Guzzle，这将满足两个要求。

composer require guzzlehttp/guzzle

使用方法

请参阅 示例 文件夹以了解如何使用库的工作示例。

创建 API 实例

您需要 API 密钥才能访问 Penny Black 服务。如果您已设置测试环境，则可以将 $isTest 标志设置为 true 以针对我们的测试服务器发出请求。对于大多数客户，我们只提供生产账户。

下面的示例使用 Guzzle，但您可以使用任何 PSR-18 兼容的 HTTP 客户端，请参阅 此处 和 此处 的包选项。

<?php

include __DIR__ . "/../vendor/autoload.php";

use PennyBlack\Api;
use GuzzleHttp\Psr7\HttpFactory;
use GuzzleHttp\Client;

$httpClient = new Client();
$streamFactory = new HttpFactory();
$requestFactory = new HttpFactory();

$apiKey = "YOUR-API-KEY";
$myIntegrationVersion = "1.0.1";
$isTest = true;

$api = new Api($httpClient, $requestFactory, $streamFactory, $apiKey, $isTest, $myIntegrationVersion);

$myIntegrationVersion 参数用于识别正在运行哪个版本的集成，以便我们的支持团队。如果您正在使用自定义集成，则此值的价值有限，但对于构建平台模块/插件/扩展非常有用。此参数可以传递到 API 构造函数，或者在支持它的特定函数调用上设置，具体取决于您的集成方法。

安装您的商店

此请求充当 API 密钥的验证，并配置 Penny Black 使用您的商店域名。

$api->installStore("your.store.com", "1.0.1");

第二个参数是集成的版本，这是可选的，请参阅上面的说明。

发送订单

您应将所有创建的订单发送到我们的订单摄取端点。

$order = new Order()
    ->setId("42")
    ->setNumber("#42")
    ->setCreatedAt(new DateTime())
    ->setCurrency('GBP')
    ->setTotalAmount(123.45)
    ->setTotalItems(2)
    ;
   
// You only need to send optional fields if you have data for them 
if ($hasShippingAddress) {
    $order->setShippingCity('London')
    ->setShippingCountry('GB')
    ->setShippingPostcode('SE15AB')
    ;
}

$customer = new Customer()
    ->setFirstName("John")
    ->setLastName("Doe")
    ->setEmail("john@example.com"
    ->setVendorCustomerId("42")
    ...
    ;
    
$origin = "magento";
    
$api->sendOrder($order, $customer, $origin, "1.0.1");

最后一个参数是集成的版本，这是可选的，请参阅上面的说明。

打印订单

备注：履约端点使用单独的 API 密钥。对于自行履约的小型商家，这应与您的商家 API 密钥相同，但这不能保证。如果您不确定，请联系支持人员。

try {
    $response = $api->requestPrint($orderId, $locationId, $merchantId);
    print($response);
} catch (PennyBlackException $e) {
    print $e->getMessage();
}

批量打印

try {
    $response = $api->requestBatchPrint($orderIds, $locationId, $merchantId);
    print_r($response);
} catch (PennyBlackException $e) {
    print $e->getMessage();
}

获取订单打印状态

try {
    $response = $api->getOrderPrintStatus($merchantId, $orderId);
    print_r($response);
} catch (PennyBlackException $e) {
    print $e->getMessage();
}

开发

开发时使用 composer install 将包含 dev 依赖项，以便您可以使用 Guzzle 和测试请求。

请参阅 example 文件夹以了解如何使用库的工作示例。

测试和 linting

我们使用 PHPUnit 进行单元测试，并使用 PHPStan、PHP CodeSniffer 和 PHP Mess Detector 进行质量检查。

• 运行 composer unit-test 以运行单元测试。
• 运行 composer quality-check 以运行质量检查工具。