Sending shipments can be done in one of two ways:
- Using the Shipping webservice
- Using the Barcode, Labelling and Confirming webservice
This library supports both methods. In this sections we'll go through all the available webservices.
Note
https://developer.postnl.nl/apis/barcode-webservice/overview
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.
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 method :phpFirstred\\PostNL\\PostNL::generateBarcode
accepts the following arguments:
type
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
For domestic and EU shipments this is your customer code. Otherwise, your GlobalPack customer code.
serie
This is the barcode range for your shipment(s). Check the PostNL barcode service page for the ranges that are available.
eps
Indicates whether this is an EU Pack Special shipment.
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 method :phpFirstred\\PostNL\\PostNL::generateBarcodeByCountryCode
accepts the following arguments:
iso
The two letter country ISO-3166 alpha-2 code. Make sure you use UPPERCASE. List of ISO-3166 codes: https://www.iban.com/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->generatesBarcodeByCountryCodes(['NL' => 2, 'DE' => 3]);
The method :phpFirstred\\PostNL\\PostNL::generateBarcodesByCountryCodes
will return a list of barcodes:
<?php
[
'NL' => [
'3SDEVC11111111111',
'3SDEVC22222222222',
],
'DE' => [
'3SDEVC111111111',
'3SDEVC222222222',
'3SDEVC333333333',
],
];
The function accepts the following argument:
type
This must be an associative array with country codes as key and the amount of barcodes you'd like to generate per country as the value.
Note
https://developer.postnl.nl/apis/labelling-webservice
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.
The following example generates a single shipment label for a domestic shipment:
<?php
use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Shipment;
use Firstred\PostNL\PostNL;
$barcode = '3S...';
$postnl = new PostNL(...);
$postnl->generateLabel(
Shipment: new Shipment(
Addresses: [
new Address(
AddressType: '01',
FirstName: 'Peter',
Name: 'de Ruijter',
Street: 'Bilderdijkstraat',
HouseNr: '9',
HouseNrExt: 'a bis',
Zipcode: '3521VA',
City: 'Utrecht',
Countrycode: 'NL',
),
new Address(
AddressType: '02',
CompanyName: 'PostNL',
Street: 'Siriusdreef',
HouseNr: '42',
Zipcode: '2132WT',
City: 'Hoofddorp',
Countrycode: 'NL',
),
],
Barcode: $barcode,
DeliveryAddress: '01',
Dimension: new Dimension('2000'),
ProductCodeDelivery: '3085',
),
printertype: 'GraphicFile|PDF',
confirm: 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
The :phpFirstred\\PostNL\\Entity\\Shipment
object. Visit the PostNL API documentation to find out what a :phpFirstred\\PostNL\\Entity\\Shipment
object consists of. The :phpFirstred\\PostNL\\Entity\\Shipment
object is based on the SOAP API: https://developer.postnl.nl/browse-apis/send-and-track/labelling-webservice/documentation-soap/
printerType
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
Indicates whether the shipment should immediately be confirmed.
The following example shows how a label can be merged:
<?php
use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Dimension;
use Firstred\PostNL\Entity\Label;
use Firstred\PostNL\Entity\Shipment;
use Firstred\PostNL\Enum\LabelPosition;
$postnl = new PostNL(...);
$barcodes = [
'NL' => ['3S...', '3S...'],
];
$shipments = [
new Shipment(
Addresses: [
new Address(
AddressType: '01',
FirstName: 'Peter',
Name: 'de Ruijter',
Street: 'Bilderdijkstraat',
HouseNr: '9',
HouseNrExt: 'a bis',
Zipcode: '3521VA',
City: 'Utrecht',
Countrycode: 'NL',
),
],
Barcode: $barcodes['NL'][0],
Dimension: new Dimension(Weight: '1000'),
ProductCodeDelivery: '3085',
),
new Shipment(
Addresses: [
new Address(
AddressType: '01',
FirstName: 'Peter',
Name: 'de Ruijter',
Street: 'Bilderdijkstraat',
HouseNr: '9',
HouseNrExt: 'a bis',
Zipcode: '3521VA',
City: 'Utrecht',
Countrycode: 'NL',
),
],
Barcode: $barcodes['NL'][1],
Dimension: new Dimension(Weight: '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
[
LabelPosition::TopLeft->value => true,
LabelPosition::TopRight->value => true,
LabelPosition::BottomLeft->value => true,
LabelPosition::BottomRight->value => 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
An array with :phpFirstred\\PostNL\\Entity\\Shipment
objects. Visit the PostNL API documentation to find out what a :phpFirstred\\PostNL\\Entity\\Shipment
object consists of. The :phpFirstred\\PostNL\\Entity\\Shipment
object is based on the SOAP API: https://developer.postnl.nl/browse-apis/send-and-track/labelling-webservice/documentation-soap/
printerType
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
Indicates whether the shipment should immediately be confirmed.
merge
This will merge the labels and make the function return a pdf string of the merged label.
format
This sets the paper format (can be Firstred\PostNL\PostNL::FORMAT_A4 or Firstred\PostNL\PostNL::FORMAT_A6).
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:
Note
https://developer.postnl.nl/browse-apis/send-and-track/shipping-webservice/
The shipping service combines all the functionality of the labeling, confirming, barcode and easy return service. The service is only available as REST.
The following example sends a single domestic shipment:
<?php
use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Dimension;
use Firstred\PostNL\Entity\Shipment;
use Firstred\PostNL\PostNL;
$postnl = new PostNL(...);
$postnl->sendShipment(
shipment: new Shipment(
Addresses: [
new Address(
AddressType: '01',
FirstName: 'Peter',
Name: 'de Ruijter',
Street: 'Bilderdijkstraat',
HouseNr: '9',
HouseNrExt: 'a bis',
Zipcode: '3521VA',
City: 'Utrecht',
Countrycode: 'NL',
),
new Address(
AddressType: '02',
CompanyName: 'PostNL',
Street: 'Siriusdreef',
HouseNr: '42',
Zipcode: '2132WT',
City: 'Hoofddorp',
Countrycode: 'NL',
),
],
DeliveryAddress: '01',
Dimension: new Dimension(Weight: '2000'),
ProductCodeDelivery: '3085',
),
printertype: 'GraphicFile|PDF',
confirm: false
);
This will create a standard shipment (product code 3085). You can access the label (base64 encoded PDF) this way:
<?php
$pdf = base64_decode($shipping->getResponseShipments()[0]->getLabels()[0]->getContent());
This function accepts the following arguments:
shipment
The :phpFirstred\\PostNL\\Entity\\Shipment
object. Visit the PostNL API documentation to find out what a Shipment object consists of.
printertype
The list of supported printer types can be found on this page: https://developer.postnl.nl/browse-apis/send-and-track/shipping-webservice/documentation/
confirm
Indicates whether the shipment should immediately be confirmed.
The following example shows how labels of multiple shipment labels can be merged:
<?php
use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Dimension;
use Firstred\PostNL\Entity\Label;
use Firstred\PostNL\Entity\Shipment;
use Firstred\PostNL\Enum\LabelPosition;
use Firstred\PostNL\PostNL;
$postnl = new PostNL(...);
$shipments = [
new Shipment(
Addresses: [
new Address(
AddressType: '01',
FirstName: 'Peter',
Name: 'de Ruijter',
Street: 'Bilderdijkstraat',
HouseNr: '9',
HouseNrExt: 'a bis',
Zipcode: '3521VA',
City: 'Utrecht',
Countrycode: 'NL',
),
],
Dimension: new Dimension(Weight: '1000'),
ProductCodeDelivery: '3085',
),
new Shipment(
Addresses: [
new Address(
AddressType: '01',
FirstName: 'Peter',
Name: 'de Ruijter',
Street: 'Bilderdijkstraat',
HouseNr: '9',
HouseNrExt: 'a bis',
Zipcode: '3521VA',
City: 'Utrecht',
Countrycode: 'NL',
),
],
Dimension: new Dimension(Weight: '1000'),
ProductCodeDelivery: '3085',
),
];
$label = $postnl->sendShipments(
shipments: $shipments,
printertype: 'GraphicFile|PDF', // Printertype (only PDFs can be merged -- no need to use the Merged types)
confirm: true, // Confirm immediately
merge: true, // Merge
format: Label::FORMAT_A4, // Format -- this merges multiple A6 labels onto an A4
positions: [
LabelPosition::TopLeft->value => true,
LabelPosition::TopRight->value => true,
LabelPosition::BottomLeft->value => true,
LabelPosition::BottomRight->value => 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
An array with :phpFirstred\\Entity\\Shipment
objects. Visit the PostNL API documentation to find out what a Shipment object consists of.
printertype
The list of supported printer types can be found on this page: https://developer.postnl.nl/browse-apis/send-and-track/shipping-webservice/documentation/
confirm
Indicates whether the shipment should immediately be confirmed.
merge
This will merge the labels and make the function return a pdf string of the merged label.
format
This sets the paper format (can be :phpFirstred\\PostNL\\PostNL::FORMAT_A4
or :phpFirstred\\PostNL\\PostNL::FORMAT_A6
).
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:
Note
https://developer.postnl.nl/apis/confirming-webservice
You can confirm shipments that have previously not been confirmed. Shipments can be confirmed after both the labelling webservice
or the shipping webservice
.
The available methods are :phpFirstred\\PostNL\\PostNL::confirmShipment
and :phpFirstred\\PostNL\\PostNL::confirmShipments
. The first method accepts a single :phpFirstred\\PostNL\\Entity\\Shipment
object whereas the latter accepts an array of :php:class:`Firstred\PostNL\Entity\Shipment`s.
Example code:
<?php
use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Dimension;
use Firstred\PostNL\Entity\Shipment;
use Firstred\PostNL\PostNL;
$postnl = new PostNL(...);
$confirmedShipment = $postnl->confirmShipment(
shipment: new Shipment(
Addresses: [
new Address(
AddressType: '01',
FirstName: 'Peter',
Name: 'de Ruijter',
Street: 'Bilderdijkstraat',
HouseNr: '9',
HouseNrExt: 'a bis',
Zipcode: '3521VA',
City: 'Utrecht',
Countrycode: 'NL',
),
new Address(
AddressType: '02',
CompanyName: 'PostNL',
Street: 'Siriusdreef',
HouseNr: '42',
Zipcode: '2132WT',
City: 'Hoofddorp',
Countrycode: 'NL',
),
],
Barcode: '3SDEVC201611210',
DeliveryAddress: '01',
Dimension: new Dimension('2000'),
ProductCodeDelivery: '3085',
),
);
The output is a :phpFirstred\\PostNL\\Entity\\Respone\\ConfirmingResponseShipment
or an array with these objects in case you are confirming multiple shipments. The results array will have the same index keys as the request input.
Note
https://developer.postnl.nl/apis/shippingstatus-webservice
This service can be used to retrieve shipping statuses. For a short update request a current status, otherwise complete status will provide you with a long list containing the shipment's history.
Gets the current or complete status by barcode. A complete status also includes the shipment history.
<?php
$postnl = new PostNL(...);
$postnl->getShippingStatusByBarcode('3SDEVC98237423');
barcode
The barcode, e.g.: 3SDEVC98237423
complete
Return the complete shipping status. This includes the shipment history.
Depending on the complete
parameter this returns a :phpFirstred\\PostNL\\Entity\\Response\\CurrentStatusResponseShipment
or a :phpFirstred\\PostNL\\Entity\\Response\\CompleteStatusResponseShipment
object.
Gets multiple current or complete statuses by barcodes. A complete status also includes the shipment history.
<?php
$postnl = new PostNL(...);
$postnl->getShippingStatusesByBarcodes(['3SDEVC98237423', '3SDEVC98237423']);
barcodes
The references, e.g.: ['3SDEVC98237423', '3SDEVC98237423']
complete
Return the complete shipping status. This includes the shipment history.
Depending on the complete
parameter this returns an array with :phpFirstred\\PostNL\\Entity\\Response\\CurrentStatusResponseShipment
or :phpFirstred\\PostNL\\Entity\\Response\\CompleteStatusResponseShipment
objects. The array is an associative array indexed by the given barcodes, e.g.: ['3SDEVC98237423' => CurrentStatusResponseShipment, ...]
.
Gets the current or complete status by reference. A complete status also includes the shipment history.
<?php
$postnl = new PostNL(...);
$postnl->getShippingStatusByReference('order-12');
reference
The barcode, e.g.: order-12
complete
Return the complete shipping status. This includes the shipment history.
Depending on the complete
parameter this returns a :phpFirstred\\PostNL\\Entity\\Response\\CurrentStatusResponseShipment
or a :phpFirstred\\PostNL\\Entity\\Response\\CompleteStatusResponseShipment
object.
Gets multiple current or complete statuses by references. A complete status also includes the shipment history.
<?php
$postnl = new PostNL(...);
$postnl->getShippingStatusesByReferences(['order-12', 'order-16']);
barcodes
The references, e.g.: ['order-12', 'order-16]
complete
Return the complete shipping status. This includes the shipment history.
Depending on the complete
parameter this returns an array with :phpFirstred\\PostNL\\Entity\\Response\\CurrentStatusResponseShipment
or :phpFirstred\\PostNL\\Entity\\Response\\CompleteStatusResponseShipment
objects. The array is an associative array indexed by the given references, e.g.: ['order-12' => CurrentStatusResponseShipment, ...]
.
Warning
This is no longer supported by the PostNL API.
Gets the current status by phase code. Note that the date range is required.
Warning
This is no longer supported by the PostNL API
Warning
This is no longer supported by the PostNL API.
Warning
This is no longer supported by the PostNL API.
Gets the signature of the shipment when available. A signature can be accessed by barcode only.
<?php
$postnl = new PostNL(...);
$postnl->getSignatureByBarcode('3SDEVC23987423');
It accepts the following arguments
barcode
The shipment's barcode, e.g. 3SDEVC23987423
This method returns a :phpFirstred\\PostNL\\Entity\\Response\\GetSignatureResponseSignature
object. To get the actual signature in binary format you will have to use:
<?php
$postnl = new PostNL(...);
$getSignatureResponseSignature = $postnl->getSignatureByBarcode('3SDEVC23987423');
$content = base64_decode($getSignatureResponseSignature->getSignatureImage());
header('Content-Type: image/gif');
echo $content;
exit;
Gets multiple signatures of multiple shipments, when available.
<?php
$postnl = new PostNL(...);
$postnl->getSignaturesByBarcodes(['3SDEVC23987423', '3SDEVC23987425']);
It accepts the following arguments
barcodes
An array of barcodes, e.g. ['3SDEVC23987423', '3SDEVC23987425']
.
It returns an array of :phpFirstred\\PostNL\\Entity\\Response\\GetSignatureResponseSignature
objects. To get the image data out of these objects, see get a single signature
.