README

介绍

这个库为 PostNL 提供了各种功能。主要分为以下两类

PostNL API - https://developer.postnl.nl
PostNL 预登记文件

最低要求

PHP 7.1

安装

使用 Composer 安装：soneritics/postnl

PostNL API

此插件将提供连接到 PostNL API 的基础。建议不要在生产环境中使用，因为它尚未经过错误检查，也不是完全自动化的测试。不过，它确实可以工作，并且目前正在生产环境中进行测试 :-)

如有需要帮助或需要比提供的更多服务，请创建一个问题。

支持的 API

* v2_2 支持 ERS 标签

代码示例：创建 API

始终从创建 API 对象开始。

$apiKey = '*YOUR API KEY*';

$endpoints = new Sandbox;
$customer = (new Customer)
    ->setCustomerCode('DEVC')
    ->setCustomerNumber('11223344')
    ->setAddress((new Address)
        ->setAddressType(AddressType::SENDER)
        ->setCompanyName('Soneritics')
        ->setStreet('De Rosmolen')
        ->setHouseNr('123')
        ->setZipcode('1234AB')
        ->setCity('Amsterdam')
        ->setCountrycode('NL')
    );

$api = new API($apiKey, $customer, $endpoints);

代码示例：获取条形码

$barcodeService = $api->getBarcodeService();
$barcode = $barcodeService->generateBarcode();
echo "generated barcode: {$barcode}\r\n";

代码示例：生成标签并确认发货（基本）

$message = new Message(1, PrinterType::JPG);
$dimension = (new Dimension)->setWeight(1000);
$receivingAddress = (new Address)
    ->setAddressType(AddressType::RECEIVER)
    ->setCompanyName('Jordi Jolink')
    ->setStreet('Some street')
    ->setHouseNr('123')
    ->setZipcode('1234AB')
    ->setCity('Amsterdam')
    ->setCountrycode('NL');

$shipments = (new Shipments)->addShipment(
    (new Shipment)
        ->setAddresses((new Addresses)->addAddress($receivingAddress))
        ->setBarcode($barcode)
        ->setDimension($dimension)
);

$result = $api->getLabellingService()->generateLabel($shipments, $message);
$labelContentsBase64 = $result['ResponseShipments'][0]['Labels'][0]['Content'];

代码示例：获取时间范围，获取标签并确认发货

$receivingAddress = (new Address)
    ->setAddressType(AddressType::RECEIVER)
    ->setCompanyName('Soneritics')
    ->setStreet('Some street')
    ->setHouseNr('123')
    ->setZipcode('1234AB')
    ->setCity('Amsterdam')
    ->setCountrycode('NL');

$deliveryOptions = [
    DeliveryOptions::DAYTIME,
    DeliveryOptions::EVENING,
    DeliveryOptions::AFTERNOON,
    DeliveryOptions::MORNING,
    DeliveryOptions::NOON
];

$result = $api->getTimeframeService()->calculateTimeframes($receivingAddress, $deliveryOptions);
echo "Timeframes:\r\n";
print_r($result);

# Confirm time frame
$barcodeService = $api->getBarcodeService();

echo "Confirming timeframe..\r\n";
if (!empty($result['Timeframes']['Timeframe'])) {
    $timeframe = array_pop($result['Timeframes']['Timeframe']);
    if ($timeframe !== null) {
        $deliveryTimestampStart = new DateTime($timeframe['Date'] . ' ' . $timeframe['Timeframes']['TimeframeTimeFrame']['From']);
        $deliveryTimestampEnd = new DateTime($timeframe['Date'] . ' ' . $timeframe['Timeframes']['TimeframeTimeFrame']['To']);

       $contact = (new Contact)->setEmail('mail@no-spam4me.nl');
       $shipments = (new Shipments)->addShipment(
            (new Shipment)
                ->setAddresses((new Addresses)->addAddress($receivingAddress))
                ->setBarcode($barcodeService->generateBarcode())
                ->setDimension($dimension)
                ->setDeliveryDate($deliveryTimestampStart)
                ->setDeliveryTimeStampStart($deliveryTimestampStart)
                ->setDeliveryTimeStampEnd($deliveryTimestampEnd)
                ->setContacts((new Contacts)->addContact($contact))
        );

        $result = $api->getLabellingService()->generateLabel($shipments, $message);
        print_r($result);
    }
}
echo "Timeframe confirmed.\r\n";

代码示例：获取最近的地点

$receivingAddress = (new Address)
    ->setAddressType(AddressType::RECEIVER)
    ->setZipcode('1234AB')
    ->setCountrycode('NL');

$result = $api->getLocationsService()->getNearestLocations($receivingAddress);
print_r($result);

代码示例：通过地理编码获取最近的地点并查找位置信息

$result = $api->getLocationsService()->getNearestLocationsByGeocode(51.963807, 5.968984, 'NL');

if (!empty($result['GetLocationsResult']['ResponseLocation'])) {
    $location = $result['GetLocationsResult']['ResponseLocation'][0];
    print_r($location);

    echo "Location info:\r\n";
    $locationCode = $location['LocationCode'];
    $retailNetworkID = $location['RetailNetworkID'];
    print_r($api->getLocationsService()->getLocationInformation($locationCode, $retailNetworkID));
}

代码示例：获取最近的地点并为取货点创建标签

$result = $api->getLocationsService()->getNearestLocationsByGeocode(51.963807, 5.968984, 'NL');

if (!empty($result['GetLocationsResult']['ResponseLocation'])) {
    $location = $result['GetLocationsResult']['ResponseLocation'][0];
    $locationCode = $location['LocationCode'];
    $retailNetworkID = $location['RetailNetworkID'];

    $pickupAddress = (new \PostNL\Model\Address)
        ->setAddressType(\PostNL\Enum\AddressType::DELIVERY_ADDRESS_FOR_PICKUP)
        ->setCompanyName($location['Name'])
        ->setStreet($location['Address']['Street'])
        ->setHouseNr($location['Address']['HouseNr'])
        ->setZipcode($location['Address']['Zipcode'])
        ->setCity($location['Address']['City'])
        ->setCountrycode('NL');

    $contact = (new Contact)->setEmail('mail@jordijolink.nl');
    $shipments = (new Shipments)->addShipment(
        (new Shipment)
            ->setAddresses((new Addresses)->addAddress($receivingAddress)->addAddress($pickupAddress))
            ->setBarcode($barcodeService->generateBarcode())
            ->setDimension($dimension)
            ->setContacts((new Contacts)->addContact($contact))
            ->setProductCodeDelivery('3533')
            ->setDeliveryAddress(AddressType::DELIVERY_ADDRESS_FOR_PICKUP)
    );

    $result = $api->getLabellingService()->generateLabel($shipments, $message);
    print_r($result);
}

代码示例：获取发货状态（通过条形码）

$endpoints = new Sandbox();
$api = new API($key, new Customer(), $endpoints);
$data = $api->getShippingStatusService()->getByBarcode($barcode);

PostNL 预登记

语言：荷兰语

为了类的语言、变量和注释，选择了荷兰语。同时，getters 和 setters 被称为混合类型，例如：setKlantnummer。之所以选择这样做，是因为 PostNL 仅在荷兰境内发送，因此也将主要由荷兰人实现。此外，还使用了一些特定的词汇，其英文翻译可能会使功能非常不明确。

代码示例

$afzender = (new Afzender)
    ->setBedrijfsnaam('Bedrijfsnaam')
    ->setPostcode('1234AB')
    ->setHuisnummerPostbusnummer('1')
    ->setLandcode('NL');

$voormelding = (new Voormelding)
    ->setAfzender($afzender)
    ->setKlantCode($customerCode)
    ->setKlantNummer($customerNr)
    ->setVolgnummer($volgnummer)
    ->setAanleverLocatie($bls);

$pakket = (new Pakket)
    ->setGeadresseerdeBedrijfsnaam($company)
    ->setGeadresseerdeVoornaam($firstname)
    ->setGeadresseerdeAchternaam($lastname)
    ->setGeadresseerdePostcode($zipcode)
    ->setGeadresseerdeStraatnaam($streetname)
    ->setGeadresseerdeHuisnummerPostbusnummer($housenumber)
    ->setGeadresseerdeHuisnummerToevoeging($housenumberExtension)
    ->setGeadresseerdeWoonplaats($city)
    ->setGeadresseerdeLandcode($country)
    ->setEmailadres($email)
    ->setZendingcode($shipmentCode);
$voormelding->addPakket($pakket);

// Contents ophalen. Dit kan opgeslagen worden in een LST bestand.
$voormeldContents = $voormelding->genereerInhoud()

ERS

使用 ERS

ERS 标签的产品代码是 4910。

PostNL 没有关于此产品代码的文档，但可以使用产品代码 3085 Return label in the box 的文档作为基础。使用 ERS 还需要一些其他的东西

应启用 CustomerCode（4个字母）的 ERS，或者它是 ERS 特定的。请联系 PostNL 支持以获取此信息。
Customer 和 Shipment 的 Addressses 都需要填写 name。
应设置 ReturnBarcode。

soneritics / postnl

维护者

详细信息