README

如何使用

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

其中 __PATH_TO_LIB__ 是 itella-api 放置的路径。这将加载 Mijora\Itella 命名空间

大多数值都期望是正确的 - 在某些情况下，如果某些值很重要但没有提供，则将抛出异常。

创建认证对象

$isTest = false;
$auth = new \Mijora\Itella\Auth($user, $pass, $isTest);
$token_array = $auth->$auth->getAuth();

$user - Itella API 用户

$pass - Itella API 密码

$isTest - API是否应使用测试模式（布尔值）

$token_array 将包含错误消息（如果出现问题）或 [access_token, expires, expires_in, token_type] 如果成功。令牌有效期为1小时 - 请使用 expires 键检查此时间，它是令牌过期的 UNIX 时间戳。可以通过传递数组到 Auth 对象而不是使用 getAuth() 请求新令牌。

示例用法

$current_token = load_previously_saved_token_array();
if ($current_token['expires'] <= time()) {
  // Getging new Token
  $new_token_array = $auth->getAuth();
  file_put_contents('token.json', json_encode($new_token_array));
} else {
  // Using saved Token
  $auth->setTokenArr($current_token);
}

创建寄件人

$sender = new \Mijora\Itella\Shipment\Party(\Mijora\Itella\Shipment\Party::ROLE_SENDER);
$sender
  ->setContract('000000')
  ->setName1('TEST Web Shop')
  ->setStreet1('Raudondvario pl. 150')
  ->setPostCode('47174')
  ->setCity('Kaunas')
  ->setCountryCode('LT');

创建收件人

$receiver = new \Mijora\Itella\Shipment\Party(\Mijora\Itella\Shipment\Party::ROLE_RECEIVER);
$receiver
  ->setName1('Testas')
  ->setStreet1('Testo g. 4')
  ->setPostCode('47174')
  ->setCity('Kaunas')
  ->setCountryCode('LT')
  ->setContactName('Testas')
  ->setContactMobile('865412345')
  ->setContactEmail('testas@testutis.lt'); // optional

当发送到取货点（SMARTPOST）时，必须提供额外信息

  ->setName2('Testutis') // if SmartPost, then name of pick-up point is given
  ->setStreet1('Testo g. 4') // if SmartPost, then street address of pick-up point is given
  ->setPostCode('47174') // if SmartPost, then postal code of pick-up point is given

创建订单项目

$item = new \Mijora\Itella\Shipment\GoodsItem(\Mijora\Itella\Shipment\GoodsItem::PRODUCT_COURIER);
$item
  ->addExtraService([3102, 3101]) // Multi
  ->setTrackingNumber('Testas123');

\Mijora\Itella\Shipment\GoodsItem::PRODUCT_COURIER - 选择快递选项时的代码
\Mijora\Itella\Shipment\GoodsItem::PRODUCT_PICKUP - 选择取货点选项时的代码（不允许额外服务）

PRODUCT_COURIER 可用的额外服务

3101 - 货到付款（仅限信用卡），COD 信息必须在 Shipment 对象中设置
3102 - 多件包裹
3104 - 易碎
3166 - 送货前电话
3174 - 超大

在多件包裹的情况下，只需创建多个具有设置多件包裹额外服务的 GoodsItem 对象（以及任何其他所需的服务）。它被视为同一订单，且包裹数量不得超过10个。每个都必须设置不同的跟踪号码。

创建运单

$isTest = false;
$shipment = new \Mijora\Itella\Shipment\Shipment($isTest);
$shipment
  ->setAuth($auth) // previously created Auth object
  ->setSenderId('sender_id') // Itella API user
  ->setReceiverId('ITELLT') // Itella code for Lithuania
  ->setShipmentNumber('TESTNR231') // Shipment/waybill identifier
  ->setShipmentDateTime(date('c')) // when shipment is ready for transport. Format must be ISO 8601, e.g. 2019-10-11T10:00:00+03:00
  ->setSenderParty($sender) // previously created Sender object
  ->setReceiverParty($receiver) // previously created Receiver object
  ->addGoodsItem([$item2, $item2, $item2, $item2]) // array of previously created GoodsItem objects, can also be just GoodsItem onject
  // needed only if COD extra service is used
  ->setBIC('testBIC') // Bank BIC
  ->setIBAN('LT123425678') // Bank account
  ->setValue(100.50) // Total to pay in EUR
  ->setReference($shipment->gereateCODReference('012')); // COD reference,here using function from Shipment class to generate reference code by order ID

要获取运单文档创建时间和序列（用于识别请求）

$documentDateTime = $shipment->getDocumentDateTime();
$sequence = $shipment->getSequence();

一旦提供所有信息，请向 Itella API 服务器发送请求

$result = $shipment->sendShipment();
if (isset($result['error'])) {
  echo '<br>Shipment Failed with error: ' . $result['error_description'];
} else {
  echo '<br>Shipment sent: ' . $result['success_description'];
}

$result 是数组 [error, error_description] 或 [success, success_description]

一旦使用过的跟踪号码不应再次使用。

在测试时，检查生成的 XML 很有用，因为除了 Auth 之外的每个类都有 getXML() 函数，该函数返回 SimpleXMLElement。

echo $sender->getXML()->asXML();
echo $receiver->getXML()->asXML();
echo $item->getXML()->asXML();
echo $shipment->getXML()->asXML();

位置 API

当使用取货点选项时，拥有正确的取货点列表很重要

// Initiate locations object
$itellaPickupPointsObj = new \Mijora\Itella\Locations\PickupPoints('https://locationservice.posti.com/api/2/location');
// it is advised to download locations for each country separately
// this will return filtered pickup points list as array
$itellaLoc = $itellaPickupPointsObj->getLocationsByCountry('LT');
// now points can be stored into file or database for future use
$itellaPickupPointsObj->saveLocationsToJSONFile('test.json', json_encode($itellaLoc));

打印标签

使用 Shipment 类对象生成的标签，因此必须先创建 Shipment 对象。标签打印没有验证，并假设所有提供的信息都是正确的。

$label = new \Mijora\Itella\Pdf\Label($shipment);
$done = $label->printLabel($fileName, $path);

$fileName - 是必须的，例如 'sample.pdf' $path - 可选，保存文件的路径（必须以 / 结尾），如果未提供 $path（null），则 pdf 将在浏览器中显示，否则保存到 $path（在这种情况下 $done 将为 true）。

mijora / itella-api-test

维护者

详细信息