Documentation REST

Labelling webservice

Summary

  • Name: Labelling webservice
  • Reason to Call: Create a label and sending a confirmation to the PostNL system (optional).
  • Input: Information about the sending
  • Output: Multiple kinds of data, like PDF, jpeg or ZPL II shipping labels.

Note: When using the labelling service (GenerateLabel method), the Confirming service does no longer need to be integrated in your system, for it is included into this service.

Methods

The following methods are defined within the Labelling WebService.

MethodsJSON Action (POST)
Generate LabelGeneration of a label, followed by the confirming of that parcel.
GenerateLabel Without ConfirmGeneration of a label. This method doesn’t confirm the shipment. Confirming has to be done using the Confirming WebService.

The two methods work exactly the same and have the same request and response format except for the use of endpoint. With the Confirm boolean in the request (true of false), you can determine if you want to confirm the shipment in the same call or not.

Call details

Interface Version

2_1

Sandbox endpoint

https://api-sandbox.postnl.nl/shipment/v2_1/label

Sandbox Swagger

https://api-sandbox.postnl.nl/shipment/v2_1/label/swagger.json

Production endpoint

https://api.postnl.nl/shipment/v2_1/label

Production Swagger

https://api.postnl.nl/shipment/v2_1/label/swagger.json

* If you already use the former SOAP API’s and/or you want to make use of the REST API’s, you can fill in the Request for API key form or contact your PostNL account manager to arrange this.

Versioning

Version

Release Date

Status

Release Notes

Schema Changes

2_1

Jun 01, 2017

Supported

The following fields have been added to the interface:
Shipment/Content, Shipment/CostCenter, Shipment/CustomerOrderNumber,  Shipment/Remark, Shipment/ReturnReference, Shipment/ReturnBarcode, Amount/BIC and Amount/IBAN. (1.4)
The field Amount/AccountNr have been removed from the interface (1.4)
To comply with SEPA regulation, the bank account details must be entered in IBAN format. The COD card has been changed to print the IBAN bank account number. (1.4)

Different namespaces (1.5)

The following fields have been added to the interface:
Shipment\ProductOption\Option, Shipment\ProductOption\Characteristic, Shipment\DeliveryDate and Shipment\DeliveryAddress (1.5)

Different namespace (1.6)

The field Shipment.DownPartnerLocation has been added to the interface (1.7)
The following fields have been added to the interface:
Shipment.IDNumber,  Shipment.IDType, Shipment.IDExpiration, Shipment.ReceiverDateOfBirth (1.8)
The field StreetHouseNrExt is now usable for locations in NL, BE and DE. (1.8)

The request now includes a field for adding a signature to the labels generated by the service. This field is optional, so no change is required to use the new version of the service. (1.9)

Shipment validation errors now include an error code in addition to the error message. (1.9)

Multiple shipments can now be sent in one request to the labelling service. To this end the Shipment field has been replaced by a Shipments field, which contains a list of Shipment elements. The response has also

been modified. (2.0)

Instead of a ResponseShipment element, the response now consists of a GenerateLabelResponse element, which has a ResponseShipments field containing multiple ResponseShipment elements. (2.0)
You can use this functionality with the GraphicFile|PDF|Merge printer types to generate one label document containing multiple labels. These “merged label” documents can be found in the new MergedLabels response field. (2.0)
If you want to send only one shipment, you have to specify the Shipments element containing one Shipment. (2.0)

PostNL has implemented a commercial route to China. In order to do this, the following fields have been added to the interface:

- Shipment.Customs.Content.Content.EAN, Shipment Customs.Content.Content.ProductURL, The Shipment.Customs.Content element can occur up to 10 times instead of 5. (2.1)
- DeliveryTimestampStart and DeliveryTimestampEnd has been added to the interface to create MyTime labels (2.1)

Yes

Guidelines

EU parcels
Our labelling service provides you the possibility to produce a label for domestic use (in The Netherlands and Belgium) as well for EPS parcels (in EU).

Recommendation
It is recommended that this service is built in as early as possible in your IT-infrastructure, for this eases the whole process thereafter. Note that the label that is send to you is not suited for scaling, for the measures of the label are carefully designed to ease the parcel through our process.

Confirmation
This webservice is an integrated webservice that combines creating a label and the PostNL confirmation. The labelling service sends the confirmation to the PostNL systems and upon receiving the confirmation, the service sends back a filled in label to be printed out and to be put on the parcel. In this way, the information we receive and the information that is printed on the label always matches. This guarantees a smoother process in our distribution.

Error handling
We would like to stress the need for a suitable error handling implementation on your side. If somehow, an error is received at your end upon sending your confirmation, this means that we could not process the information correctly and the successful delivery of the parcel is in jeopardy. We strive to return the error message with as much detail as possible so you can take proper action in order to improve the information about the parcel and retry.

Multi-collo
Each request contains a single parcel. This parcel can be (part of) a single shipment or can be part of a multi-collo shipment. Each parcel in a multi-collo shipment must be in a separate request towards the GenerateLabel or GenerateLabelWithoutConfirm method.

For shipments within the Netherlands, multi collo shipments can be created. Using the API, this can be done as follows:

-Create a separate request per parcel to retrieve a label or to confirm the shipment (or both at once)
-Connect the parcels by using the Group type in each request. Mention the amount of parcels in the shipment  (GroupCount), the number of the specific Parcel (GroupSequence) and the main barcode of the shipment (MainBarcode) and specify Multicollo as the GroupType (GroupType 03).
-Every parcel in the multi collo shipment has to have its own, unique barcode.

GlobalPack
The Customs type is mandatory for GlobalPack shipments and not allowed for any other shipment types.

Printertypes
When calling the Labelling webservice, a printer type must be specified in the request. The Customer Interaction Framework is capable of generating a wide range of output formats, as summarized in the appendix . Each value can be used in the web service request. Please choose the type that fits best with your local printing situation.

Graphic Files

Zebra ZPL II*

Zebra EPS2*

GraphicFile|GIF 200 dpi

Zebra|LP 2844-Z

Zebra|LP 2844

GraphicFile|GIF 300 dpi

Zebra|Stripe S600

Zebra|105SL

GraphicFile|GIF 600 dpi

Zebra|Z4Mplus

Zebra|Stripe S300

GraphicFile|JPG 200 dpi

Zebra|Generic ZPL II 200 dpi

Zebra|Stripe S400

GraphicFile|JPG 300 dpi

Zebra|Generic ZPL II 300 dpi

Zebra|Stripe S500

GraphicFile|JPG 600 dpi

Zebra|DA 402

Zebra|A300

GraphicFile|PDF

Zebra|105Se

Zebra|S4M

GraphicFile|PDF|MergeA

Zebra|105SL

Zebra|GK420d

GraphicFile|PDF|MergeB

Zebra|Stripe S300

 

GraphicFile|PDF|MergeC

Zebra|Stripe S400

Datamax

GraphicFile|PDF|MergeD

Zebra|Stripe S500

Datamax|Class Series II

GraphicFile|PS

Zebra|A300

 
 

Zebra|S4M

 
 

Zebra|GK420d

 

* Please note: It is not recommended to send .pdf files/labels directly to a Zebra printer. If you want to send it directly to your Zebra printer, please use .jpeg files.


Labeltypes
The Label type helps you to determine what document is returned. In most cases, only a Label is returned. The following label types are possible:
LabeltypeDescription
Label (A6)normal shipping label for all shipments except for GlobalPack
BusPakjeExtra (A6)shipping label for parcels that fit in a mailbox
CODcard (Kabinet (21 x 10,16 cm)COD card as required for Dutch domestic COD shipments
CN23 form (A5)customs form for GlobalPack shipments
CP71 form (A5)customs form for GlobalPack shipments
Commercialinvoice (A4)

commercial invoice for GlobalPack shipments

Return Label (A6)normal shipping label for reverse logistics

 

Product code

Parameter

Description

  

4945

Gift, Documents

CN23 / CP71

 

4945

Commercial Goods,Commercial Sample,Returned Goods

CN23 / CP71 / CommercialInvoice

 
   

4947

Gift, Documents

CN23 (combilabel)

 

4947

Commercial Goods,Commercial Sample,Returned Goods

CN23 (combilabel) / CommercialInvoice

 
  CN23 (combilabel)
   

For the product codes 3086, 3091, 3093, 3097, 3288, 3535, 3536, 3545 and 3546 the labeltype is Label and CODcard.

Multiple shipments
Multiple shipments can now be sent in one request to the labelling service. To this end the Shipment field has been replaced by a Shipments field, which contains a list of Shipment elements. The response has also been modified. Instead of a ResponseShipment element, the response now consists of a GenerateLabelResponse element, which has a ResponseShipments field containing multiple ResponseShipment elements.

A maximum of four Shipment elements can be included in the Shipments field. When sending multiple signature images, keep in mind that the maximum size for the entire request is 200 KB.

You can use this functionality with the GraphicFile|PDF|Merge printer types to generate one label document containing multiple labels. These “merged label” documents can be found in the new MergedLabels response field.

If you want to send only one shipment, you have to specify the Shipments element containing one Shipment.

Address type
PostNL internal applications validate the receiver address. In case the spelling of addresses should be different according to our PostNL information, the address details will be corrected. This can be noticed in Track & Trace.

The webservice will not add address details. Street and City fields will only be printed when they are in the call towards the labeling webservice.

The element Address type is a code in the request. Possible values are:

CodeDescription
01Receiver
02Sender
03Alternative sender address
04Collection address
08Return address*
09Delivery address (for use with Pick up at PostNL location)

* When using the ‘label in the box return label’, it is mandatory to use an Antwoordnummer in AddressType 08. This cannot be a regular address. 

Remarks:
Within the CustomerType, only AddressType 02 can be used. This Type can also be placed in the ShipmentType.
Within the ShipmentType, at least ShipmentType with 01 is required. 

The element StreetHouseNrExt is a combination of Street, HouseNr and HouseNrExt. This field has a dependency with the field Street. One of both fields must be filled mandatory; using both fields is also allowed. This field can be used in case the values of Street, HouseNr and HouseNrExt can’t be mapped separately before calling the webservice.

This webservice will calculate a split of street name, house number and extension for you, and will afterwards use the split values. This might result in incorrect behavior for which PostNL can’t be held liable. Content in this field must be in the described order or otherwise the conversion will not work and place all values in the Street field. The conversion is only made for NL, BE and DE addresses.

Shipment type
The element Shipment type is a code in the request. Possbile values are:

CodeDescription
01Receiver
02Sender (if not in Customer/Address)
03Alternative sender address
04Collection address
08Return address*
09Delivery address (for use with Pickup at PostNL location)

* When using the ‘label in the box return label’, it is mandatory to use a Antwoordnummer in AddressType 08. This cannot be a regular address. 

The following rules apply:
If there is no Address specified with AddressType = 02, the data from Customer/Address will be added to the list as AddressType 02. If there is no Customer/Address, the message will be rejected.

An Address with AddressType = 02 can be specified. In this case, no Customer/Address has to be specified.

At least one other AddressType must be specified, other than AddressType 02. In most cases this will be AddressType 01, the receiver address.

Multiple label printing
It is possible to generate multiple labels at once, and have these labels printed on a single A4-sheet.

In order to use this functionality, you must select a different PrinterType. The PrinterType chosen determines the starting position of the label that is generated first. Below are the four printertypes that will produce an A4 sheet with multiple labels

GraphicFile|PDF|MergeA
GraphicFile|PDF|MergeB
GraphicFile|PDF|MergeC
GraphicFile|PDF|MergeD

In the figure below, the label starting position is shown for each type.

MergeA

MergeB

MergeC

MergeD

When a Merge type is chosen, the labels that follow are automatically printed on the next position. Note that you can print four labels at once using this method, so you are always able to fill a complete A4 sheet.

Limitations
The following applies to the merge functionality described above:

MergeA-D cannot be used for labels which are not 10x15 cm

MergeA-D cannot be used for combilabels

MergeA-D cannot be used for COD-products, due to the COD-card being printed

You can request up to four labels at once

Contact type
At Contact type you have the element Email, SMSNr and TelNr. This fields have a dependency with each other. At least one of these three fields must be filled mandatory. Two or three can be filled as well. To be used in combination with Pickup at PostNL location (Ophalen bij PostNL locatie) + Notification, Early Morning Pick up Points and Parcel machine product codes.

Remark: Please add the e-mail address of the receiver to improve the Mijn PostNL experience of your customer.

Request size
The total request can have a maximum size of 200KB. Larger requests will not be accepted by the server for performance reasons. Requests that exceed this limit will not return a validation error, but a HTTP 404 error.

Error codes
Error codes have been specified in the API Generic document. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in API.


Labelling Error Codes

Request and Response codes

For explanation of the request and response codes, you can take a look at the Documentation page of this API. Here you can find all information about the attributes of the json call, like descriptions, formats and examples.

Swagger UI

Test the RESTful API's with JSON content type format with the below Swagger tooling. To easily test the API: Click at 'Expand Operations', fill in at least the requirerd parameters and click at the 'Try it Out!' button. You can find the response code under Response Messages.

You can also test this API's by using the following Swagger url: http://petstore.swagger.io/(expand the url with /swagger.json and click Explore)

Labelling

Generates a Base64 label