Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
716 lines (526 sloc) 21 KB

Services

Barcode service

Note

PostNL API documentation for this service:

The barcode service allows you to generate barcodes for your shipment labels. Usually you would reserve an amount of barcodes, generate shipping labels and eventually confirm those labels. According to PostNL, this flow is necessary for a higher delivery success rate.

Generate a single barcode

You can generate a single barcode for domestic shipments as follows:

<?php
$postnl->generateBarcode();

This will generate a 3S barcode meant for domestic shipments only.

The function accepts the following arguments:

type

string - optional, defaults to 3S

The barcode type. This is 2S/3S for the Netherlands and EU Pack Special shipments. For other destinations this is your GlobalPack barcode type. For more info, check the PostNL barcode service page.

range

string - optional, can be found automatically

For domestic and EU shipments this is your customer code. Otherwise, your GlobalPack customer code.
serie

string - optional, can be found automatically

This is the barcode range for your shipment(s). Check the PostNL barcode service page for the ranges that are available.

eps

bool - optional, defaults to false

Indicates whether this is an EU Pack Special shipment.

Generate a barcode by country code

It is possible to generate a barcode by country code. This will let the library figure out what type, range, serie to use.

Example:

<?php
$postnl->generateBarcodeByCountryCode('BE');

This will generate a 3S barcode meant for domestic shipments only.

The function accepts the following arguments:

iso

string - required

The two letter country ISO code. Make sure you use UPPERCASE.

Generate multiple barcodes by using country codes

You can generate a whole batch of barcodes at once by providing country codes and the amounts you would like to generate.

Example:

<?php
$postnl->generateBarcodeByCountryCode(['NL' => 2, 'DE' => 3]);

This will return a list of barcodes:

<?php
[
    'NL' => [
        '3SDEVC11111111111',
        '3SDEVC22222222222',
    ],
    'DE' => [
        '3SDEVC111111111',
        '3SDEVC222222222',
        '3SDEVC333333333',
    ],
];

The function accepts the following argument:

type

string - required

An associative array with country codes as key and the amount of barcodes you'd like to generate per country as the value.

Labelling service

Note

PostNL API documentation for this service:

The labelling service allows you to create shipment labels and optionally confirm the shipments. The library has a built-in way to merge labels automatically, so you can request labels for multiple shipments at once.

Generate a single label

The following example generates a single shipment label for a domestic shipment:

<?php
$postnl = new PostNL(...);
$postnl->generateLabel(
    Shipment::create()
        ->setAddresses([
            Address::create([
                'AddressType' => '01',
                'City'        => 'Utrecht',
                'Countrycode' => 'NL',
                'FirstName'   => 'Peter',
                'HouseNr'     => '9',
                'HouseNrExt'  => 'a bis',
                'Name'        => 'de Ruijter',
                'Street'      => 'Bilderdijkstraat',
                'Zipcode'     => '3521VA',
            ]),
            Address::create([
                'AddressType' => '02',
                'City'        => 'Hoofddorp',
                'CompanyName' => 'PostNL',
                'Countrycode' => 'NL',
                'HouseNr'     => '42',
                'Street'      => 'Siriusdreef',
                'Zipcode'     => '2132WT',
            ]),
        ])
        ->setBarcode($barcode)
        ->setDeliveryAddress('01')
        ->setDimension(new Dimension('2000'))
        ->setProductCodeDelivery('3085'),
    'GraphicFile|PDF',
    false
);

This will create a standard shipment (product code 3085). You can access the label (base64 encoded PDF) this way:

<?php
$pdf = base64_decode($label->getResponseShipments()[0]->getLabels()[0]->getContent());

This function accepts the following arguments:

shipment

Shipment - required

The Shipment object. Visit the PostNL API documentation to find out what a Shipment object consists of.

printertype

string - optional, defaults to GraphicFile|PDF

The list of supported printer types can be found on this page: https://developer.postnl.nl/browse-apis/send-and-track/labelling-webservice/documentation-soap/

confirm

string - optional, defaults to true

Indicates whether the shipment should immediately be confirmed.

Generate multiple shipment labels

The following example shows how a label can be merged:

<?php
$shipments = [
    Shipment::create([
        'Addresses'           => [
            Address::create([
                'AddressType' => '01',
                'City'        => 'Utrecht',
                'Countrycode' => 'NL',
                'FirstName'   => 'Peter',
                'HouseNr'     => '9',
                'HouseNrExt'  => 'a bis',
                'Name'        => 'de Ruijter',
                'Street'      => 'Bilderdijkstraat',
                'Zipcode'     => '3521VA',
            ]),
        ],
        'Barcode'             => $barcodes['NL'][0],
        'Dimension'           => new Dimension('1000'),
        'ProductCodeDelivery' => '3085',
    ]),
    Shipment::create([
        'Addresses'           => [
            Address::create([
                'AddressType' => '01',
                'City'        => 'Utrecht',
                'Countrycode' => 'NL',
                'FirstName'   => 'Peter',
                'HouseNr'     => '9',
                'HouseNrExt'  => 'a bis',
                'Name'        => 'de Ruijter',
                'Street'      => 'Bilderdijkstraat',
                'Zipcode'     => '3521VA',
            ]),
        ],
        'Barcode'             => $barcodes['NL'][1],
        'Dimension'           => new Dimension('1000'),
        'ProductCodeDelivery' => '3085',
    ]),
];

$label = $postnl->generateLabels(
    $shipments,
    'GraphicFile|PDF', // Printertype (only PDFs can be merged -- no need to use the Merged types)
    true, // Confirm immediately
    true, // Merge
    Label::FORMAT_A4, // Format -- this merges multiple A6 labels onto an A4
    [
        1 => true,
        2 => true,
        3 => true,
        4 => true,
    ] // Positions
);

file_put_contents('labels.pdf', $label);

By setting the merge flag it will automatically merge the labels into a PDF string.

The function accepts the following arguments:

shipments

Shipment[] - required

The Shipment objects. Visit the PostNL API documentation to find out what a Shipment object consists of.

printertype

string - optional, defaults to GraphicFile|PDF

The list of supported printer types can be found on this page: https://developer.postnl.nl/browse-apis/send-and-track/labelling-webservice/documentation-soap/

confirm

string - optional, defaults to true

Indicates whether the shipment should immediately be confirmed.

merge

bool - optional, default to false

This will merge the labels and make the function return a pdf string of the merged label.

format

int - optional, defaults to 1 (FORMAT_A4)

This sets the paper format (can be A4 or A4).

positions

bool[] - optional, defaults to all positions

This will set the positions of the labels. The following image shows the available positions, use true or false to resp. enable or disable a position:

img/positions.png

Confirming service

Note

PostNL API documentation for this service:

You can confirm shipments that have previously not been confirmed. The available methods are confirmShipment and confirmShipments. The first method accepts a single Shipment object whereas the latter accepts an array of `Shipment`s. The output is a boolean, or an array with booleans in case you are confirming multiple shipments. The results will be tied to the keys of your request array.

Shipping status service

Note

PostNL API documentation for this service:

This service can be used to retrieve shipping statuses. For a short update use the CurrentStatus method, otherwise CompleteStatus will provide you with a long list containing the shipment's history.

Current Status by Barcode

Gets the current status by Barcode

<?php
 $postnl = new PostNL(...);
 $postnl->getCurrentStatus((new CurrentStatus())
     ->setShipment(
         (new Shipment())
             ->setBarcode('3SDEVC98237423')
     )
 );
statusrequest

CurrentStatus - required

The CurrentStatus object. Check the API documentation for all possibilities.

Current Status by Reference

Gets the current status by reference. Note that you must have set the reference on the shipment label first.

<?php
 $postnl = new PostNL(...);
 $postnl->getCurrentStatusByReference((new CurrentStatusByReference())
     ->setShipment(
         (new Shipment())
             ->setReference('myref')
     )
 );
statusrequest

CurrentStatusByReference - required

The CurrentStatusByReference object. Check the API documentation for all possibilities.

Current Status by Status Code

Gets the current status by status.

<?php
$postnl = new PostNL(...);
$postnl->getCurrentStatusByStatus((new CurrentStatusByStatus())
    ->setShipment(
        (new Shipment())
            ->setStatusCode('5')
    )
);
statusrequest

CurrentStatusByStatus - required

The CurrentStatusByStatus object. Check the API documentation for all possibilities.

Current Status by Phase Code

Gets the current status by phase code. Note that the date range is required.

<?php
$postnl = new PostNL(...);
$postnl->getCurrentStatusByReference((new CurrentStatusByPhase())
    ->setShipment(
        (new Shipment())
            ->setPhaseCode('5')
            ->setDateFrom(date('d-m-Y H:i:s', strtotime('-7 days'))
            ->setDateTo(date('d-m-Y H:i:s')
    )
);
statusrequest

CurrentStatusByPhase - required

The CurrentStatusByPhase object. Check the API documentation for all possibilities.

Complete Status by Barcode

Gets the complete status by Barcode

<?php
$postnl = new PostNL(...);
$postnl->getCompleteStatus((new CompleteStatus())
    ->setShipment(
        (new Shipment())
            ->setBarcode('3SDEVC98237423')
    )
);
statusrequest

CompleteStatus - required

The CompleteStatus object. Check the API documentation for all possibilities.

Complete Status by Reference

Gets the complete status by reference. Note that you must have set the reference on the shipment label first.

<?php
$postnl = new PostNL(...);
$postnl->getCompleteStatusByReference((new CompleteStatusByReference())
    ->setShipment(
        (new Shipment())
            ->setReference('myref')
    )
);
statusrequest

CompleteStatusByReference - required

The CompleteStatusByReference object. Check the API documentation for all possibilities.

Complete Status by Status Code

Gets the complete status by status.

<?php
$postnl = new PostNL(...);
$postnl->getCompleteStatusByStatus((new CompleteStatusByStatus())
    ->setShipment(
        (new Shipment())
            ->setStatusCode('5')
    )
);
statusrequest

CompleteStatusByStatus - required

The CompleteStatusByStatus object. Check the API documentation for all possibilities.

Complete Status by Phase Code

Gets the complete status by phase code. Note that the date range is required.

<?php
$postnl = new PostNL(...);
$postnl->getCompleteStatusByReference((new CompleteStatusByPhase())
    ->setShipment(
        (new Shipment())
            ->setPhaseCode('5')
            ->setDateFrom(date('d-m-Y H:i:s', strtotime('-7 days'))
            ->setDateTo(date('d-m-Y H:i:s')
    )
);
statusrequest

CompleteStatusByPhase - required

The CompleteStatusByPhase object. Check the API documentation for all possibilities.

Get Signature

Gets the signature of the shipment when available. A signature can be accessed by barcode only.

It accepts the following arguments

getsignature

GetSignature - required

The GetSignature object. It needs to have one Shipment set with a barcode.

Delivery date service

Note

PostNL API documentation for this service:

Use the delivery date webservice to determine the delivery and shipping date. You can use this service to calculate the dates 'live' and to make sure you do not promise your customers any timeframes that are no longer available.

Get the Delivery Date

Here's how you can retrieve the closest delivery date:

<?php

$cutoffTime = '15:00:00';
$dropoffDays = [1 => true, 2 => true, 3 => true, 4 => true, 5 => true, 6 => false, 7 => false];
foreach (range(1, 7) as $day) {
    if (isset($dropoffDays[$day])) {
        $cutOffTimes[] = new CutOffTime(
            str_pad($day, 2, '0', STR_PAD_LEFT),
            date('H:i:00', strtotime($cutoffTime)),
            true
        );
    }
}
$deliveryDate = $postnl->getDeliveryDate(
    (new GetDeliveryDate())
        ->setGetDeliveryDate(
            (new GetDeliveryDate())
                ->setAllowSundaySorting(false)
                ->setCountryCode('NL')
                ->setCutOffTimes($cutOffTimes)
                ->setHouseNr('66')
                ->setOptions(['Morning', 'Daytime'])
                ->setPostalCode('2132WT')
                ->setShippingDate(date('d-m-Y H:i:s'))
                ->setShippingDuration('1')
        )
);

The result will be a GetDeliveryDateResponse. Calling getDeliveryDate on this object will return the delivery date as a string in the d-m-Y H:i:s PHP date format.

The function accepts the following arguments

deliverydaterequest

GetDeliveryDate - required

The GetDeliveryDate request. See the API documentation for the possibilities. As shown in the example you will need to provide as many details as possible to get accurate availability information.

Get the Shipping Date

The Shipping Date service almost works in the same way as the Delivery Date service, except this time you provide the actual delivery date in order to calculate the closest shipping date.

<?php

$cutoffTime = '15:00:00';
$dropoffDays = [1 => true, 2 => true, 3 => true, 4 => true, 5 => true, 6 => false, 7 => false];
foreach (range(1, 7) as $day) {
    if (isset($dropoffDays[$day])) {
        $cutOffTimes[] = new CutOffTime(
            str_pad($day, 2, '0', STR_PAD_LEFT),
            date('H:i:00', strtotime($cutoffTime)),
            true
        );
    }
}
$deliveryDate = $postnl->getDeliveryDate(
    (new GetDeliveryDate())
        ->setGetDeliveryDate(
            (new GetDeliveryDate())
                ->setAllowSundaySorting(false)
                ->setCountryCode('NL')
                ->setCutOffTimes($cutOffTimes)
                ->setHouseNr('66')
                ->setOptions(['Morning', 'Daytime'])
                ->setPostalCode('2132WT')
                ->setShippingDate(date('d-m-Y H:i:s'))
                ->setShippingDuration('1')
        )
);

The function accepts the following arguments

shippingdaterequest

GetSentDate - required

The GetSentDate request. See the API documentation for the possibilities. As shown in the example you will need to provide as many details as possible to get accurate availability information.

Timeframe service

Note

PostNL API documentation for this service:
timeframes

GetTimeframes - required

The GetTimeframes request object. See the API documentation for more details.

Location service

Note

PostNL API documentation for this service:

The location service allows you to retrieve a list of locations for the given postcode or coordinates.

Get Nearest Locations

Here's an example of how you can retrieve the nearest location by postcode:

<?php
$postnl->getNearestLocations(
    (new GetNearestLocations())
        ->setCountrycode('NL')
        ->setLocation(
            (new Location())
                ->setAllowSundaySorting(false)
                ->setDeliveryOptions(['PG'])
                ->setOptions(['Daytime'])
                ->setHouseNr('66')
                ->setPostalcode('2132WT')
        )
    );
nearestlocations

GetNearestLocations - required

The GetNearestLocations request object. See the API documentation for more details.

Get Nearest Locations by Coordinates

You can also get the locations by specifying a bounding box. One can be drawn by providing the North-West and South-East corner of the box:

<?php

 $postnl->getLocationsInArea(
     (new GetLocationsInArea())
         ->setCountrycode('NL')
         ->setLocation(
             (new Location())
                 ->setAllowSundaySorting(false)
                 ->setDeliveryDate(date('d-m-Y', strtotime('+1 day')))
                 ->setDeliveryOptions([
                     'PG',
                 ])
                 ->setOptions([
                     'Daytime',
                 ])
                 ->setCoordinatesNorthWest(
                     (new CoordinatesNorthWest())
                         ->setLatitude((string) 52.156439)
                         ->setLongitude((string) 5.015643)
                 )
                 ->setCoordinatesSouthEast(
                     (new CoordinatesNorthWest())
                         ->setLatitude((string) 52.017473)
                         ->setLongitude((string) 5.065254)
                 )
         )
 );

This function accepts the arguments:

locationsinarea

GetLocationsInArea - required

The GetLocationsInArea request object. See the API documentation for more details.

You can’t perform that action at this time.