Barcode

Documentation

The barcode is a unique identifier which contains details about sender, receiver and details  of the shipment itself. Each generated barcode will be stored in a database, making each barcode completely unique.

Development

All the necessary information for implementing this API.

Why use the Barcode API

Unique identifier 

An identifier to create unique shipments based on your customer number and code.

Input for Shipping or Labelling API 

The service needs to be built in such that when a parcel is ready to be sent, the system is triggered to connect to request a unique barcode.


Track & Trace parcels

With each generated and used barcode you and your customers will be able to trace the parcels. 

Get started

Request your (Sandbox) API Key and start using the API.
As soon as you have an API key, it is recommended to run our Postman collections. Here you can find code examples of the various services and products we offer. This makes implementing the APIs much easier.

Guidelines

Shipping requests

For most products you can omit the barcode from the Shipping API and a barcode will be generated automatically. Should you choose to generate a barcode separately, it is recommended to automate these two API-calls (Barcode & Labelling). The received barcode can then be used directly as input to generate the shipping label (Labelling API). 

Specifications barcodes
The barcodes contain three elements; Type, Range and Serie.

Type: 

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.

Range:

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

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.

Serie: 

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.

Product groups

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 the way calls must be configured.

Dutch domestic shipments:

Type: 3S

RangeSerieTotal lengthExample generated barcode
AB00000000000-99999999999153SAB83691658823
ABCD0000000-9999999133SABCD3427702
ABCD987000000-987600000153SABCD987446630

Parcels EU shipments:

Type: 3S

RangeSerieTotal lengthExample generated barcode
ABCD0000000-9999999133SABCD1175003
ABC10000000-20000000133SABC19149187
A5210500000-5210600000133SA5210528875


Parcels Non-EU shipments:

Type*: CC,CD,CP

RangeSerie **Total lengthExample generated barcode
12340000-999913CC123442066NL
11120000-999913CD111208171NL
11220000-999913CP112251335NL

* 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 Parcels Non-EU 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: LA,UE,RI 

RangeSerieTotal lengthExample generated barcode *
NL00000000-9999999913LA599196732NL
NL00000000-9999999913UE597256100NL
NL00000000-9999999913RI543495045NL

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