README

要通过皇家邮政API跟踪物品，您需要成为皇家邮政账户持有者，并通过皇家邮政开发者门户获得对跟踪API的批准访问权限，请访问https://developer.royalmail.net/

安装

composer require nomisoft/royal-mail-tracking-api

用法

您需要提供要获取详细信息的物品的跟踪参考号以及您的客户端ID、客户端密钥和应用程序ID（所有这些都可以从皇家邮政开发者门户获取）

单个物品摘要

use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
use \Nomisoft\RoyalMailTrackingApi\RoyalMailException;

$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
try {
    $response = $rm->getSingleItemSummary('XX12345678XX');
}catch (SoapFault $e) {
	echo $e->getMessage();
} catch(RoyalMailException $e) {
	echo $e->getMessage() . ' - ' . $e->getCause();
}

返回的响应是一个包含DateTime对象、状态和摘要文本的数组

Array
(
    [datetime] => DateTime Object
        (
            [date] => 2016-06-01 12:30:00
            [timezone_type] => 3
            [timezone] => Europe/London
        )
    [status] => Delivered
    [summary] => Item XX12345678XX was collected and signed for by the addressee on the 2016-06-01 from Kidderminster DO.
)

单个物品完整历史记录

use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
$response = $rm->getSingleItemHistory('XX12345678XX');

返回的响应是一个多维数组。每个投递状态更新都包含一个DateTime对象、位置和状态

Array
(
    [0] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-06-01 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Kidderminster DO
            [status] => Delivered
        )

    [1] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-05-31 15:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Kidderminster DO
            [status] => We have your item
        )

    [2] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-05-31 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Kidderminster DO
            [status] => Delivery attempted
        )

    [3] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-05-28 10:00:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Medway Mail Centre
            [status] => It's on its way.
        )

)

多个物品摘要

use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
$response = $rm->getMultiItemSummary(array('XX12345678XX','ZZ12345678ZZ'));

返回的响应是一个多维数组，以跟踪参考号为键。每个物品包含一个DateTime对象、状态和摘要

Array
(
    [XX12345678XX] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-06-01 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [status] => Delivered
            [summary] => Item XX12345678XX was collected and signed for by the addressee on the 2016-06-01 from Kidderminster DO.
        )

    [ZZ12345678ZZ] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-06-01 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [status] => Delivered
            [summary] => We have a record of item ZZ12345678ZZ as being delivered from Fort William DO on 2016-06-01.
        )
)

投递证明

use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
$response = $rm->getProofOfDelivery('XX12345678XX');

返回的响应是一个包含DateTime对象和签署包裹的人名的数组

Array
(
    [datetime] => DateTime Object
        (
            [date] => 2016-06-01 12:30:00
            [timezone_type] => 3
            [timezone] => Europe/London
        )
    [name] => Smith
)

错误

如果从API收到错误响应，将抛出RoyalMailException异常。调用getMessage()函数将返回皇家邮政的错误描述。还有一个额外的getCause()函数，它将返回API返回的'Cause'字段的值

try {
    $response = $rm->getSingleItemSummary('XX12345678XX');
} catch(RoyalMailException $e) {
	echo $e->getMessage();
	echo $e->getCause();
}

如果物品在30天前交付，您可能在上面的示例代码中看到以下输出

Tracking data are not available for barcode reference XX12345678XX
It is not possible to provide information about events that occurred more than 30 days ago