Documentation SOAP

Labelling webservice

Summary

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

Methods

The following methods are defined within the Labelling WebService.

Methods

Description

GenerateLabel

Generation of a label, followed by the confirmation of that parcel.

GenerateLabelWithoutConfirm

Generation of a label. This method doesn’t confirm the shipment. Confirming has to be done using the Confirming WebService.

Methods

SoapAction

GenerateLabel

http://postnl.nl/cif/services/LabellingWebSer vice/ILabellingWebService/GenerateLabel

GenerateLabelWithoutConfirm

http://postnl.nl/cif/services/LabellingWeb Service/ILabellingWebService/GenerateLabelWithoutConfirm

The two methods work exactly the same and have the same request and response format.

Call details

Interface Version

2_1

Sandbox endpoint

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

Sandbox WSDL

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

Production endpoint

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

Production WSDL

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

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

Versioning

VersionRelease DateStatusRelease NotesSchema Changes
1_3Dec 27, 2012Supported   
1_4Nov 8, 2013SupportedThe following fields have been added to the interface:
Shipment/Content
Shipment/CostCenter
Shipment/CustomerOrderNumber
Shipment/Remark
Shipment/ReturnReference
Shipment/ReturnBarcode
Amount/BIC
Amount/IBAN

The following fields have been removed from the interface:
Amount/AccountNr

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.
Yes
1_5Feb 27, 2014Supported

Different namespace 

Note: due to changes in the backend the Label in the box (return label) functionality is only available from version 1_6 or later.

The following fields have been added to the interface:
Shipment\ProductOption\Option
Shipment\ProductOption\Characteristic
Shipment\DeliveryDate
Shipment\DeliveryAddress

Yes
1_6Aug 14, 2014SupportedDifferent namespaceYes
1_7Nov 14, 2014SupportedThe following field has been added to the interface:
Shipment.DownPartnerLocation
Yes
1_8Jan 12, 2015SupportedThe following fields have been added to the interface:
- Shipment.IDNumber
- Shipment.IDType
- Shipment.IDExpiration
- Shipment.ReceiverDateOfBirth

The field StreetHouseNrExt is now usable for locations in NL, BE and DE.
Yes
1_9Apr 24, 2015SupportedThe 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.

Shipment validation errors now include an error code in addition to the error message.
Yes
2_0Aug 14, 2015SupportedMultiple 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.

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.
Yes
2_1July 15, 2017Current Version

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.

- DeliveryTimestampStart (Delivery on Demand label)

- DeliveryTimestampEnd (Delivery on Demand label)

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 GenerateLabel and GenerateLabelWithoutConfirm

CustomerType

AttributeMandatoryFormatDescriptionExample
AddressO-MAddress typeSee Address type (XmlElement is Address)
Address 02 is mandatory. It can either be placed in the Customer segment or in the Shipment segment.
Note that if you put it in the Shipment segment, it should go into all Shipment segments.
 
CollectionLocationMStringCode of delivery location at PostNL Pakketten123456
ContactPersonOStringName of customer contact personJanssen
CustomerCodeMString [1-4]Customer code as known at PostNL PakkettenABCD
CustomerNumberMInteger [1-8]Customer number as known at PostNL Pakketten1234567
EmailOString [0-50]E-mail address of customerjanssen@company.com
NameOString [0-35]Customer nameJanssen 

LabelSignature type

AttributeMandatoryFormatDescriptionExample
 OBase64

GIF image of the signature (as a base64 encoded string). The value of this element can have a maximum size of 65536 characters.
Note that 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.

 

Message type

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12] ID of the message1
MessageTimeStampMDatetime [19] Date/time of sending the message. Format:  dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00
PrintertypeMString [1-35] Printer type that will be used to process the label, e.g. Zebra printer or PDF See Guidelines for the available printer types.GraphicFile|PDF

Shipments type

AttributeMandatoryFormatDescriptionExample
ShipmentMShipment typeList of 1 or more ShipmentType elements of a shipment. At least one shipment type is required. Shipments for validation or
confirmation.
 

Shipment type

AttributeMandatoryFormatDescriptionExample
AddressesMAddress typeList of 1 or more Address type elements
At least 1 address type is mandatory
 
Amounts0-MAmount typeList of 0 or more AmountType elements. An amount represents a value of the shipment.
Amount type 01 mandatory for COD-shipments, Amount type 02 mandatory for domestic insured shipments.
Amount type 04 mandatory for Commercial route China (productcode 4992)
Amount type 12 mandatory for Inco terms DDP Commercial route China (productcode 4992)
 
BarcodeMString [11-15] Barcode of the shipment. This is a unique value3SABCD6659149
CollectionTimeStampEndODatetime [19] Ending date/time of the collection of the shipment04-06-2016 17:00:00
CollectionTimeStampStartODatetime [19] Starting date/time of the collection of the shipment 04-06-2016 19:00:00
ContactsO-MContact typeOne or more ContactType elements belonging to a shipment
Mandatory in some cases. Please refer to the Guidelines
 
ContentO-MString [0-35] *Content of the shipment
Mandatory for Extra@Home shipments
Media player
CostCenterOString [0-35] Cost center of the shipment.
This value will appear on your invoice
SX-GT-66
CustomerOrderNumber OString [0-35] Order number of the customer. 8689242390
CustomsO-MCustoms typeThe Customs type is mandatory for GlobalPack shipments and not allowed for any other shipment types. 
DeliveryAddressO-MInteger [2] Delivery address specification. This field is mandatory when AddressType on the Address is 09. 02
DeliveryTimestampEndO-MDatetime [19] Timestamp of the delivery used for Delivery on Demand (MyTime)
Mandatory for Delivery on Demand shipments
04-06-2017 18:00:00
DeliveryTimestampStartO-MDatetime [19] Timestamp of the delivery used for Delivery on Demand (MyTime)
Mandatory for Delivery on Demand shipments
04-06-2017 16:00:00
DeliveryDateO-Mdatetime [19] The delivery date of the shipment. We strongly advice to use the DeliveryDate service to get this date when using delivery options like Evening/Morning/Sameday delivery etc. For those products, this field is mandatory (please regard the Guidelines section).30-06-2016 12:00:00
DimensionMDimension typeDimension of a shipment.
See the dimension type.
 
DownPartnerBarcodeO-M String [0-35]Barcode of the downstream network partner of PostNL Pakketten.
Madatory for requesting GlobalPack combilabel product codes
CD123456785NL
DownPartnerIDO-M String [0-50]Identification of the downstream network partner of PostNL Pakketten.
Mandatory for Pickup at PostNl Location Belgium: LD-01
MEDEA-BE
DownPartnerLocationO-MString [0-10]Identification of the location of the downstream network partner of PostNL Pakketten
Mandatory for at PostNl Location Belgium: LD-01
12345
GroupsO-MGroup typeList of 0 or more Group types with data, grouping multiple shipments together.
Mandatory for multicollo shipments. Please see Guidelines (Multiple shipments) for more information.
 
IDExpirationO-MDate [10]Expiration date of the ID document.
Mandatory for ID Check products
05-06-2020
IDNumberO-MString [0-20]Document number of the ID document
Mandatory for ID Check products
4261103214
IDTypeO-MInteger [2]Type of the ID document.
Mandatory for ID Check products.
See Products for possible values
03
ProductCodeCollectOInteger [4]Second product code of a shipment3153
ProductCodeDeliveryMInteger [4]Product code of the shipment3085
ProductOptionsO-MProductOption typeProduct options for the shipment, mandatory for certain products, see the Products page of this webservice 
ReceiverDateOfBirthO-MDate [10]Date of birth
Mandatory for Age check products
10-12-1980
ReferenceO-MString [0-35] *Your own reference of the shipment. Mandatory for Extra@Home shipments; for E@H this is used to create your order number, so this should be unique for each request.2016014567
ReferenceCollectOString [0-35]Additional reference of the collect order of the shipment.6659150
RemarkOString [0-35]Remark of the shipment.Fragile
ReturnBarcodeO-MString [11-15]

Return barcode of the shipment. PostNL will provide you with a separate customer code specifically for generating the returnBarcode.

Note: It is not possible to generate Label in the box labels with the 1.4 and 1.5 version. Please upgrade to the newest API version (or at least > 1.5) .

 

Mandatory for Label in the Box (return label) shipments.
3SABCD7762162
ReturnReferenceOString [0-35]Return reference of the shipment.112233

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

Address type

AttributeMandatoryFormatDescriptionExample
AddressTypeMInteger [2]Type of the address. This is a code. You can find the possible values at Guidelines02
AreaOString [0-35]Area of the addressBeukenhorst
BuildingnameOString [0-35]Building name of the addressAA
CityMString [0-35] *City of the addressHoofddorp
CompanyNameO-MString [0-35] *This field has a dependency with the field Name. One of both fields must be filled mandatory; using both fields is also allowed.
Mandatory when AddressType is 09.
PostNL
CountrycodeMString [2]The ISO2 country codesNL
DepartmentOString [0-35]Send to specific department of a company.IT
DoorcodeOString [0-35]Door code of address123
FirstNameOString [0-35] *Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer.Peter
FloorOString [0-35]Send to specific floor of a company.4
HouseNrO-MString [0-35]Mandatory for shipments to Benelux.
Max. length is 5 characters (only for Benelux addresses).
For Benelux addresses, this field should always be numeric.
42
HouseNrExtOString [0-35]House number extensionA
NameO-MString [0-35] *Last name of person. This field has a dependency with the field CompanyName. One of both fields must be filled mandatory; using both fields is also allowed. Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer.de Ruiter
RegionOString [0-35]RegionNoord-Holland
RemarkOString [0-35]Remark of the shipmentFragile
StreetO-MString [0-95] *This field has a dependency with the field StreetHouseNrExt. One of both fields must be filled mandatory; using both fields is also allowed.Siriusdreef
StreetHouseNrExtO-MString [0-95]

Combination of Street, HouseNr and HouseNrExt. 

The field StreetHouseNrExt is only usable for locations in NL, BE and DE.
Please see Guidelines for the explanation.

Siriusdreef 42 A
ZipcodeO-MString [0-10]Zipcode of the address. Mandatory for shipments to Benelux
Max length (NL) 6 characters, (BE;LU) 4 numeric characters.
2132WT

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

Amount type

AttributeMandatoryFormatDescriptionExample
AccountNameOString [0-35]Name of bank account ownerC. de Ruiter
AmountTypeMInteger [2]Amount type. This is a code. Possible values are: 01 = Cash on delivery (COD) 02 = Insured value
04 mandatory for Commercial route China.
12 mandatory for Inco terms DDP Commercial route China.
01
BICO-MString [8-11]BIC number, optional for COD shipments (mandatory for bank account number other than originating in The Netherlands)INGBNL2A
CurrencyOString [3]Currency code according ISO 4217. E.g. EUREUR
IBANO- MString [15-31]IBAN bank account number, mandatory for COD shipments. Dutch IBAN numbers are 18 charactersNL00INGB1234567890
ReferenceOString [0-35]Personal payment reference1234-5678
TransactionNumberOString [0-35]Transaction number1234
ValueO-MDecimal [0-9]Money value in EUR (unless value Currency is specified for another currency). Value format (N6.2): #####0.00 (2 digits behind decimal dot)
Mandatory for COD, Insured products and Commercial route China.
10.00

Contact type

AttributeMandatoryFormatDescriptionExample
ContactTypeMInteger [2]Type of the contact. This is a code. You can find the possible values at Guidelines01
EmailO-MString [0-50]Email address of the contact. Mandatory in some cases. Please see Guidelinesreceiver@gmail.com
SMSNrO-MString [10-17]Mobile phone number of the contact. Mandatory in some cases.0612345678
TelNrO-MString [10-17]Phone number of the contact.0612345678

Customs type

AttributeMandatoryFormatDescriptionExample
CertificateO-MBoolean [true/false]Mandatory for Commercial Goods, Commercial Sample and Returned Goods (or Invoice or License; at least 1 out of 3 must be selected)true
CertificateNrO-MString [0-35]Mandatory when Certificate is true.NR112233
ContentMContent typeThis section is mandatory (minimum once, maximum 5) 
CurrencyMString [3]Currency code, only EUR and USS are allowed.EUR
EANO-MString [0-13]A unique code for a product. Together with HS number this is mandatory for product code 4992.8712512330262
HandleAsNonDeliverableMBoolean [true/false]Determines what to do when the shipment cannot be delivered the first time (if this is set to true, the shipment will be returned after the first failed attempt)false
InvoiceO-MBoolean [true/false]Possible values are true/false (no capitals allowed)
Mandatory for Commercial Goods, Commercial Sample and Returned Goods (or Certificate or License; at least 1 out of 3 must be selected)
true
InvoiceNrO-MString [0-35]Mandatory when Invoice is true.22334455
LicenseO-MBoolean [true/false]Mandatory for Commercial Goods, Commercial Sample and Returned Goods (or Certificate or Certificate; at least 1 out of 3 must be selected)true
LicenseNrO-MString [0-35]Mandatory when License is true11223344
ProductURLO-MString [0-200]Webshop URL of the product which is being shipped.
Mandatory for product code 4992
http://jishi.ydx.hk/goods.php?id=4974_1
ShipmentTypeMString [1-35]Type of shipment, possible values: Gift, Documents, Commercial Goods, Commercial Sample, Returned GoodsCommercial Goods

Content type

AttributeMandatoryFormatDescriptionExample
DescriptionMString [1-35]Description of goodsPowdered milk
QuantityMInteger [1-4]Quantity of items in description2
WeightMInteger [1-20]Net weight of goods in gram (gr)2600
ValueMDecimal [1-9]Commercial (customs) value of goods.20.00
HSTariffNrMString [6]First 6 numbers of Harmonized System Code100878
CountryOfOriginMString [2]Country codeNL

Dimension type

AttributeMandatoryFormatDescriptionExample
HeightOInteger [0-20]Height of the shipment in milimeters (mm).1400
LengthOInteger [0-20]Length of the shipment in milimeters (mm).2000
VolumeO-MInteger [0-20]Volume of the shipment in centimeters (cm3).
Mandatory for E@H-products
30000
WeightMInteger [0-20]Weight of the shipment in grams
Approximate weight suffices
4300
WidthOInteger [0-20]Width of the shipment in milimeters (mm).1500

Group type

AttributeMandatoryFormatDescriptionExample
GroupCountO-MInteger [0-3]Total number of colli in the shipment (in case of multicolli shipments)
Mandatory for multicollo shipments
4
GroupSequenceO-MInteger [0-3]Sequence number of the collo within the complete shipment (e.g. collo 2 of 4)
Mandatory for multicollo shipments
2
GroupTypeO-MInteger [2]Group sort that determines the type of group that is indicated. This is a code. Possible values: 01 = Collection request 03 = Multiple parcels in one shipment (multicolli) 04 = Single parcel in one shipment03
MainBarcodeO-MString [11-15]Main barcode for the shipment (in case of multicolli shipments)
Mandatory for multicollo shipments
3SABCD6659149

ProductOption type

AttributeMandatoryFormatDescriptionExample
CharacteristicO-MInteger [3]The characteristic of the ProductOption. Mandatory for some products, please see the Products page118
OptionO-MInteger [3]The product option code for this ProductOption.
Mandatory for some products, please see the Products page
006

Example

POST https://api-sandbox.postnl.nl/shipment/v2_1/label HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/LabellingWebService/ILabellingWebService/GenerateLabel"
apikey: **********
Content-Length: 2635
Connection: Keep-Alive . 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:lab="http://postnl.nl/cif/services/LabellingWebService/" 
xmlns:tpp="http://postnl.nl/cif/domain/LabellingWebService/">
  <soapenv:Body>
     <lab:GenerateLabel>
           <tpp:Customer>
                <tpp:Address>
                       <tpp:AddressType>02</tpp:AddressType>
                       <tpp:City>Hoofddorp</tpp:City>
                       <tpp:CompanyName>PostNL</tpp:CompanyName>
                       <tpp:Countrycode>NL</tpp:Countrycode>
                       <tpp:FirstName>Frank</tpp:FirstName>
                       <tpp:HouseNr>42</tpp:HouseNr>
                       <tpp:HouseNrExt>A</tpp:HouseNrExt>
                       <tpp:Name>Peeters</tpp:Name>
                       <tpp:Street>Siriusdreef</tpp:Street>
                       <tpp:Zipcode>2132WT</tpp:Zipcode>
                   </tpp:Address>
                  <tpp:CollectionLocation>123456</tpp:CollectionLocation>
                  <tpp:CustomerCode>DEVC</tpp:CustomerCode>
                  <tpp:CustomerNumber>11223344</tpp:CustomerNumber>
         </tpp:Customer>
             <tpp:Message>
             <tpp:MessageID>1</tpp:MessageID>
             <tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
             <tpp:Printertype>GraphicFile|PDF</tpp:Printertype>
        </tpp:Message>
              <tpp:Shipments>
                  <tpp:Shipment>
                     <tpp:Addresses>
                         <tpp:Address>
                              <tpp:AddressType>01</tpp:AddressType>
                                 <tpp:City>Utrecht</tpp:City>
                                 <tpp:CompanyName>PostNL</tpp:CompanyName>
                                 <tpp:Countrycode>NL</tpp:Countrycode>
                                 <tpp:FirstName>Peter</tpp:FirstName>
                                 <tpp:HouseNr>137</tpp:HouseNr>
                                 <tpp:HouseNrExt/>
                                 <tpp:Name>de Ruiter</tpp:Name>
                                 <tpp:Street>Oldenburgerstraat</tpp:Street>
                                 <tpp:Zipcode>3573SJ</tpp:Zipcode>
                    </tpp:Address>
                      </tpp:Addresses>
                      <tpp:Barcode>3SABCD6659149</tpp:Barcode>
                          <tpp:Contacts>
                            <tpp:Contact>
                            <tpp:ContactType>01</tpp:ContactType>
                            <tpp:Email>receiver@gmail.com</tpp:Email>
                            <tpp:SMSNr>0612345678</tpp:SMSNr>
                              </tpp:Contact>
                            </tpp:Contacts>
                         <tpp:Dimension>
                       <tpp:Weight>4300</tpp:Weight>
                         </tpp:Dimension>
                   <tpp:ProductCodeDelivery>3085</tpp:ProductCodeDelivery>
                      </tpp:Shipment>
                  </tpp:Shipments>
             </lab:GenerateLabel>
       </soapenv:Body>
</soapenv:Envelope>

Response Generate label and GenerateLabelWithoutConfirm

ResponseShipment type

Attribute  DescriptionExample
Barcode  Barcode of the shipment3SABCD6659149
DownPartnerBarcode  Barcode downstream network partner. This value will be generated for Combilabel shipmentsEA123456785NL
DownPartnerID  Identification downstream network partner. This value will be generated for Combilabel shipments.EURODIS
Labels  The list with the generated labels.  
ProductCodeDelivery  Product code of the shipment. This value can be changed by the label generation process.3085
Warnings  List of warnings 

Label type

Attribute  DescriptionExample
Content  Base64 encoded binary label
See Guidelines
 
Contenttype  

Content type of the label, e.g. zebra of pdf. See Guidelines

Note: It is not recommended to send .PDF files/labels directly to a Zebra printer. See Guidelines

PDF
Labeltype  Type of the label
See Guidelines
Label

Warning type

Attribute  DescriptionExample
Code  Warning code1003
Description  Warning description

Validation failed for shipment

Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GenerateLabelResponse>
xmlns="http://postnl.nl/cif/services/LabellingWebService/"
xmlns:a="http://postnl.nl/cif/domain/LabellingWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <a:MergedLabels i:nil="true"/>
      <a:ResponseShipments>
        <a:ResponseShipment>
          <a:Barcode>3SABCD6659149</a:Barcode>
          <a:DownPartnerBarcode i:nil="true"/>
          <a:DownPartnerID i:nil="true"/>
          <a:DownPartnerLocation i:nil="true"/>
          <a:Labels>
            <a:Label>
              <a:Content>JVBERi0xL[TRUNCATED BASE64 STRING]</a:Content>
              <a:Contenttype i:nil="true"/>
              <a:Labeltype>Label</a:Labeltype>
            </a:Label>
          </a:Labels>
          <a:ProductCodeDelivery>3085</a:ProductCodeDelivery>
          <a:Warnings i:nil="true"/>
        </a:ResponseShipment>
      </a:ResponseShipments>
    </GenerateLabelResponse>
  </s:Body>
</s:Envelope>