README

这是一个 HRX WOP API 的库。

使用 HRX-API 库

• __PATH_TO_LIB__ 是 HRX-API 放置的路径。这将加载 HrxApi 命名空间

require __PATH_TO_LIB__ . 'hrx-api/vendor/autoload.php';

验证、检查等。抛出异常并在调用库类时应该用：块包裹

try {
  // ...
} catch (Exception $e) {
  // ...
}

以 add 或 set 开头的任何函数都返回其类，因此函数可以被链式调用。

身份验证

使用提供的用户 $token。它是在创建 API 对象期间调用的。

• 使用以下命令初始化新的 API 库： $api = new API();
• 使用以下命令设置 API 令牌： $api->setToken($token);

API 扩展命令

在初始化 API 类之后，可以更改某些参数。

• 更改超时值： $api->setTimeout(60);
• 启用调试数据返回： $api->setDebug(true);
• 启用连接到测试端点（仅适用于测试令牌）： $api->setTestMode(true);
• 更改测试端点： $api->setTestUrl($url);
• 更改实时端点： $api->setLiveUrl($url);

简单示例

$api = new API();
$api
    ->setToken($token) // Different tokens are used for test and live endpoints
    ->setTimeout(60) // If want change timeout value
    ->setDebug(true) // If want get debug data with function $api->getDebugData()
    ->setTestMode(false) // If want switch between Test/Live mode
    ->setTestUrl($url_test) // If want change test endpoint
    ->setLiveUrl($url_live); // If want change live endpoint

获取位置（v1）- 已弃用

$pickup_locations = $api->getPickupLocations(1, 100); // Get pickup locations. First param - page number, second param - elements per page
$delivery_locations = $api->getDeliveryLocations(1, 100); // Get delivery locations for terminals. First param - page number, second param - elements per page
$courier_$delivery_locations = $api->getCourierDeliveryLocations(); // Get delivery locations for courier.

获取位置（v2）

$pickup_locations = $api->getPickupLocations(1, 100); // Get pickup locations. First param - page number, second param - elements per page
$delivery_locations_countries = $api->getDeliveryLocationsCountries(); // Get countries list of terminal delivery locations.
foreach ( $delivery_locations_countries as $country ) {
  $country_code = $country['country'];
  $endpoint = $country['links']['locations'];
  $delivery_locations = $api->get_delivery_locations_for_country($country_code, 1, $endpoint); // Get delivery locations of country terminals. First param - country code (eg LT), second page number, third endpoint from which to get country terminals (if want to use the endpoint received with the list of countries)
}
$courier_$delivery_locations = $api->getCourierDeliveryLocations(); // Get delivery locations for courier.

查找最近的位置

该库具有一个附加功能，允许在位置列表中查找最近的位置。还可以按最近的位置对列表进行排序。

use HrxApi\NearestLocation;

$address_coordinates = NearestLocation::getCoordinatesByAddress('Street 1, City', 'LT'); // Get address coordinates

$api_nearest_location = new NearestLocation();
$api_nearest_location->setLocationsList($locations_list); // Give locations list to the class. A list must be an array of objects. Each (location) object must have a latitude and longitude property.
$api_nearest_location->setAddressCoordinates($address_coordinates['latitude'], $address_coordinates['longitude']); // Give address coordinates to the class
$api_nearest_location->findNearestLocation(); // Initiate the search for the nearest location

$nearest_location = $api_nearest_location->getNearestLocation(); // Get the nearest location found
$sorted_locations_list = $api_nearest_location->sortLocationsByDistance()->getLocationsList(); // Sort a list of locations by distance (from nearest) and get this list

创建接收器

use HrxApi\Receiver; 允许创建 Receiver 对象。

最低要求配置

use HrxApi\Receiver;

$receiver = new Receiver();

$receiver
  ->setName('Tester') // Receiver name
  ->setEmail('test@test.ts') // Receiver email
  ->setPhone('58000000', "^5[0-9]{6,7}|8[0-9]{7}$"); // Phone number without code and a second parameter is for check the phone value according to the regex specified in delivery location information

通过快递发送时

use HrxApi\Receiver;

$receiver = new Receiver();

$receiver
  ->setName('Tester') // Receiver name
  ->setEmail('test@test.ts') // Receiver email
  ->setPhone('58000000', "^5[0-9]{6,7}|8[0-9]{7}$") // Phone number without code and a second parameter is for check the phone value according to the regex specified in delivery location information
  ->setAddress('Street 1') // Receiver address
  ->setPostcode('46123') // Receiver postcode (zip code)
  ->setCity('Testuva') // Receiver city
  ->setCountry('EE'); // Receiver country code

创建货运

use HrxApi\Shipment; 允许创建 Shipment 对象。

最低要求配置

use HrxApi\Shipment;

$shipment = new Shipment();

$shipment
  ->setReference('REF001') // Package ID or other identifier. Optional.
  ->setComment('Comment') // Comment for shipment. Optional.
  ->setLength(15) // Dimensions values in cm. Must be between the min and max values specified for the delivery location. If min or max value in delivery location is null, then value not have min/max limit
  ->setWidth(15)
  ->setHeight(15)
  ->setWeight(1); // kg

创建订单

use HrxApi\Order; 允许创建 Order 对象。

最低要求配置

use HrxApi\Order;

$order = new Order();

$order
  ->setPickupLocationId('bcaac6c5-3a69-44e1-9e29-809b8150c997') // Pickup location ID retrieved from the API
  ->setDeliveryKind('delivery_location') // Shipping method. Can be one of: "delivery_location" or "courier".
  ->setDeliveryLocation('14fce476-f610-4ff8-a81e-9f6c653ac116') // Delivery location ID retrieved from the API
  ->setReceiver($receiver) // Receiver object
  ->setShipment($shipment); // Shipment object

$order_data = $order->prepareOrderData(); // Organized and prepared data for sending to API

生成订单

所有发送到配送地点的流程语法

use HrxApi\API;
use HrxApi\Receiver;
use HrxApi\Shipment;
use HrxApi\Order;

$api = new API();
$api->setToken($token);

$pickup_locations = $api->getPickupLocations(1, 10);
$delivery_locations = $api->get_delivery_locations_for_country('LT', 1); // Required when shipping to delivery location

$receiver = new Receiver();

$receiver
  ->setName('Tester')
  ->setEmail('test@test.ts')
  ->setPhone('58000000', $delivery_locations[0]['recipient_phone_regexp']);

$shipment = new Shipment();

$shipment
  ->setReference('PACK-12345')
  ->setComment('Comment')
  ->setLength(15) // cm
  ->setWidth(15) // cm
  ->setHeight(15) // cm
  ->setWeight(1); // kg

$order = new Order();

$order
  ->setPickupLocationId($pickup_locations[0]['id'])
  ->setDeliveryKind('delivery_location') // Required when shipping to delivery location
  ->setDeliveryLocation($delivery_locations[0]['id']) // Required when shipping to delivery location
  ->setReceiver($receiver)
  ->setShipment($shipment);
$order_data = $order->prepareOrderData();

$order_response = $api->generateOrder($order_data); // Data sending to the API for shipment generation

所有通过快递发送到接收者地址的流程语法

use HrxApi\API;
use HrxApi\Receiver;
use HrxApi\Shipment;
use HrxApi\Order;

$api = new API();
$api->setToken($token);

$pickup_locations = $api->getPickupLocations(1, 10);
$delivery_locations = $api->getCourierDeliveryLocations();

$receiver_country = 'LT';
$receiver_delivery_location = array();
foreach ( $delivery_locations as $delivery_location ) {
    if ( $delivery_location['country'] == $receiver_country ) {
        $receiver_delivery_location = $delivery_location;
        break;
    }
}

$receiver = new Receiver();

$receiver
  ->setName('Tester')
  ->setEmail('test@test.ts')
  ->setPhone('60000000', $receiver_delivery_location['recipient_phone_regexp'])
  ->setAddress('Street 1') // Required when shipping via courier
  ->setPostcode('46123') // Required when shipping via courier
  ->setCity('Testuva') // Required when shipping via courier
  ->setCountry($receiver_country); // Required when shipping via courier

$shipment = new Shipment();

$shipment
  ->setReference('PACK-12345')
  ->setComment('Comment')
  ->setLength(15) // cm
  ->setWidth(15) // cm
  ->setHeight(15) // cm
  ->setWeight(1); // kg

$order = new Order();

$order
  ->setPickupLocationId($pickup_locations[0]['id'])
  ->setDeliveryKind('courier') // Required when shipping via courier
  ->setReceiver($receiver)
  ->setShipment($shipment);
$order_data = $order->prepareOrderData();

$order_response = $api->generateOrder($order_data); // Data sending to the API for shipment generation

从 API 获取所有订单

$orders_list = $api->getOrders(1, 100); // Get orders. First param - page number, second param - elements per page

从 API 获取单个订单数据

获取订单

$order = $api->getOrder('e161c889-782b-4ba2-a691-13dc4baf7b62'); // Order ID

获取标签（当跟踪号成功生成时）

$label = $api->getLabel('e161c889-782b-4ba2-a691-13dc4baf7b62'); // Order ID

获取退货标签

$return_label = $api->getReturnLabel('e161c889-782b-4ba2-a691-13dc4baf7b62'); // Order ID

获取跟踪事件

$tracking_events = $api->getTrackingEvents('e161c889-782b-4ba2-a691-13dc4baf7b62'); // Order ID

获取公共跟踪信息

• 如果订单在 API 接收的数据中未出错，跟踪号会在订单数据中指示。

$tracking_information = $api->getTrackingInformation('TRK0099999999'); // Tracking number

设置订单就绪状态

就绪状态表示包裹是否已打包、贴上标签并准备好取件。可以在订单具有 new、ready 状态时调用。

$order_ready = $api->changeOrderReadyState('e161c889-782b-4ba2-a691-13dc4baf7b62', true); // Change ready state. First param - order ID, second param - if mark as ready

取消订单

$canceled_order = $api->cancelOrder('e161c889-782b-4ba2-a691-13dc4baf7b62'); // Order ID

调试

如果遇到 API 请求问题，可以获取调试信息以确定问题。首先需要在初始化 API 类之后以及执行一些查询之后激活调试模式，然后可以获取调试信息。

$api = new API();
$api->setToken($token)
    ->setDebug(true); // Enable debug mode

try {
  $response = $api->getOrders(1, 100); // Any request
  $debug_data = $api->getDebugData(); // Debug data if response success
} catch (\Exception $e) {
  $debug_data = $api->getDebugData(); // Debug data if response fail
}

示例

请查看 src/examples/ 中的此 API 库示例。文件 index.php 展示了所有函数。