README

订单跟踪 API - PHP SDK

一个多功能 API，可以跟踪全球超过 850 家快递公司和邮政服务机构的包裹，支持所需语言。

该库为用 PHP 编写的应用程序提供了方便地访问 business.pkge.net api 的接口。

跟踪 API 文档可在此处找到： https://business.pkge.net/docs

要求

PHP 5.4.0 及以上版本。

安装

通过 Composer (https://getcomposer.org/)

运行以下命令

composer require pkge/php-sdk

要使用 SDK，请使用 Composer 的 autoload

require_once 'vendor/autoload.php';

入门指南

首先，您需要使用您的 API 密钥初始化 api 包装器类

$api = new \Pkge\API(
    '{API_KEY}', //Your API key
    'en', //API language
    false //Expand related objects
);

响应元数据

最后响应的元数据，例如某些 API 端点的请求速率限制和分页信息，可在 getLastResponseMetaData() 方法中找到

$metadata = $api->getLastResponseMetaData();

//Last response status code
$metadata->responseStatusCode; 

//Requests Rate-Limit information.
$metadata->rateLimit;

//Pagination information
$metadata->pagination;

实体

SDK 中使用的所有实体及其属性描述，请参阅 /src/Entities

配送服务端点

通过 API 对象的 couriers 属性访问所有配送服务端点

$api->couriers;

所有可用的端点方法请参阅 \Pkge\Endpoints\Couriers::class

包裹端点

通过 API 对象的 packages 属性访问所有配送服务端点

$api->packages;

所有可用的端点方法请参阅 \Pkge\Endpoints\Packages::class

Webhooks

使用 \Pkge\Webhook::class 来处理 webhook 通知。示例

$webhook = new \Pkge\Webhook('WEBHOOK_SECRET');

try {
    $event = $webhook->handleEvent(
        file_get_contents("php://input"),
        $_SERVER['HTTP_PKGE_WEBHOOK_SIGNATURE']
    );
} catch (\Pkge\Exceptions\WebhookSignatureException $e) {
    die ($e->getMessage());
}

/** @var \Pkge\Entities\Package $updatedPackage */
$updatedPackage = $event->payload;

异常

在某些情况下，通过 SDK 进行 API 请求时可能会发生异常。它们的描述如下。有关特定方法可以抛出哪些异常的更多信息，请参阅该方法的 PHPDoc 注释。

\Pkge\Exceptions\ApiBadKeyException - 指定的 API 密钥无效。如何获取 API 密钥，请参阅此处。
\Pkge\Exceptions\ApiCouriersNotDetectedException - 无法自动识别给定跟踪号码的配送服务。
\Pkge\Exceptions\ApiMaxPackagesAmountUpdatingNowException - 无法更新包裹。当前正在更新允许的最大包裹数量。等待下一个包裹完成更新，然后重复请求。
\Pkge\Exceptions\ApiPackageCannotBeUpdatedException - 无法更新包裹。自上次更新以来未经过足够的时间，或包裹已被投递。如果可能更新，则在 'payload' 中跟随下一个可能的更新日期。
\Pkge\Exceptions\ApiPackagesLimitExceededException - 您已达到您计划在账单期间添加包裹的限制。
\Pkge\Exceptions\ApiRequestRateLimitException - 每秒请求限制超出。
\Pkge\Exceptions\ApiTrackNumberExistsException - 跟踪号码已添加。
\Pkge\Exceptions\ApiWrongCourierIdException - 指定的配送服务 ID 无效。
\Pkge\Exceptions\ApiWrongTrackNumberException - 无效或不支持的跟踪号码格式。
\Pkge\Exceptions\ApiRequestValidationException - 验证POST请求发送的数据出错。请参阅异常中getValidationErrors()方法中的验证错误描述。
\Pkge\Exceptions\ApiRequestException - 一般或未知请求错误。请参阅getMessage()方法的描述。

示例

示例代码请查看examples/demo.php。运行

php ./examples/demo.php

pkge / php-sdk

维护者

详细信息