README

这是一个用于Pakettikauppa API库的包装库。

使用composer安装Itella-API

composer require mijora/itella-api

使用Itella-API库

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

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

验证、检查等抛出ItellaException，对库类的调用应包含在：块中

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

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

身份验证

使用提供的user和secret。在创建运输时调用。

创建发件人

Party::ROLE_SENDER用于识别发件人。

最小要求设置

发件人必须设置合同！
电话号码必须是国际格式，库将尝试修复给定的号码或抛出ItellaException。

use Mijora\Itella\Shipment\Party;
use Mijora\Itella\ItellaException;

try {
  $sender = new Party(Party::ROLE_SENDER);
  $sender
    ->setContract('000000')               // API contract number given by Itella
    ->setName1('TEST Web Shop')           // sender name
    ->setStreet1('Test str. 150')         // sender address
    ->setPostCode('47174')                // sender post code
    ->setCity('Kaunas')                   // sender city
    ->setCountryCode('LT')                // sender country code in ISO 3166-1 alpha-2 format (two letter code)
    ->setContactMobile('+37060000000')    // sender phone number in international format
    ->setContactEmail('sender@test.lt');  // sender email
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

创建收件人

Party::ROLE_RECEIVER用于识别收件人。

最小要求设置

电话号码必须是国际格式，库将尝试修复给定的号码或抛出ItellaException。

use Mijora\Itella\Shipment\Party;
use Mijora\Itella\ItellaException;

try {
  $receiver = new Party(Party::ROLE_RECEIVER);
  $receiver
    ->setName1('Testas')                    // receiver name
    ->setStreet1('None str. 4')             // receiver address
    ->setPostCode('47174')                  // receiver post code
    ->setCity('Kaunas')                     // receiver city
    ->setCountryCode('LT')                  // receiver country code in ISO 3166-1 alpha-2 format (two letter code)
    ->setContactMobile('+37060000000')      // receiver phone number in international format
    ->setContactEmail('receiver@test.lt');  // receiver email
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

禁用电话检查/修复

默认情况下，Party类检查提供的电话是否与设置的格式匹配（如果国家是立陶宛，则期望看到立陶宛的电话号码），并在需要时尝试将电话号码修复为符合国际标准。如果不需要此类检查/修复（电话号码来自不同的国家），则可以通过在Party类上使用disablePhoneCheck函数来禁用。

注意：即使检查/修复被禁用，Party类仍然会检查提供的号码是否为国际格式。

示例

use Mijora\Itella\Shipment\Party;
use Mijora\Itella\ItellaException;

try {
  $receiver = new Party(Party::ROLE_RECEIVER);
  $receiver
    ->setName1('Testas')
    ->setStreet1('None str. 4')
    ->setPostCode('47174')
    ->setCity('Kaunas')
    ->disablePhoneCheck()                   // disable phone checking / fixing
    ->setCountryCode('LT')                  // country is set to Lithuania
    ->setContactMobile('+37120000000')      // but phone number is Latvian
    ->setContactEmail('receiver@test.lt');
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

注意国家代码设置为LT（立陶宛），而联系人手机号码为拉脱维亚。

创建订单项目

如果使用多包裹附加服务，只需创建多个GoodsItem并将它们注册到运输中。

use Mijora\Itella\Shipment\GoodsItem;
use Mijora\Itella\ItellaException;

try {
  $item = new GoodsItem();
  $item
    ->setGrossWeight(0.5)       // kg, optional
    ->setVolume(0.5)            // m3, optional
    ->setContentDesc('Stuff');  // optional package content description
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

创建附加服务

Shipment::PRODUCT_COURIER可用的附加服务

必须手动设置
- 3101 - 货到付款（仅限信用卡）。需要包含此信息的数组
  - amount => 应付的欧元金额，
  - account => 银行账户（IBAN），
  - codbic => 银行BIC，
  - reference => COD参考，可以使用Helper::generateCODReference($id)，其中$id可以是订单ID。
- 3104 - 易碎
- 3166 - 交货前电话
- 3174 - 超大
将自动设置
- 3102 - 多包裹，如果运输有1个以上但不超过10个GoodsItem，将自动设置。需要包含此信息的数组
  - count => 已注册GoodsItem的总数。

Shipment::PRODUCT_PICKUP可用的附加服务

必须手动设置
- 3101 - 货到付款（仅限信用卡）。需要包含此信息的数组
  - amount => 应付的欧元金额，
  - account => 银行账户（IBAN），
  - codbic => 银行BIC，
  - reference => COD参考，可以使用Helper::generateCODReference($id)，其中$id可以是订单ID。
将自动设置
- 3201 - 提货点，当提货点ID（来自位置API的pupCode）注册到运输中时将自动设置。需要包含此信息的数组
  - pickup_point_id => 提货点pupCode。

尝试设置对设置的产品代码不可用的附加服务将抛出ItellaException。

创建不需要额外信息的附加服务（例如，易碎）

use Mijora\Itella\Shipment\AdditionalService;
use Mijora\Itella\ItellaException;

try {
  $service_fragile = new AdditionalService(AdditionalService::FRAGILE);
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

创建COD附加服务

use Mijora\Itella\Shipment\AdditionalService;
use Mijora\Itella\Helper;
use Mijora\Itella\ItellaException;

try {
  $service_cod = new AdditionalService(
    AdditionalService::COD,
    array(
      'amount'    => 100,
      'codbic'    => 'XBC0101',
      'account'   => 'LT100000000000',
      'reference' => Helper::generateCODReference('666')
    )
  );
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

创建运输

可用产品代码

Shipment::PRODUCT_COURIER = 2317
Shipment::PRODUCT_PICKUP = 2711

运输可以是其中一个，但不能同时是两个。请参阅附加服务，了解每个产品代码可用的服务。

应首先设置运输产品代码。

在注册商品项时，可以使用$shipment->addGoodsItem(GoodsItem)一次注册一个，或者通过数组传递多个，使用$shipment->addGoodsItems(array(GoodsItem, GoodsItem))。

在注册附加服务时，可以使用$shipment->addAdditionalService(AdditionalService)一次注册一个，或者通过数组传递多个，使用$shipment->addAdditionalServices(array(AdditionalService, AdditionalService))。

快递运输示例（使用上述示例中的变量）

use Mijora\Itella\Shipment\Shipment;
use Mijora\Itella\ItellaException;

try {
  $shipment = new Shipment($p_user, $p_secret);
  $shipment
    ->setProductCode(Shipment::PRODUCT_COURIER) // product code, should always be set first
    ->setShipmentNumber('Test_ORDER')           // shipment number, Order ID is good here
    ->setSenderParty($sender)                   // Register Sender
    ->setReceiverParty($receiver)               // Register Receiver
    ->addAdditionalServices(                    // Register additional services
      array($service_fragile, $service_cod)
    )
    ->addGoodsItems(                            // Register GoodsItem
      array($item)
    )
    ->setComment('Comment about shipment')      // Comment string
  ;
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

取货点运输示例（使用上述示例中的变量）

use Mijora\Itella\Shipment\Shipment;
use Mijora\Itella\ItellaException;

$user = 'API_USER';     // API user
$secret = 'API_SECRET'; // API secret / password

try {
  $shipment = new Shipment($user, $secret);
  $shipment
    ->setProductCode(Shipment::PRODUCT_PICKUP)  // product code, should always be set first
    ->setShipmentNumber('Test_ORDER')           // shipment number, Order ID is good here
    ->setSenderParty($sender)                   // Register Sender
    ->setReceiverParty($receiver)               // Register Receiver
    ->setPickupPoint('071503201')               // Register pickup point pupCode
    ->addAdditionalService($service_cod)        // Register additional services
    ->addGoodsItem($item)                       // Register GoodsItem (this adds just one)
    ->setComment('Comment about shipment')      // Comment string
  ;
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

一旦提供所有信息，就可以注册运输。如果注册成功，将返回跟踪号码。在此示例中，显示返回的跟踪号码，通常它会被保存到订单中，以供以后请求运输标签PDF使用。

try {
  $tracking_number = $shipment->registerShipment();
  echo "Shipment registered:\n <code>" . $tracking_number . "</code>\n";
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

如果需要检查请求的XML，可以使用asXML()。

try {
  $xml = $shipment->asXML();
  file_put_contents('request.xml', $xml);
} catch (ItellaException $e) {
  // Handle validation exceptions here
}

打印标签

可用的标签尺寸

Shipment::LABEL_SIZE_A5 = A5
Shipment::LABEL_SIZE_107X225 = 107x225

建议始终在需要时下载标签。为此，使用Shipment类。结果将是base64编码的PDF文件。如果传递多个跟踪号码（数组中），PDF将包含所有这些标签。要从两个不同用户的PDF中获取和合并标签，请参阅get-merge-labels.php示例。

$shipment->downloadLabels($track, $size = null)的次要参数$size是可选的，并且仅在posti/itella环境在pakettikauppa侧实现后才会生效。

重要：如果跟踪号码来自不同的用户，它将被忽略。

use Mijora\Itella\Shipment\Shipment;
use Mijora\Itella\ItellaException;

$user = 'API_USER';     // API user
$secret = 'API_SECRET'; // API secret / password

$track = 'JJFI12345600000000001';
// or if need multiple in one pdf
// $track = ['JJFI12345600000000001', 'JJFI12345600000000010'];

try {
  $shipment = new Shipment($user, $secret);
  $pdf_base64 = $shipment->downloadLabels($track, Shipment::LABEL_SIZE_A5);
  $pdf = base64_decode($pdf_base64);
  if ($pdf) { // check if its not empty
    if (is_array($track)) {
      $track = 'labels';
    }
    $path = $track . '.pdf';
    $is_saved = file_put_contents($path, $pdf);
    $filename = 'labels.pdf';
    if (!$is_saved) { // make sure it was saved
      throw new ItellaException("Failed to save label pdf to: " . $path);
    }

    // make sure there is nothing before headers
    if (ob_get_level()) ob_end_clean();
    header("Content-Type: application/pdf; name=\"{$filename}\"");
    header("Content-Transfer-Encoding: binary");
    // disable caching on client and proxies, if the download content vary
    header("Expires: 0");
    header("Cache-Control: no-cache, must-revalidate");
    header("Pragma: no-cache");
    readfile($path);
  } else {
    throw new ItellaException("Downloaded label data is empty.");
  }
} catch (ItellaException $e) {
  echo "Exception: <br>\n" . $e->getMessage() . "<br>\n";
}

上述示例检查响应不为空（如果跟踪号码错误，它仍然返回空响应），并将其保存到文件中，然后加载到浏览器中。

位置API

当使用取货点选项时，拥有正确的取货点列表很重要。同时，当创建发送到取货点的运输时，将需要取货点ID。

use Mijora\Itella\Locations\PickupPoints;

$pickup = new 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
$itella_loc = $pickup->getLocationsByCountry('LT');
// now points can be stored into file or database for future use
$pickup->saveLocationsToJSONFile('itella_locations_lt.json', json_encode($itella_loc));

运单生成

默认情况下，生成运单时使用英文字符串 - 可以传递翻译。

运单构造函数接受额外的参数

$timestamp => 默认 false，并将分配当前系统时间。可以在此处传递Unix时间戳，以在运单上的标志上方显示特定日期。
$dateFormat => 默认 'Y-m-d'。日期格式作为字符串，可以使用PHP date()函数支持的任何内容https://php.ac.cn/manual/en/function.date

需要包含此信息的数组数组

track_num => 跟踪号码（字符串），
weight => 重量（如有）(浮点数)，
delivery_address => 递送地址（字符串）。

有关其他选项，请参阅以下示例

use Mijora\Itella\Pdf\Manifest;

$items = array(
  array(
    'track_num' => 'JJFItestnr00000000015',
    'weight' => 1,
    'delivery_address' => 'Test Tester, Example str. 6, 44320 City, LT',
  ),
);

// If need to translate default english
$translation = array(
  'sender_address' => 'Sender address:',
  'nr' => 'No.',
  'track_num' => 'Tracking number',
  'date' => 'Date',
  'amount' => 'Quantity',
  'weight' => 'Weight (kg)',
  'delivery_address' => 'Delivery address',
  'courier' => 'Courier',
  'sender' => 'Sender',
  'name_lastname_signature' => 'name, surname, signature',
);

$manifest = new Manifest();
$manifest
  ->setStrings($translation) // set translation
  ->setSenderName('TEST Web Shop') // sender name
  ->setSenderAddress('Shop str. 150') // sender address
  ->setSenderPostCode('47174') // sender postcode
  ->setSenderCity('Kaunas') // sender city
  ->setSenderCountry('LT') // sender country code
  ->addItem($items) // register item list
  ->setToString(true) // if requires pdf to be returned as string set to true (default false)
  ->setBase64(true) // when setToString is true, this one can set if string should be base64 encoded (default false)
  ->printManifest('manifest.pdf', 'PATH_TO_SAVE'); // set filename as first argument and path where to save it if setToStringis false

调用快递

要调用快递，必须生成运单（与base64编码的PDF配合良好）。CallCourier使用mail() php函数。这意味着 - 即使邮件报告发送成功，也不能保证邮件已发送。

use Mijora\Itella\CallCourier;
use Mijora\Itella\ItellaException;
use Mijora\Itella\Pdf\Manifest;

$manifest = new Manifest();
$manifest_string = $manifest
  /*
  See previous examples on how to create manifest, here only show last couple settings to get base64 string
  */
  ->setToString(true)
  ->setBase64(true)
  ->printManifest('manifest.pdf')
;

$sendTo = 'test@test.com'; // email to send courier call to
try {
  $caller = new CallCourier($sendTo);
  $result = $caller
    ->setSenderEmail('shop@shop.lt') // sender email
    ->setSubject('E-com order booking') // currently it must be 'E-com order booking'
    ->setPickUpAddress(array( // strings to show in email message
      'sender' => 'Name / Company name',
      'address' => 'Street, Postcode City, Country',
      'contact_phone' => '860000000',
    ))
    ->setAttachment($manifest_string, true) // attachment is previously generated manifest, true - means we are passing base64 encoded string
    ->callCourier() // send email
  ;
  if ($result) {
    echo 'Email sent to: <br>' . $sendTo;
  }
} catch (ItellaException $e) { // catch if something goes wrong
  echo 'Failed to send email, reason: ' . $e->getMessage();
}

调用快递 - 在开发中