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 返回标签在盒子里 的文档作为基础。使用ERS还需要额外的事项

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

soneritics / postnl

维护者

详细信息