Documentation
Barcode webservice
Summary
- Name: Barcode Webservice.
- Reason to Call: Generate a barcode for your parcels..
- Input: Customer code and customer number and some specifications of the required barcode.
- Output: An unique identifier to use for creating shipments and to track and trace the status of the parcels.
Method
The following method is defined within the BarcodeWebService.
Method | Description |
GenerateBarcode | Generation of a single barcode |
Method | SoapAction |
GenerateBarcode | http://postnl.nl/cif/services/BarcodeWebService/IBarcodeWebService/GenerateBarcode |
Call details
Interface version | 1_1 |
Sandbox endpoint | https://api-sandbox.postnl.nl/shipment/v1_1/barcode |
Sandbox wsdl | https://api-sandbox.postnl.nl/shipment/v1_1/barcode/soap.wsdl |
Sandbox swagger | https://api-sandbox.postnl.nl/shipment/v1_1/barcode/swagger.json |
Production endpoint | https://api.postnl.nl/shipment/v1_1/barcode |
Production wsdl | https://api.postnl.nl/shipment/v1_1/barcode/soap.wsdl |
Production swagger | https://api.postnl.nl/shipment/v1_1/barcode/swagger.json |
Versioning
REST:
API
| Version | Release Date | Status | Release Notes | Schema Changes |
Barcode | 1_1 | Jun 01, 2017 | Current version | IN COMPARISON TO THE 2_1 SOAP VERSION,
| N/A |
API | Version | Release Date | Status | Release Notes | Schema Changes |
Barcode | 1_0 | Oct 01, 2012 | Not supported | ||
1_1 | Oct 28, 2014 | Current Version | Different namespaces | Yes |
Guidelines
Request
This webservice is designed to process a vast amount of requests; making sure that within milliseconds after the request is sent, a unique code is reserved and sent to accompany the parcel it is requested for. It is highly recommended to automate the process, so that if a parcel is ready for sending, a unique barcode is immediately requested from our webservice.
Specifications barcodes
The barcodes contain three elements; type, range and serie. For Types, the following business rules apply:
- A generated barcode of Type 3S is always 13 or 15 characters long and any other generated barcode (the so called S10 barcodes) must be 13 characters.
- The total length of the information in the request is validated. Length is calculated by length of Type + length of Serie + length of Range. For type 3S, value must be 13 or 15. For all other types the combined length must be 13. For S10-barcodes a 13th character is added to the result (a checkdigit). When the total length is not correct, the request will be denied.
- The Range is the customer code that PostNL has configured for you. This code consist of 1-4 letters in the case of barcodes where Type is 3S, otherwise it consists of 4 numbers (for S10-barcodes).
- Barcode Serie in the format: "###000000-###000000", for example: 100000-20000. The range must consist of a minimal difference of 100.000 for 3S barcodes (for S10-barcodes the serie should always be 0000-9999). Minimum length of the serie is 6 characters; maximum length is 9 characters.
- For certain products (International), generic S10 barcodes need to be used. These barcodes do not have a customer-component in its syntax. In these cases, the field Range needs to contain the fixed syntax ‘NL’ and the Serie needs to be fixed at 00000000-99999999.
- It is allowed to add extra leading zeros at the beginning of the serie. For example : ‘000100000’ causing the Total generated barcode to end up with the required length of 13 or 15.
See the Products page for more information about which barcode type and length to use for the PostNL products.
Specific barcode types and barcode lengths must be used per product group. Below overview gives more insight in how calls must be configured.
Dutch domestic shipments:
Type | Range | Serie | Total length | Example generated barcode |
3S | AB | 00000000000-99999999999 | 15 | 3SAB83691658823 |
3S | ABCD | 0000000-9999999 | 13 | 3SABCD3427702 |
3S | ABCD | 987000000-987600000 | 15 | 3SABCD987446630 |
Parcels EU shipments:
Type | Range | Serie | Total length | Example generated barcode |
3S | ABCD | 0000000-9999999 | 13 | 3SABCD1175003 |
3S | ABC | 10000000-20000000 | 13 | 3SABC19149187 |
3S | A | 5210500000-5210600000 | 13 | 3SA5210528875 |
GlobalPack shipments:
Type* | Range | Serie ** | Total length | Example generated barcode |
CC | 1234 | 0000-9999 | 13 | CC123442066NL |
CD | 1112 | 0000-9999 | 13 | CD111208171NL |
CP | 1122 | 0000-9999 | 13 | CP112251335NL |
* PostNL will provide you the exact barcode type to use with the PostNL Pakketten API. This should be either CC, CD, CF or CP.
** The Serie must always be 0000-9999 for use with GlobalPack to be able to generate a unique number for you.
The resulting (non-3S) barcode contains one more number than entered by {range} plus {serie}, this is the mandatory checkdigit. This number is calculated for you. The barcode will always end with NL.
International Mail & Packet products shipments:
Type | Range | Serie | Total length | Example generated barcode * |
LA | NL | 00000000-99999999 | 13 | LA599196732NL |
UE | NL | 00000000-99999999 | 13 | UE597256100NL |
RI | NL | 00000000-99999999 | 13 | RI543495045NL |
* The resulting (non-3S) barcode contains one more number than entered by {range} plus {serie}, this is the mandatory checkdigit. This number is calculated for you. The barcode will always end with NL.
Error codes
Error codes have been specified in the below PDF file. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures.
Request GenerateBarcode
MessageType
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-4-2019 12:00:00 |
Customer type
Attribute | Mandatory | Format | Description | Example |
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 |
Barcode type
Attribute | Mandatory | Format | Description | Example |
Type | M | String [2] | Accepted values are: 2S, 3S, CC, CP, CD, CF, LA | 3S |
Range | M | String [1-4] | This is the customer code that PostNL has
configured for you. Use NL for International Mail & Packet products (PEPS) shipments | ABCD |
Serie | M | String [9-19] | Barcode serie in the format: "###000000-
###000000", for example: 100000-20000. The range must consist of a minimal difference of 100.000. Minimum length of the serie is 6 characters; maximum length is 9 characters. It is allowed to add extra leading zeros at the beginning of the serie. See Guidelines for more information. | 1000000-2000000 |
Request example
POST https://api-sandbox.postnl.nl/shipment/v1_1/barcode HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: http://postnl.nl/cif/services/BarcodeWebService/IBarcodeWebService/GenerateBarcode
apikey: **********
Content-Length: 1074
Connection: Keep-Alive
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:bar="http://postnl.nl/cif/services/BarcodeWebService/"
xmlns:tpp="http://postnl.nl/cif/domain/BarcodeWebService/">
<soapenv:Body>
<bar:GenerateBarcode>
<tpp:Message>
<tpp:MessageID>1</tpp:MessageID>
<tpp:MessageTimeStamp>29-04-2019 12:00:00</tpp:MessageTimeStamp>
</tpp:Message>
<tpp:Customer>
<tpp:CustomerCode>DEVC</tpp:CustomerCode>
<tpp:CustomerNumber>11223344</tpp:CustomerNumber>
</tpp:Customer>
<tpp:Barcode>
<tpp:Type>3S</tpp:Type>
<tpp:Range>DEVC</tpp:Range>
<tpp:Serie>1000000-2000000</tpp:Serie>
</tpp:Barcode>
</bar:GenerateBarcode>
</soapenv:Body>
</soapenv:Envelope>
Response GenerateBarcode
Attribute | Description | Example |
Barcode | Generated barcode | 3SABCD6659149 |
Response example
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GenerateBarcodeResponse xmlns="http://postnl.nl/cif/services/BarcodeWebService/"
xmlns:a="http://postnl.nl/cif/domain/BarcodeWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Barcode>3SABCD6659149</a:Barcode>
</GenerateBarcodeResponse>
</s:Body>
</s:Envelope>