Shippingstatus

Documentation

When parcels go through the PostNL distribution process, they pass certain checkpoints. In this process different scans are made; the information that is derived from these scans is valuable information about where the parcel is located in the distribution process. With the ShippingStatus API we are able to share these statuses with our customers.

Development

All the necessary information for implementing this API.
 
                                         .

Go to Technical documentation https://docs.api.postnl.nl

Why use the Shippingstatus API

Near real-time status information
The current status and the complete status can be requested. With the Detail boolean in the request (true) gives you an overview of all the statuses that are given to the parcel throughout the distribution process.

Retrieve all your updated statuses
With the method ‘updatedshipments' you can retrieve (all) the updated statuses for a particular customer number.

Restricted to your personal codes
The statuses about the parcels are restricted to a customer number in combination with the customer code. Only if the customer data and the parcels match, the information is disclosed.

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.

 

Start using the API

Guidelines

Use of the API
Please be aware that this service is meant for single requests* about a parcel and not designed to update the status every single minute on all your parcels. This is important because the capacity of our network is limited. So, please ensure that this service is only called in useful intervals, and for relevant shipments only. PostNL suggests the following usage:

  • Only call ShippingStatus for an update when needed by a customer application or user.
  • Limit the number of days that will be searched for better performance with the parameter 'maxDays'.
  • Only set the parameter 'Detail'on true (boolean), when exceptions have occurred and more detailed statuses are needed.
  • Only call ShippingStatus after a shipment can have a status update (for example: request status in afternoon after delivery to PostNL, then it will have been sorted and delivered, giving useful information).
  • Stop calling ShippingStatus when the barcode is not found or an error has occurred.
* From January 15, 2019 the method '/updatedshipments' has been introduced. With this method you can retrieve (all) the updated statuses for a particular customer number. 


Security policy
The statuses about your parcels are restricted to your company (customercode and customernumber). Our security policy is designed to identify which company is requesting the information and matches that information with the parcels sent by the company. Only if the company and the parcels match, the information is disclosed.

GetSignature response 
This method returns a GIF image (base64 encoded). To retrieve a working image you need to convert and decode this string and mark the mime-type of the image as GIF.

Using the response information
You can use the response information of the API to inform your own customers proactively about the status of their parcels. As the status we return is a near to real-time status, it is recommended to communicate this status as soon as possible to your customers.