README

介绍

这是一个用于简化 SwipBox 集成的 PHP 客户端库，它允许您快速实现。

您需要 SwipBox 账户才能使用该 API。

索引

• 需求
• 许可协议
• 安装
  • 使用 Composer
  • 手动安装
• 入门指南
• 包裹
  • 创建包裹
  • 激活包裹
  • 激活包裹的标签
  • 取消包裹
• 站点
  • 查找最近的站点
  • 查找活动收藏夹
  • 查找喜欢的站点附近的站点
  • 按邮政编码查找站点
  • 通过取件 ID 获取站点
• 跟踪与追踪
• 错误
  • 错误代码

需求

• 来自 SwipBox 的 GUID。
• PHP 5.3+

许可协议

此库采用 MIT 许可协议。

版权 (C) <2013>

特此授予任何获取本软件及其相关文档文件（以下简称“软件”）副本的人免费使用该软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本，并允许软件的接收者为此目的进行操作，但须遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性保证。在任何情况下，作者或版权所有者均不对因软件或软件的使用或其它交易而产生的任何索赔、损害或其他责任负责，无论此类索赔、损害或其他责任是基于合同、侵权或其他原因。

安装

Composer

要使用 Composer（推荐）安装，请将 repox/swipbox 包添加到您的 composer.json 文件中。

{
    "require": {
        "repox/swipbox": "1.1.*"
    }
}

通过包含 vendor/autoload.php 来启用自动加载。

手动安装

下载最新的 稳定标签，并将其中的 src/ 解压到一个文件夹中，然后包含文件以供使用。

<?php
include 'Swipbox/Client.php';
include 'Swipbox/Exception.php';

手动安装时，您还需要下载 Guzzle。
我建议下载 Guzzle Phar 并将其包含在内。

include 'guzzle.phar';

入门指南

当您获得了 SwipBox 账户的 GUID 后，您首先需要实例化一个 SwipBox 客户端。

<?php
use \Swipbox\Client;

$swipbox = new Client('YOUR-GUID-GOES-HERE');

如果您正在测试您的实现，您可以在构造函数中添加一个布尔值 true 作为第二个参数。

<?php
use \Swipbox\Client;

$swipbox = new Client('YOUR-GUID-GOES-HERE', true);

包裹

创建包裹

使用 create 方法，我们可以通过传递一个参数数组作为第一个参数快速创建一个包裹。以下参数是必需的。

以下参数是可选的。

示例

try
{

	$parcel = $swipbox->create( array(
		'first_name' => 'Niels',
		'last_name' => 'Nielsen',
		'address_1' => 'Fantastisk vej 12',
		'city' => 'København N',
		'zip' => 2200,
		'country' => 'DK',
		'email' => 'niels@example.com',
		'mobile_number' => '12345678',
		'parcel_size' => 1,
		'test_parcel' => 0,
		'return_parcel' => 0,
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$parcel 现在包含一个包含包裹ID和包裹类型ID的多维数组。

echo $parcel['parcels'][0]['parcel_id']; // Integer identifying the Parcel
echo $parcel['parcels'][0]['parcel_type']; // Integer identifying the Parcel type (1 for normal Parcel, 2 for return Parcel)

如果您想通过将 1 传递给 return_parcel 参数来创建一个退货包裹，您可以在多维数组的索引 1 中检索信息。

// The normal parcel
echo $parcel['parcels'][0]['parcel_id'];
echo $parcel['parcels'][0]['parcel_type'];

// The return parcel
echo $parcel['parcels'][1]['parcel_id'];
echo $parcel['parcels'][1]['parcel_type'];

激活包裹

包裹必须在7天内激活。否则，包裹将过期。

要激活包裹，您可以使用 activate 方法，并将参数数组作为第一个参数传递。

以下参数是必需的。

激活包裹时，收件人将收到邮件和短信通知。

示例

try {

	$pdf_label = $swipbox->activate( array(
		'parcel_id' => 27181,
		'format' => 0,
		'output' => 0,
		
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$pdf_label 现在将包含二进制数据（因为我们传递了 0，这表示PDF格式），这是包裹标签。
您可以通过在浏览器中回显数据并使用适当的头信息来查看标签以供打印。

header('Content-Type: application/pdf');
echo $pdf_label;

激活包裹的标签

在需要时获取包裹数据或标签很有用。

要获取包裹标签或信息，您可以使用 get_label 方法，并将参数数组作为第一个参数传递。

以下参数是必需的。

激活包裹时，收件人将收到邮件和短信通知。

示例

try {

	$pdf_label = $swipbox->get_label( array(
		'parcel_id' => 27181,
		'format' => 0,
		'output' => 0,
		
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$pdf_label 现在将包含二进制数据（因为我们传递了 0，这表示PDF格式），这是包裹标签。
您可以通过在浏览器中回显数据并使用适当的头信息来查看标签以供打印。

header('Content-Type: application/pdf');
echo $pdf_label;

取消包裹

使用此功能取消状态为 '已创建' 或 '已激活' 的包裹。
注意：目前，您无法从尚未激活的包裹中获取取消包裹所需的条形码！

以下参数是必需的。

可以通过获取包裹标签（例如，使用JSON格式）来检索条形码。
一个完整的示例将类似于以下示例

示例

try {
	
	$json_label = $swipbox->get_label( array(
		'parcel_id' => 27181,
		'format' => 2,
		'output' => 0,
		
	));

	$result = $swipbox->cancel(array(
		'barcode' => $json_label['label']['barcode'],
	));
		
}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

这应该可以成功取消包裹。

站点

站点是包裹的取货地点。
创建包裹时，您可以提供一个可选的 pick_up_id 参数，指定客户希望取货的目的地。

以下方法是用于定位站点的。

查找最近站点

要获取距离指定地址最近的站点，您可以通过传递参数数组作为第一个参数使用 find_nearest 方法。

以下参数是必需的。

以下参数是可选的。

示例

try {

	$result = $swipbox->find_nearest(array(
		'address_1' => 'Rosenvangs Alle 12',
		'city' => 'Aarhus',
		'zip' => '8000',
		'country' => 'DK',
		'parcel_size' => 1,
		'no_of_stations' => 5,
	));
		
}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$result 将包含一个包含5个站点的多维数组，按距离指定地址的最近顺序排序。

查找活跃收藏

要获取特定客户的活动收藏站点，您可以通过传递参数数组作为第一个参数使用 find_active_favorites 方法。

以下参数是必需的。

示例

try {

	$result = $swipbox->find_active_favorites(array(
		'email' => 'niels@example.com',
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$result 将包含一个包含5个站点的多维数组。

查找靠近收藏的站点

要获取靠近特定客户第一个活动收藏站点的站点，您可以通过传递参数数组作为第一个参数使用 find_near_to_favorite 方法。

以下参数是必需的。

以下参数是可选的。

示例

try {

	$result = $swipbox->find_near_to_favorite(array(
		'email' => 'niels@example.com',
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$result 将包含一个包含3个站点的多维数组。

通过邮编查找站点

要获取特定邮编的站点，您可以通过传递参数数组作为第一个参数使用 find_by_zip 方法。

以下参数是必需的。

示例

try {

	$result = $swipbox->find_by_zip(array(
		'zip' => '8000',
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$result 将包含一个包含指定邮编内所有站点的多维数组。

通过取货点ID获取站点

要获取特定站点的详细信息，您可以通过传递参数数组作为第一个参数使用 get_station_by_id 方法。

以下参数是必需的。

示例

try {

	$result = $swipbox->get_station_by_id(array(
		'pick_up_id' => '1259',
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$result 将包含一个包含您通过取货ID指定的站点的详细信息的多维数组。

追踪包裹

跟踪和追溯功能可以识别包裹的事件。
您可以通过传递参数数组作为第一个参数使用 track 方法。

以下参数是必需的。

示例

try {

	$json_label = $swipbox->get_label( array(
		'parcel_id' => 27181,
		'format' => 2,
		'output' => 0.
	));	

	$track = $swipbox->track(array(
			'barcode' => $json_label['label']['barcode'],
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

$track 将包含一个包含包裹跟踪记录的所有事件的详细信息的多维数组。

错误 - 异常处理

通过输出异常信息，您将获得SwipBox返回的消息。

示例

try {

	$result = $swipbox->find_by_zip(array(
		'non_existing_parameter' => '8000',
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getMessage();
}

这将导致SwipBox客户端抛出异常 - 如示例中所示处理它，结果将是输出错误消息（在这种情况下将是“缺少Zip”）。

错误代码

也可以处理错误代码，因为这些与错误消息相关联。

示例

try {

	$result = $swipbox->find_by_zip(array(
		'non_existing_parameter' => '8000',
	));

}
catch( \Swipbox\Exception $e)
{
	echo $e->getCode();
}

与之前相同的错误，但是您得到的是错误代码14，这对应于之前相同的消息。

以下表格显示了可能的错误代码和消息。