Documentation

• Name: Labelling webservice. 
• Reason to Call: Create a label and send a confirmation to PostNL (optional). 
• Input: Information about the shipment. 
• Output: One or more 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.

The following methods are defined within the Labelling 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.

* PostNL has launched a new API platform since 24 August 2017. The former webservices have been migrated to this platform, so that we can keep providing good service. It is recommended to use the above endpoints.

If you already use the former API’s (endpoint: https://service.postnl.com/CIF/) and you want to make use of the new endpoints, you can fill in the Request for API key form or contact your PostNL account manager to arrange this.

REST:

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.

 * 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:

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:

* 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:

* 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.

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

* To be sure that all the characters are visible on the label don’t use more than 20 characters.

* It may happen that not all the characters will be shown on the label.