Documentation REST

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.

MethodDescription
GenerateBarcodeGeneration of a single barcode
MethodJSON Action (GET)
GenerateBarcodeGenerate standard barcode

Call details

Interface Version

1_1

Sandbox endpoint

https://api-sandbox.postnl.nl/shipment/v1_1/barcode

Sandbox Swagger

https://api-sandbox.postnl.nl/shipment/v1_1/barcode/swagger.json  

Production endpoint

https://api.postnl.nl/shipment/v1_1/barcode

Production Swaggerhttps://api.postnl.nl/shipment/v1_1/barcode/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

API

Version

Release Date

Status

Release Notes

Schema Changes

Barcode

1_1

Jun 01, 2017

Current Version

Different namespaces compared to the previous (SOAP) 1.0 version

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

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

000000000-999999999

13

3SABCD3427702

3S

ABCD

9870000000-9876000000

15

3SABCD987446630

EPS shipments:

Type

Range

Serie

Total length

Example generated barcode

3S

ABCD

000000000-999999999

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.

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.

Barcode_Error_Document

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)

Barcode API