Introduction
To make use of the Parcels API’s you need a key. Below you can find information about how to start.
Our web services are easy to use to meet your data needs. To get an idea of the PostNL API’s, it is recommended to read the Instructions and take a look at the Documention page.
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.
Run sample requests
You can access the PostNL 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 url in the 'Documentation REST of the API’s.
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 Parcels ontract number and you don’t use the PostNL 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.
IT support will approve the move to production and will provide you with credentials that can be used in the production environment.
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 API?
The PostNL API offers you, customer or software partner of PostNL, a real-time, flexible and modern platform for data solutions. The platform offers these services as webservices that can be used by customers and external systems to fulfil shipping needs. PostNL wishes to support her customers to realize a further integration into their supply chain with PostNL applications.
How does the PostNL 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. TLS 1.2 encryption will be used via a TLS 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.
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.