README

Trunkrs 公共客户端 SDK 的软件开发工具包。使用此 PHP SDK，您可以在我们的系统中管理您的运输、运输状态和 webhooks。

从版本 1 迁移

如果您想迁移 Trunkrs SDK 的 v1 实现，请查看我们的迁移指南。

要求

PHP 7.0 及以上。

安装

您可以通过 Composer 安装 SDK。运行以下命令：

composer require trunkrs/sdk

要使用绑定，请使用 Composer 的 自动加载

require_once('vendor/autoload.php');

依赖

SDK 需要以下扩展才能正常工作：

• json
• guzzle/guzzle（可选，可替换）

如果您使用 Composer，这些依赖项应自动处理。

入门

在使用前，通过提供您的商户凭据来设置 SDK 设置。如果您还没有任何凭据，请联系 Trunkrs 以获取更多信息。

\Trunkrs\SDK\Settings::setApiKey("your-trunkrs-api-key");

使用测试环境

为了使用 Trunkrs 测试环境，您可以使用我们的系统测试您的实现。SDK 可以轻松切换。

\Trunkrs\SDK\Settings::useStaging();

API 端点和跟踪 URL 都将指向测试环境。

运输

创建运输

可以通过 Shipment 类创建运输，它公开了一个静态方法 Shipment::create(...)。

$details = new \Trunkrs\SDK\ShipmentDetails();

$parcel = new \Trunkrs\SDK\Parcel();
// Set the reference of the parcel. This is required.
$parcel->reference = 'your-order-reference';

$details->parcels = [
    // Define which parcels are part of this shipment
    $parcel,
];

$details->sender = new \Trunkrs\SDK\Address();
// Set the pickup address properties.

$details->recipient = new \Trunkrs\SDK\Address();
// Set the delivery address properties.

$shipments = \Trunkrs\SDK\Shipment::create($details);

国际运输

在国际运输时，我们要求您定义包裹的内容以及包裹的体积和重量。

检索运输详情

可以通过调用 Shipment::find($trunkrsNr) 方法通过其标识符检索单个运输的详细信息。

$shipment = \Trunkrs\SDK\Shipment::find('4000002123');

检索运输历史

您可以使用 Shipment::retrieve($page) 方法以分页方式列出您的运输历史。每页最多包含 50 个运输。

$shipments = \Trunkrs\SDK\Shipment::retrieve();

取消运输

可以通过其标识符或通过 Shipment 实例的 cancel() 方法取消运输。

Shipment 类公开了一个名为 cancelByTrunkrsNr($trunkrsNr) 的静态方法

\Trunkrs\SDK\Shipment::cancelByTrunkrsNr('4000002123');

Shipment 实例还公开了一个便利方法 cancel()

$shipment = \Trunkrs\SDK\Shipment::find('4000002123');

$shipment->cancel();

运输状态

要检索关于运输当前状态和当前所有者的详细信息，可以使用 ShipmentState 类，该类公开了一个静态方法 forShipment($shipmentId)。

$status = \Trunkrs\SDK\ShipmentState::forShipment('4000002123');

Webhooks

为了通知运输状态更改，Trunkrs 创建了一个 webhook 通知服务。SDK 允许通过此服务注册通知的回调 URL。

注册订阅

Webhook 类公开了一个名为 register($webhook) 的静态方法，允许注册新的 webhooks

$webhook = new \Trunkrs\SDK\Webhook();
$webhook->callbackUrl = "https://your.web.service/shipments/webhook";
$webhook->sessionHeaderName = 'X-SESSION-TOKEN';
$webhook->sessionToken = "your-secret-session-token";
$webhook->event = \Trunkrs\SDK\Enum\WebhookEvent::ON_STATE_UPDATE;

\Trunkrs\SDK\Webhook::register($webhook);

检索活动订阅

您可以使用 Webhook::retrieve() 查看您的活动 webhook 订阅。

$webhooks = \Trunkrs\SDK\Webhook::retrieve();

取消订阅

可以使用 Webhook::removeById($webhookId) 或 webhook 实例上的实例方法取消 webhook 订阅。

$webhookId = 100;

\Trunkrs\SDK\Webhook::removeById($webhookId);

$webhook = \Trunkrs\SDK\Webhook::find(100);

$webhook->remove();