How to use

Barcode webservice

Introduction

To make use of the PostNL Pakketten API we offer a sandbox environment that is functionally identical with the live environment. Below you can find information about how to start.

Our web services are easy to use to meet your shipping needs. To get an idea of the PostNL Pakketten API’s, it is recommended to read the Instructions and take a look at the Documention page(s).

Get your API key

To make API requests you will need an API key for the sandbox environment. API keys are unique codes that identify you or your application each time you make a call to one of our API’s. After registration, you will be handed credentials within a working day.

The received API key can give you access to all the PostNL Pakketten API’s; barcode, labelling, confirming, shippingstatus, deliverydate, timeframe and location webservices. With the credentials you can run sample requests, use the simulators and/ or make a start developing your connection(s) to the PostNL Pakketten API’s.

Run sample requests

You can access the PostNL Pakketten API without writing any code. With the API key and the documentation on this website you can run sample requests, use the simulators and/ or start developing your connection(s) to the PostNL API.

The easiest way to test connectivity and experience the input and output responses from our API’s is to use an API testing tool like SOAPUI or POSTMAN. You can find the SOAPaction url in the wsdl's of the webservices.

You can also use the SWAGGER tool to see how the webservice(s) work. You can find the SWAGGER tool at the submenu 'Documentation REST' of the webservices.

Connect to the services

To integrate the API’s into your website, e-commerce platform and/or backend application(s), you have to use a production account. After registration to become a PostNL customer you will be given personalized login credentials and receive further instructions.

Do you already have a PostNL Pakketten contract number and you don’t use the PostNL Pakketten API’s? Please contact your Account Manager or fill out this form.

Read the documentation

Get familiar with our API documentation. The detailed essential information common to all of our services. You need to be aware of these conventions before integrating any of our services.

Go to production

When you become a customer you receive a personal customer code/number and further information. The Sandbox environment must be used again in order to validate the implementation is finished without errors. IT support of PostNL Pakketten will validate your sandbox implementation 

IT support will approve the move to production and will provide you with credentials that can be used in the production environment. Then, the service endpoints can be renamed from their sandbox Uri to the production Uri and the implementation is complete.

Instructions

You can implement a (customized) integration of PostNL API's based on your particular system, platform and software. Implementation requires expertise and resource. To ensure you integrate the webservices properly to your business system and/or webshop, it is recommended to be done by (a) qualfied developer(s).

What is the PostNL Pakketten API?

The PostNL API offers you, customer or software partner of PostNL Pakketten, a real-time, flexible and modern platform for shipping services. The platform offers these services as webservices that can be used by customers and external systems to fulfil shipping needs. PostNL Pakketten wishes to support her customers to realize a further integration into their supply chain with PostNL Pakketten applications.

The PostNL Pakketten API focuses on supporting customers that have built a dedicated shipping system to be used for shipping via PostNL. Using the PostNL API, real-time interaction is made possible and direct feedback and validation of information are key advantages of the PostNL API.

How does the PostNL Pakketten API work?

Integration
After registration via account management and IT support, customers will be connected to PostNL API. This connection consists of backend services, delivery options services and a track and trace service. Each service is described separately so customers can connect to these services and integrate this with other IT applications. Also, customers will be given login credentials which are personalized per customer.

Endpoint
The base endpoint of PostNl API is a publicly accessible internet address (Uri). The communication with the endpoint is secured and will be handled via HTTPS. The Uri also contains the requested functionality and version of the service.

Versions
Each service has an own version and is part of the endpoint Uri. This means that a set of used services contains different versions. A version changes when the interface specification changes. When introducing a new version, the old version will be maintained for a certain period. Sometimes an upgrade of a certain webservice is required. PostNL will give you a reasonable period of time to update.

Communication with PostNL API (SOAP)
Communication with PostNL API will occur over HTTPS. SSL 3.0 encryption will be used via a SSL certificate. The SOAP protocol is used to call the services and receive information of a service. SOAP 1.1 must be used to send and receive the messages. The content encoding is done in UTF-8 format.

Use of services

Calling a service
SOAP: A service is called by sending a SOAP message to a service endpoint. The SOAP message contains a SOAP header with security information (username / password) and a SOAP body which contains the service method and related parameters.

Each message that is received by the API is authenticated and authorized. The authorization mechanism determines if the user has access to the requested service. The access is aligned with the services that have been agreed between PostNL Pakketten and the customer.

After processing the request, the service will return a SOAP message with a response. The SOAP message contains a SOAP body with information.

Parameter specification / field order
For each API, the parameters of a service are specified. Also, the behavior of these parameters are detailed, for example if a parameter is mandatory a [M] is shown. If the parameter is optional the description is [O].It is important to maintain the exact order of the fields as specified in the XSD. Changing the order of fields is not allowed and will result in unspecified errors returned back at the client.

API key
Each service (SOAP and REST) is secured with an API key. This API key should be added into the header of your API requests.