Documentation REST

Shippingstatus webservice

Summary

  • Name: Shippingstatus Webservice.
  • Reason to Call: Receive status information about the shipments.
  • Input: Customer code, customer number, barcode or reference or timeframes in combination with status/phase codes.
  • Output: Status information about the shipment.

Methods

The following methods are defined within the Shippingstatus WebService.

Methods

Description

/v1_6/status/barcode/{barcode}

Returns the statuses for a particular barcode

/v1_6/status/reference/{referenceId}Get status by reference id

/v1_6/status/lookup/{kgid}

Get status by 'kennisgeving' id

/v1_6/status/searchSearch shipments by reference, status or phase
/v1_6/status/signature/{barcode}Returns the statuses for a particular barcode

Call details

Methods

JSON Action (GET)

Interface Version

1.6

Sandbox endpoint

https://api-sandbox.postnl.nl/shipment/v1_6/status

Sandbox Swagger

https://api-sandbox.postnl.nl/shipment/v1_6/status/swagger.json

Production endpoint

https://api.postnl.nl/shipment/v1_6/status

Production Swagger

https://api.postnl.nl/shipment/v1_6/status/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 theRequest for API keyform or contact your PostNL account manager to arrange this.

Versioning

API

Version

Release Date

Status

Release Notes

Schema Changes

ShippingStatus

1_6

Juni 1, 2017

Supported

New additional methods:
CompleteStatusByReference, CurrentStatusByPhase,CurrentStatusByReference

and CurrentStatusByStatus (1.2)
Changed fields in CurrentStatus response:
Removed Shipments/Customer and Removed Shipments/ProductDescription (1.2)

Different namespaces (1.3)
Changed fields in CurrentStatus response:
Added Shipments/ProductOptions (1.3)
Changed fields in CompleteStatus response:
Added Shipments/ProductOptions (1.3)

Different namespaces (1.4)

The following fields have been added to the interface:
CurrentStatusResponseShipment/Warnings and CompleteStatusResponseShipment/Warnings (1.5)
GetSignature operation has been added to the interface (1.5)
Changes in response of an unknown Shipment (1.5)

The following fields have been added to the interface:
CurrentStatusResponseShipment/DeliveryDate, CurrentStatusResponseShipment/Expectation, 

CompleteStatusResponseShipment/DeliveryDate and
CompleteStatusResponseShipment/Expectation (1.6)

Yes

Guidelines

Use of the webservice
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.
Always use the CurrentStatus method to retrieve high level status of shipment.
Only use the CompleteStatus method 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.

Security policy
The statuses about your parcels are restricted to your company (customer code and customer number). 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.

Request
The requests of the methods are almost the same. There is only a difference  in the Shipment element type of the methods. For CurrentStatusByPhase and CurrentStatusByStatus you have to give some date information combined with the status- or phase code. And for GetSignature you only need the barcode of the shipment.

Response
CurrentStatus,CurrentStatusByStatus and CurrentStatusByPhase,CurrentStatusByReference have the same response. The CompleteStatus and CompleteStatusByReference have four additional elements; Customer, Events, Old Statuses and Product Description.

The GetSignature response is different because this return 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 webservice to inform your own customers proactively about the status of their parcel. As the status we return to you is a near to real-time status it is recommended that you communicate this status as soon as possible to your customers.

Warnings
When the parcel requested is not found, the service returns a warning message.

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 in the API.

ShippingStatus_Error_Codes

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)

ShippingStatus API

Receive status information about the shipments