Documentation
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/LabellingWebService/ILabellingWebService/GenerateLabel |
GenerateLabelWithoutConfirm | http://postnl.nl/cif/services/LabellingWebService/ILabellingWebService/GenerateLabelWithoutConfirm |
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_2* |
Sandbox endpoint | https://api-sandbox.postnl.nl/shipment/v2_2/label |
Sandbox wsdl | https://api-sandbox.postnl.nl/shipment/v2_2/label/soap.wsdl |
Sandbox swagger | https://api-sandbox.postnl.nl/shipment/v2_2/label/swagger.json |
Production endpoint | https://api.postnl.nl/shipment/v2_2/label |
Production wsdl | https://api.postnl.nl/shipment/v2_2/label/soap.wsdl |
Production swagger | https://api.postnl.nl/shipment/v2_2/label/date/swagger.json |
Versioning
REST:
API
| Version | Release Date | Status | Release Notes | Schema Changes |
Labelling | 2_1 | Jun 01, 2017 | Supported | IN COMPARISON TO THE 2_0 SOAP VERSION,
- DeliveryTimestampStart
| N/A |
2_2 | Jan 25, 2019 | Current version | The following fields have been added to the interface for shipments to the USA: -Shipment.Customs.TrustedShipperID
-Shipment.CodingText (response)
| Yes |
Version | Release Date | Status | Release Notes | Schema Changes | |
1_3 | Dec 27, 2012 | Not supported | |||
1_4 | Nov 8, 2013 | Not supported | The 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_5 | Feb 27, 2014 | Not supported | 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.
| Yes | |
1_6 | Aug 14, 2014 | Supported | Different namespace | Yes | |
1_7 | Nov 14, 2014 | Supported | The following field has been added to the interface:
Shipment.DownPartnerLocation | Yes | |
1_8 | Jan 12, 2015 | Not supported | The 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_9 | Apr 24, 2015 | Not supported | 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.
Shipment validation errors now include an error code in addition to the error message. | Yes | |
2_0 | Aug 14, 2015 | Supported | 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.
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_1 | July 15, 2017 | Supported | 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
- DeliveryTimestampStart (Delivery on Demand label) - DeliveryTimestampEnd (Delivery on Demand label) | Yes | |
2_2 | Jan 25, 2019 | Current version | The following fields have been added to the interface for shipments to the USA: -Shipment.Customs.TrustedShipperID -Shipment.Customs.ImporterReferenceCode -Shipment.Customs.TransactionCode -Shipment.Customs.TransactionDescription -Shipment.CodingText (response) A Codingtext have been added to the labels for mailbox parcels (brievenbuspakjes). | 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 Parcels 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.
For Extra@Home and Cargo shipments, the requests cannot be done separately for multicollo shipments. Multi collo shipments must be confirmed in one joint request.
Destination EU / Rest of World
The Customs type is mandatory for GlobalPack (Rest of World) shipments and recommended for shipments with destination EU 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* |
GraphicFile|GIF 200 dpi | Zebra|Generic ZPL II 200 dpi |
GraphicFile|GIF 300 dpi | Zebra|Generic ZPL II 300 dpi |
GraphicFile|GIF 600 dpi | Zebra|Generic ZPL II 600 dpi |
GraphicFile|JPG 200 dpi | |
GraphicFile|JPG 300 dpi | |
GraphicFile|JPG 600 dpi | |
GraphicFile|PDF | |
GraphicFile|PDF|MergeA | |
GraphicFile|PDF|MergeB | |
GraphicFile|PDF|MergeC | |
GraphicFile|PDF|MergeD |
* 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 .gif files or the native (Generic) zpl printer type.
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:
Labeltype | Description |
---|---|
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) | ||||
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:
Code | Description |
---|---|
01 | Receiver |
02 | Sender |
03 | Alternative sender address |
04 | Collection address |
08 | Return address* |
09 | Delivery 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:
Code | Description |
---|---|
01 | Receiver |
02 | Sender (if not in Customer/Address) |
03 | Alternative sender address |
04 | Collection address |
08 | Return address* |
09 | Delivery 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 label, 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
Attribute | Mandatory | Format | Description | Example |
Address | O-M | Address type | See 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. | |
CollectionLocation | M | String | Code of delivery location at PostNL Pakketten | 123456 |
ContactPerson | O | String | Name of customer contact person | Janssen |
CustomerCode | M | String [1-4] | Customer code as known at PostNL Pakketten | ABCD |
CustomerNumber | M | Integer [1-8] | Customer number as known at PostNL Pakketten | 1234567 |
O | String [0-50] | E-mail address of customer | janssen@company.com | |
Name | O | String [0-35] | Customer name | Janssen |
LabelSignature type
Attribute | Mandatory | Format | Description | Example |
O | Base64 | GIF image of the signature (as a base64 encoded string). The value of this element can have a maximum size of 65536 characters.
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
Attribute | Mandatory | Format | Description | Example |
MessageID | M | String [1-12] | ID of the message | 1 |
MessageTimeStamp | M | Datetime [19] | Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss | 29-06-2016 12:00:00 |
Printertype | M | String [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
Attribute | Mandatory | Format | Description | Example |
Shipment | M | Shipment type | List of 1 or more ShipmentType elements of a shipment. At least one shipment type is required. Shipments for validation or
confirmation. |
Shipment type
Attribute | Mandatory | Format | Description | Example |
Addresses | M | Address type | List of 1 or more Address type elements
At least 1 address type is mandatory | |
Amounts | 0-M | Amount type | List 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) | |
Barcode | M | String [11-15] | Barcode of the shipment. This is a unique value | 3SABCD6659149 |
CollectionTimeStampEnd | O | Datetime [19] | Ending date/time of the collection of the shipment | 04-06-2016 17:00:00 |
CollectionTimeStampStart | O | Datetime [19] | Starting date/time of the collection of the shipment | 04-06-2016 19:00:00 |
Contacts | O-M | Contact type | One or more ContactType elements belonging to a shipment
Mandatory in some cases. Please refer to the Guidelines | |
Content | O-M | String [0-35] * | Content of the shipment
Mandatory for Extra@Home shipments | Media player |
CostCenter | O | String [0-35] | Cost center of the shipment.
This value will appear on your invoice | SX-GT-66 |
CustomerOrderNumber | O | String [0-35] | Order number of the customer. | 8689242390 |
Customs | O-M | Customs type | The Customs type is mandatory for GlobalPack shipments and not allowed for any other shipment types. | |
DeliveryAddress | O-M | Integer [2] | Delivery address specification. This field is mandatory when AddressType on the Address is 09. | 02 |
DeliveryTimestampEnd | O-M | Datetime [19] | Timestamp of the delivery used for Delivery on Demand (MyTime)
Mandatory for Delivery on Demand shipments | 04-06-2017 18:00:00 |
DeliveryTimestampStart | O-M | Datetime [19] | Timestamp of the delivery used for Delivery on Demand (MyTime)
Mandatory for Delivery on Demand shipments | 04-06-2017 16:00:00 |
DeliveryDate | O-M | datetime [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 |
Dimension | M | Dimension type | Dimension of a shipment.
See the dimension type. | |
DownPartnerBarcode | O-M | String [0-35] | Barcode of the downstream network partner of PostNL Pakketten.
Madatory for requesting GlobalPack combilabel product codes | CD123456785NL |
DownPartnerID | O-M | String [0-50] | Identification of the downstream network partner of PostNL Pakketten.
Mandatory for Pickup at PostNl Location Belgium. Use the data from the Location API response; attribute RetailNetworkID | PNPBE-01 |
DownPartnerLocation | O-M | String [0-10] | Identification of the location of the downstream network partner of PostNL Pakketten.
| BE0Q82 |
Groups | O-M | Group type | List of 0 or more Group types with data, grouping multiple shipments together.
Mandatory for multicollo shipments. Please see Guidelines (Multiple shipments) for more information. | |
IDExpiration | O-M | Date [10] | Expiration date of the ID document.
Mandatory for ID Check products | 05-06-2020 |
IDNumber | O-M | String [0-20] | Document number of the ID document
Mandatory for ID Check products | 4261103214 |
IDType | O-M | Integer [2] | Type of the ID document.
Mandatory for ID Check products. See Products for possible values | 03 |
ProductCodeCollect | O | Integer [4] | Second product code of a shipment | 3153 |
ProductCodeDelivery | M | Integer [4] | Product code of the shipment | 3085 |
ProductOptions | O-M | ProductOption type | Product options for the shipment, mandatory for certain products, see the Products page of this webservice | |
ReceiverDateOfBirth | O-M | Date [10] | Date of birth
Mandatory for Age check products | 10-12-1980 |
Reference | O-M | String [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 |
ReferenceCollect | O | String [0-35] | Additional reference of the collect order of the shipment. | 6659150 |
Remark | O | String [0-35] | Remark of the shipment. | Fragile |
ReturnBarcode | O-M | String [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 |
ReturnReference | O | String [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
Attribute | Mandatory | Format | Description | Example |
AddressType | M | Integer [2] | Type of the address. This is a code. You can find the possible values at Guidelines | 02 |
Area | O | String [0-35] | Area of the address | Beukenhorst |
Buildingname | O | String [0-35] | Building name of the address | AA |
City | M | String [0-35] * | City of the address | Hoofddorp |
CompanyName | O-M | String [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 |
Countrycode | M | String [2] | The ISO2 country codes | NL |
Department | O | String [0-35] | Send to specific department of a company. | IT |
Doorcode | O | String [0-35] | Door code of address | 123 |
FirstName | O | String [0-35] * | Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer. | Peter |
Floor | O | String [0-35] | Send to specific floor of a company. | 4 |
HouseNr | O-M | String [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 |
HouseNrExt | O | NL= String [0-6]
Outside of NL= String [0-35] | House number extension | A |
Name | O-M | String [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 |
Region | O | String [0-35] | Region | Noord-Holland |
Remark | O | String [0-35] | Remark of the shipment | Fragile |
Street | O-M | String [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 |
StreetHouseNrExt | O-M | String [0-95] | Combination of Street, HouseNr and HouseNrExt. The field StreetHouseNrExt is only usable for locations in NL, BE and DE.
| Siriusdreef 42 A |
Zipcode | O-M | String [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
Attribute | Mandatory | Format | Description | Example | ||
AccountName | O | String [0-35] | Name of bank account owner | C. de Ruiter | ||
AmountType | M | Integer [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 | ||
BIC | O-M | String [8-11] | BIC number, optional for COD shipments (mandatory for bank account number other than originating in The Netherlands) | INGBNL2A | ||
Currency | O | String [3] | Currency code according ISO 4217. E.g. EUR | EUR | ||
IBAN | O- M | String [15-31] | IBAN bank account number, mandatory for COD shipments. Dutch IBAN numbers are 18 characters | NL00INGB1234567890 | ||
Reference | O | String [0-35] | Personal payment reference | 1234-5678 | ||
TransactionNumber | O | String [0-35] | Transaction number | 1234 | ||
Value | O-M | Decimal [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 (with the exception of certain productcodes with a standard insured amount) and Commercial route China. For COD the Eurosign (€) is always required. | 10.00 |
Contact type
Attribute | Mandatory | Format | Description | Example |
ContactType | M | Integer [2] | Type of the contact. This is a code. You can find the possible values at Guidelines | 01 |
O-M | String [0-50] | Email address of the contact. Mandatory in some cases. Please see Guidelines | receiver@gmail.com | |
SMSNr | O-M | String [10-17] | Mobile phone number of the contact. Mandatory in some cases. | 0612345678 |
TelNr | O-M | String [10-17] | Phone number of the contact. | 0612345678 |
Customs type
Attribute | Mandatory | Format | Description | Example |
Certificate | O-M | Boolean [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 |
CertificateNr | O-M | String [0-35] | Mandatory when Certificate is true. | NR112233 |
Content | M | Content type | This section is mandatory (minimum once, maximum 5) | |
Currency | M | String [3] | Currency code, only EUR and USS are allowed. | EUR |
EAN | O-M | String [0-13] | A unique code for a product. Together with HS number this is mandatory for product code 4992. | 8712512330262 |
HandleAsNonDeliverable | M | Boolean [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 |
Invoice | O-M | Boolean [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 |
InvoiceNr | O-M | String [0-35] | Mandatory when Invoice is true. | 22334455 |
License | O-M | Boolean [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 |
LicenseNr | O-M | String [0-35] | Mandatory when License is true | 11223344 |
ProductURL | O-M | String [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 |
ShipmentType | M | String [1-35] | Type of shipment, possible values: Gift, Documents, Commercial Goods, Commercial Sample, Returned Goods | Commercial Goods |
TrustedShipperID | O | String [0-50] | Use only when available.
Sender’s Customs reference, if any, as displayed on the CN 23 form. Used if the sender is designated as a trusted shipper by Customs. Assumed to be different per country customs. | 1234 |
ImporterReferenceCode | O | String [0-50] | Dependent on destination. Importer’s reference, if any, as displayed in the CN 23 form. This can be (for example) a tax code, VAT No or importer code. | 567 |
TransactionCode | O-M | String [0-50] | Code and accompanying description according to UPU List 136: “Item nature indication codes” (link). Most common codes are shown below for your reference.
| 11 |
TransactionDescription | O-M | String [0-50] | Transaction description
| Sale of goods |
Content type
Attribute | Mandatory | Format | Description | Example |
Description | M | String [1-35] | Description of goods | Powdered milk |
Quantity | M | Integer [1-4] | Quantity of items in description | 2 |
Weight | M | Integer [1-20] | Net weight of goods in gram (gr) | 2600 |
Value | M | Decimal [1-9] | Commercial (customs) value of goods. | 20.00 |
HSTariffNr | M | String [6] | First 6 numbers of Harmonized System Code | 100878 |
CountryOfOrigin | M | String [2] | Country code | NL |
Dimension type
Attribute | Mandatory | Format | Description | Example |
Height | O | Integer [0-20] | Height of the shipment in milimeters (mm). | 1400 |
Length | O | Integer [0-20] | Length of the shipment in milimeters (mm). | 2000 |
Volume | O-M | Integer [0-20] | Volume of the shipment in centimeters (cm3).
Mandatory for E@H-products | 30000 |
Weight | M | Integer [0-20] | Weight of the shipment in grams
Approximate weight suffices | 4300 |
Width | O | Integer [0-20] | Width of the shipment in milimeters (mm). | 1500 |
Group type
Attribute | Mandatory | Format | Description | Example |
GroupCount | O-M | Integer [0-3] | Total number of colli in the shipment (in case of multicolli shipments)
Mandatory for multicollo shipments | 4 |
GroupSequence | O-M | Integer [0-3] | Sequence number of the collo within the complete shipment (e.g. collo 2 of 4)
Mandatory for multicollo shipments | 2 |
GroupType | O-M | Integer [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 shipment | 03 |
MainBarcode | O-M | String [11-15] | Main barcode for the shipment (in case of multicolli shipments)
Mandatory for multicollo shipments | 3SABCD6659149 |
ProductOption type
Attribute | Mandatory | Format | Description | Example |
Characteristic | O-M | Integer [3] | The characteristic of the ProductOption. Mandatory for some products, please see the Products page | 118 |
Option | O-M | Integer [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 | Description | Example | ||
Barcode | Barcode of the shipment | 3SABCD6659149 | ||
CodingText | CodingText used for mailbox parcels. If you are using GenerateLabelWithoutConfirm, please use this value in the Confirming request when confirming the shipment. | #2426A3A#03#0306# | ||
DownPartnerBarcode | Barcode downstream network partner. This value will be generated for Combilabel shipments | EA123456785NL | ||
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 | Description | Example | ||
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 | |||
Labeltype | Type of the label
See Guidelines | Label |
Warning type
Attribute | Description | Example | ||
Code | Warning code | 1003 | ||
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>