firstred/myparcelnl-sdk

此包已被废弃，不再维护。没有建议的替代包。

此包通过API发送和接收MyParcel的数据。

维护者

详细信息

github.com/firstred/myparcelnl-sdk

主页

源代码

安装: 131

依赖项: 0

建议者: 0

安全性: 0

星标: 0

关注者: 1

分叉: 12

dev-master 2019-08-22 21:20 UTC

Requires

Requires (Dev)

GPL-3.0-or-later 1cbca7537a488204267aeece60422f67e889e8ae

This package is auto-updated.

Last update: 2020-01-02 18:05:51 UTC

README

这是MyParcel PHP库的PHP 5.3.3+非官方端口。

如果您可以运行更高版本的PHP，请避免使用此非官方端口！

MyParcel SDK

此SDK使用PHP连接到MyParcel API。

内容

安装

要求

MyParcel SDK适用于PHP版本^5.3 || ^7.0。需要安装PHP cURL扩展。

使用Composer安装

此SDK使用Composer。Composer是PHP中的依赖管理工具。它允许您声明项目所依赖的库，并且它会为您管理（安装/更新）它们。有关如何使用/安装Composer的更多信息，请访问https://getcomposer.org.cn/

要将MyParcel SDK安装到您的项目中，只需使用以下命令：

$ composer require myparcelnl/sdk

不使用Composer安装

也可以在不使用Composer安装的情况下使用SDK。

您可以从项目的发布页面下载zip文件。

  1. 下载包（SDKvx.x.x.zip）。
  2. 解压缩下载的.zip文件，并将vendor目录上传到您的服务器。
  3. 需要src/AutoLoader.php
  4. 现在您可以在项目中使用SDK了！

快速开始和示例

将以下行添加到您的项目中，以导入创建托运单所需的SDK类。

use MyParcelNL\Sdk\src\Helper\MyParcelCollection;
use MyParcelNL\Sdk\src\Model\Repository\MyParcelConsignmentRepository;

创建一个托运单

此示例仅使用创建托运单和下载其标签所需的必需方法。

$consignment = (new MyParcelConsignmentRepository())
    ->setApiKey('api_key_from_MyParcel_backoffice')
    ->setReferenceId('Order 146')
    ->setCountry('NL')
    ->setPerson('Piet Hier')
    ->setFullStreet('Plein 1945 55b')
    ->setPostalCode('2231JE')
    ->setCity('Amsterdam')
    ->setEmail('piet.hier@test.nl');

$myParcelCollection = (new MyParcelCollection())
    ->addConsignment($consignment)
    ->setPdfOfLabels()
    ->downloadPdfOfLabels();

创建多个托运单

此示例通过将它们添加到一个MyParcelCollection()中创建多个托运单，然后创建并下载包含所有标签的PDF。

// Create the collection before the loop
$myParcelCollection = (new MyParcelCollection())
    ->setUserAgent('name_of_cms', '1.0');

// Loop through your shipments, adding each to the same MyParcelCollection()
foreach ($yourShipments as $yourShipment) {

    $consignment = (new MyParcelConsignmentRepository())
        ->setApiKey('api_key_from_MyParcel_backoffice')
        ->setReferenceId($yourShipment['reference_id']) // Note: Make sure every shipment gets a unique reference ID
        ->setPerson($yourShipment['name'])
        ->setPostalCode($yourShipment['postal_code'])
        ->setFullStreet($yourShipment['full_street'])
        ->setCity($yourShipment['city']);

    // Add each consignment to the collection created before
    $myParcelCollection
        ->addConsignment($consignment);
}

标签格式和位置

在创建PDF或下载链接时，选择输出标签为A4或A6，请使用setPdfOfLabels($positions)和setLinkOfLabels($positions)中的$positions参数。

$positions的示例值

A4:            A6:
┏━━━━━┳━━━━━┓  ┏━━━━━┓
┃  1  ┃  2  ┃  ┃  x  ┃
┣━━━━━╋━━━━━┫  ┗━━━━━┛
┃  3  ┃  4  ┃
┗━━━━━┻━━━━━┛
  1. 1：默认值。输出A4，从左上角开始。
  2. false：输出A6格式
  3. [1,4]：定义A4纸上的标签位置。仅适用于第一页，后续页面将使用默认定位（1,2,3,4）

更多信息：[链接](https://myparcelnl.github.io/api/#6_F)

包裹类型和选项

使用setPackageType($type)设置包裹类型。之后使用getPackageType()获取。有关不同类型包裹的详细信息：[链接](https://myparcelnl.github.io/api/#6_A_1)

1：包裹

这是默认的包裹类型。必须显式设置以启用其他发货选项。适用于NL、EU和全球发货。

2：邮箱包裹

此包裹类型仅适用于适合邮箱的NL发货。它不支持附加选项。注意：如果您仍然带有附加选项发出请求，请记住您需要支付比必要更多的费用！

3：信件

此包裹类型适用于NL、EU和全球发货。此发货的标签为未付款，这意味着您需要向邮局/快递公司支付发送此信件/包裹的费用。因此，它不支持附加选项。

4：数字邮票

此包裹类型仅适用于NL发货，不支持任何附加选项。其价格是根据使用setPhysicalProperties()设置的包裹重量计算的。

    ->setPackageType(4)
    ->setPhysicalProperties(['weight' => 300]); // weight in grams (required)

注意：此发货将在运输状态2（待处理 - 已注册）的发票上显示，而不是其他所有发货类型，它们不会在运输状态3之前显示。了解更多：[链接](https://myparcelnl.github.io/api/#6_A_1)

包裹选项

这些选项仅适用于包裹类型1（包裹）。

可用选项

  • only_recipient：仅在预定收件人的地址交付包裹。此选项对于晨间和晚间递送类型是必需的。
    • 设置：setOnlyRecipient(true)
    • 获取：isOnlyRecipient()
  • signature：收件人必须为包裹签名。此选项对于取件和取件快递递送类型是必需的。
    • 设置：setSignature(true)
    • 获取：isSignature()
  • return：当收件人不在家时，将包裹退回给发件人。
    • 设置：setReturn(true)
    • 获取：isReturn()
  • large_format：如果包裹尺寸在100 x 70 x 50和175 x 78 x 58厘米之间，则必须指定此选项。如果承运人扫描的尺寸表明此包裹为大尺寸，并且未指定，则它将在计费过程中添加到发货中。此选项也适用于EU发货。
    • 设置：setLargeFormat(true)
    • 获取：isLargeFormat()
  • insurance：此选项允许对发货进行一定金额的保险。NL发货可以保额为5000欧元。EU发货必须保额为500欧元。全球发货必须保额为200欧元。当对NL发货进行保险时，以下发货选项是强制性的：only_recipient和signature。
    • 集合： setInsurance(250)（金额以欧元计）
    • 获取： getInsurance()

更多信息： https://myparcelnl.github.io/api/#6_A_3

从托运单中检索数据

大多数具有 set...() 方法的属性也具有 get...() 方法来检索数据。在此处查看托运单的所有方法。

$consignment = new MyParcelConsignmentRepository();

echo $consignment->getFullStreet();
echo $consignment->getPerson();
echo $consignment->getPhone();
echo $consignment->getStreet();
// etc...

获取状态

在 setPdfOfLabels()、setLinkOfLabels() 和 createConcepts() 之后，您可以获取状态。

$status = $consignment->getStatus();

获取条码

在 setPdfOfLabels() 和 setLinkOfLabels() 之后，条码可用。

$barcode = $consignment->getBarcode();

创建和下载标签

使用 setPdfOfLabels($position) 创建并直接下载 PDF，其中 $positions 是 标签位置 值。

$myParcelCollection
    ->setPdfOfLabels()
    ->downloadPdfOfLabels(false); // Opens pdf "inline" by default, pass false as argument to download file

使用 setLinkOfLabels($position) 创建并回显到 PDF 的下载链接，其中 $positions 是 标签位置 值。

echo $myParcelCollection
    ->setLinkOfLabels($positions)
    ->getLinkOfLabels();

更多信息：[链接](https://myparcelnl.github.io/api/#6_F)

类及其方法列表

这是 SDK 中所有类及其可用方法的列表。

模型

MyParcelNL/Sdk/src/Model

MyParcelConsignment

⚠️ 通过 \MyParcelNL\Sdk\src\Model\Repository\MyParcelConsignmentRepository（它扩展了 MyParcelConsignment）访问这些方法。

MyParcelNL/Sdk/src/Model/MyParcelConsignment.php

$consignment = (new \MyParcelNL\Sdk\src\Model\Repository\MyParcelConsignmentRepository())
    ->setApiKey('api_key_from_MyParcel_backoffice')
    ->setReferenceId('Order 1203')

    // Recipient/address: https://myparcelnl.github.io/api/#7_B
    ->setPerson('Piet Hier')    // Name
    ->setEmail('test@test.nl')  // E-mail address
    ->setPhone('+31 612345678') // Phone number
    ->setCompany('Piet BV')     // Company

    ->setFullStreet('Plein 1945 55b') // Street, number and suffix in one line
    // OR send the street data separately:
    ->setStreet('Plein 1945') / Street
    ->setNumber((string)55)   // Number
    ->setNumberSuffix('b')    // Suffix

    ->setCity('Amsterdam')    // City
    ->setPostalCode('2231JE') // Postal code
    ->setCountry('NL')        // Country

    // Available package types:
    // 1: Package (default)
    // 2: Mailbox package
    // 3: Letter
    // 4: Digital stamp
    ->setPackageType(1)

    // Options (https://myparcelnl.github.io/api/#6_A_3)
    ->setOnlyRecipient(false)   // Deliver the package only at address of the intended recipient. This option is required for Morning and Evening delivery types.
    ->setSignature(true)        // Recipient must sign for the package. This option is required for Pickup and Pickup express delivery types.
    ->setReturn(true)           // Return the package to the sender when the recipient is not home.
    ->setLargeFormat(false)     // Must be specified if the dimensions of the package are between 100x70x50 and 175x78x58 cm.
    ->setInsurance(250)         // Allows a shipment to be insured up to certain amount. Only packages (package type 1) can be insured.

    ->setLabelDescription('Order 10034') // This description will appear on the shipment label for non-return shipments.

    // Delivery: https://myparcelnl.github.io/api/#8
    ->setDeliveryType()
    ->setDeliveryDate()
    ->setDeliveryRemark()

    // Set pickup location
    ->setPickupLocationName('Supermarkt')
    ->setPickupStreet('Straatnaam')
    ->setPickupNumber('32')
    ->setPickupPostalCode('1234 AB')
    ->setPickupCity('Hoofddorp')

    // Physical properties
    ->setPhysicalProperties(['weight' => 73]) // Array with physical properties of the shipment. Currently only used to set the weight in grams for digital stamps (which is required)

    // Non-EU shipment attributes: see https://myparcelnl.github.io/api/#7_E
    ->setInvoice()
    ->setContents()
    ->addItem();

// Get attributes from consignment
$consignment
    ->getApiKey()
    ->getReferenceId()
    ->getBarcode() // Barcode is available after using setLinkOfLabels() or setPdfOfLabels() on the MyParcelCollection the consignment has been added to

    ->getLabelDescription()
    ->getMyParcelConsignmentId()
    ->getShopId()
    ->getStatus()

    // Recipient info
    ->getPerson()
    ->getEmail()
    ->getPhone()
    ->getCompany()

    // It doesn't matter whether you used setFullStreet() or set all parts separately
    ->getStreet()
    ->getStreetAdditionalInfo()
    ->getNumber()
    ->getNumberSuffix()
    ->getPostalCode()
    ->getCity()
    ->getCountry()

    // Package type
    ->getPackageType()

    // Get value of options
    ->isOnlyRecipient()
    ->isSignature()
    ->isReturn()
    ->isLargeFormat()
    ->getInsurance()

    // Get pickup location info
    ->getPickupLocationName()
    ->getPickupStreet()
    ->getPickupNumber()
    ->getPickupPostalCode()
    ->getPickupCity()

    // Delivery
    ->getDeliveryDate()
    ->getDeliveryRemark()
    ->getDeliveryType()

    // Physical properties (digital stamps or non-EU shipments)
    ->getPhysicalProperties()

    // Non-EU attributes
    ->getInvoice()
    ->getContents()
    ->getItems();

MyParcelCustomsItem

此对象嵌入在 MyParcelConsignment 对象中，用于全球运输，对于非欧盟运输是强制性的。

MyParcelNL/Sdk/src/Model/MyParcelCustomsItem.php

  ->setAmount(3) // Amount of items in the package

  // ISIC/IDEP code (https://www.cbs.nl/nl-nl/deelnemers-enquetes/deelnemers-enquetes/bedrijven/onderzoek/lopend/internationale-handel-in-goederen/idep-codelijsten)
  ->setClassification(0111) // Example: 0111 = "Growing of cereals (except rice), leguminous crops and oil seeds"
  ->setCountry('NL') // Country of origin
  ->setDescription('Cereal grains')
  ->setItemValue(["amount" => 200, "currency" => "EUR"]) // Must be array with amount and currency like in the example
  ->setWeight() // The total weight for these items in whole grams. Between 0 and 20000 grams.

  ->getAmount()
  ->getClassification()
  ->getCountry()
  ->getDescription()
  ->getItemValue()
  ->getWeight()

  ->isFullyFilledItem()

MyParcelRequest

此模型表示一个请求

MyParcelNL/Sdk/src/Model/MyParcelRequest.php

  ->sendRequest()
  ->setRequestParameters()
  ->setUserAgent()

  ->getError()
  ->getResult()
  ->getUserAgent()
  ->getUserAgentFromComposer()

Repository\MyParcelConsignmentRepository

MyParcel 托运单的存储库。

MyParcelNL/Sdk/src/Model/Repository/MyParcelConsignmentRepository.php

  ->setFullStreet('Street 23b, 1234 AB City')

  ->apiDecode()
  ->apiEncode()
  ->encodeReturnShipment()

  // Convert pickup data from checkout
  // You can use these if you use the following code in your checkout: https://github.com/myparcelnl/checkout
  ->setDeliveryDateFromCheckout()
  ->setPickupAddressFromCheckout()

  ->getDeliveryTypeFromCheckout()

  ->getFullStreet()
  ->getTotalWeight()

  ->isCdCountry()
  ->isCorrectAddress()
  ->isEuCountry()

辅助工具

MyParcelNL/Sdk/src/Helper

MyParcelCollection

存储所有数据以与 MyParcel API 通信。

MyParcelNL/Sdk/src/Helper/MyParcelCollection.php

    ->addConsignment() // Add consignment to collection

    // Get consignments from the collection
    ->getConsignments()
    ->getConsignmentByApiId()
    ->getConsignmentByReferenceId()

    ->clearConsignmentsCollection() // Clear the collection

    ->createConcepts() // Create concept shipment in the MyParcel Backoffice
    ->deleteConcepts()

    ->getOneConsignment()
    ->getRequestBody()

    ->sendReturnLabelMails() // Send return label to customer. The customer can pay and download the label
    ->setLatestData() // Set id and run this function to update all the information about this shipment
    ->setLatestDataWithoutIds()

    ->setLinkOfLabels()
    ->getLinkOfLabels()

    // Refer to
    ->setPdfOfLabels()
    ->downloadPdfOfLabels()

    // To give us insight into which CMS system you're connecting from, you should send a User-Agent.
    // If you're using a known CMS system it's required.
    // You must send the name of the CMS system followed by a version number.
    ->setUserAgent('name_of_cms', '1.0')
    ->getUserAgent()

MyParcelCurl

Curl，用于 MyParcel API。它扩展了 https://github.com/php-curl-class/php-curl-class

贡献

  1. 检查开放问题或创建新问题以开始围绕错误或功能进行讨论。
  2. 在 GitHub 上分叉存储库以开始进行更改。
  3. 为新的功能或暴露错误编写一个或多个测试。
  4. 对代码进行更改以实现功能或修复错误。
  5. 发送一个拉取请求以合并您的更改并发布。