Summary
- Name: Shippingstatus Webservice.
- Reason to Call: Receive status information about the shipments.
- Input: Customernumber, barcode or reference.
- Output: Status information about the shipment(s).
Methods
| REST (Get) | Description |
| /v2/status/barcode/{barcode} | Returns the statuses for a particular barcode |
| /v2/status/reference/{referenceID} | Get status by customer reference |
| /v2/status/signature/{barcode} | Returns the signature image for a specific shipment. |
| /v2/status/{customernumber}/updatedshipments | Returns the updated statuses for a particular customer number |
* Status_Codes
**Event_Codes
Call details
| Interface version | v2* |
| Sandbox endpoint | https://api-sandbox.postnl.nl/shipment/v2/status |
| Sandbox swagger | https://api-sandbox.postnl.nl/shipment/v2/status/swagger.json |
| Production endpoint | https://api.postnl.nl/shipment/v2/status |
| Production swagger | https://api.postnl.nl/shipment/v2/status/swagger.json |
*The v2 version is only available in REST. For information about the old Shippingstatus SOAP version(s) please check the following page.
Versioning
REST:
| API | Version | Release Date | Status | Release Notes | Schema Changes |
| Shippingstatus | 1_6 | Jun 01, 2017 | Supported | IN COMPARISON TO THE 1_5 SOAP VERSION;
the following fields have been added to the interface;
CurrentStatusResponseShipment/DeliveryDate, CurrentStatusResponseShipment/Expectation,
CompleteStatusResponseShipment/DeliveryDate and CompleteStatusResponseShipment/Expectation. | N/A |
| | 2 | Feb 12, 2018 | Current version | A new method has ben added to the interface;
/v2/status/{customernumber}/updatedshipments. This method returns the updated statuses for a particular customer number.
The following fields have been added to the interface;
maxDays
language | 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.
- 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 webservice 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.
Warnings
When the parcel requested is not found, the service returns a warning message.
Error codes
Error codes have been specified in the Error codes section. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in the API.
Request
/v2/status/barcode/{barcode}
|
|
| Parameter | Mandatory | Format | Description | Example |
| apikey | M | String [32] | Authenticate using your API key.
| R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX |
| barcode | M | String [13-15] | Barcode of the shipment. This is a unique value. | 3SDEVC172649258 |
| detail | O | Boolean [true/false] | Option to include old statuses in the response.
Default value: false | false |
| language | O | String [2] | Language of the returned shipment descriptions. Possible values EN, CN, DU, FR and NL.
Default values: NL | EN |
| maxDays | O | String [2] | Limit the number of days that will be searched (decrease this amount for better performance).
| 2 |
Example
CURL:
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/barcode/
3SDEVC172649258?detail=false&language=EN&maxDays=2"
-H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"
Request URL:
https://api-sandbox.postnl.nl/shipment/v2/status/barcode/3SDEVC172649258
?detail=false&language=EN&maxDays=2
Example
{
"CurrentStatus": {
"Shipment": {
"MainBarcode": "3SDEVC172649258",
"Barcode": "3SDEVC172649258",
"ShipmentAmount": "1",
"ShipmentCounter": "1",
"Customer": {
"CustomerCode": "DEVC",
"CustomerNumber": "11223344",
"Name": "Testaccount API PNP"
},
"ProductCode": "003085",
"ProductDescription": "Standaard Zending",
"Reference": "foobar",
"Dimension": {
"Height": {1400},
"Length": {2000},
"Volume": {3000},
"Weight": {4300},
"Width": {1500}
},
"Address": [
{
"AddressType": "01",
"Building": {},
"City": "Utrecht",
"CompanyName": {},
"CountryCode": "NL",
"DepartmentName": {},
"District": {},
"FirstName": "Ben",
"Floor": {},
"HouseNumber": "42",
"HouseNumberSuffix": {},
"LastName": "Cavens",
"Region": {},
"Remark": {},
"Street": "Awesome street",
"Zipcode": "3532VA"
},
{
"AddressType": "02",
"Building": {},
"City": "Hoofddorp",
"CompanyName": {},
"CountryCode": "NL",
"DepartmentName": {},
"District": {},
"FirstName": "Ben",
"Floor": {},
"HouseNumber": "42",
"HouseNumberSuffix": {},
"LastName": "Cavens",
"Region": {},
"Remark": {},
"Street": "Siriusdreef",
"Zipcode": "2132WT"
}
],
"Status": {
"TimeStamp": "10-01-2019 16:20:27",
"StatusCode": "1",
"StatusDescription": "Zending voorgemeld",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
}
}
}
}
Response CompleteStatus
See the Currentstatus (without details/old statuses) above for information about the parameters. Additional to this fields the following parameters will appear:
| Parameter | | | Description | Example |
| Event | | | Collection of old Statuses that have occurred for this parcel |
|
| Expectation | | | Collection of old Statuses that have occurred for this parcel | |
| OldStatuses | | | Collection of old Statuses that have occurred for this parcel | |
| | | | |
Expectation type
| Parameter | | | Description | Example |
| ETAFrom | | | Estimated earliest time of arrival. Only shown when PostNL has calculated this time. | 2016-04-22T14:30:00+02:00 |
| ETATo | | | Estimated latest time of arrival. Only shown when PostNL has calculated this time. | 2016-04-22T16:30:00+02:00 |
Events type
| Parameter | | | Description | Example |
| Code | | | Event sort code, e.g: 01A. | 01A |
| Description | | | Event sort description, e.g. Zending is voorgemeld. (shipment is confirmed) | Zending is aangemeld maar nog niet ontvangen door PostNL |
| DestinationLocationCode | | | Location code of the destination | 888888 |
| LocationCode | | | Location code | 156789 |
| RouteCode | | | Route code | 310 |
| RouteName | | | Route name | 310 Sittard Vrangendael |
| TimeStamp | | | Timestamp of the event | 20-4-2016 0:39 |
CompleteStatus ResponseOldStatus type
| Attribute | | | Description | Example |
| Code | | | Code of the phase | 7 |
| Description | | | Description of the phase | Zending in distributieproces
(Shipment in distribution process) |
| PhaseCode | | | Code of the status | 4 |
| PhaseDescription | | | Description of the status | Afgeleverd (Delivered) |
| TimeStamp | | | Timestamp of the status | 05-06-2016 18:00:00 |
Example
{
"CompleteStatus": {
"Shipment": {
"MainBarcode": "3SDEVC172649258",
"Barcode": "3SDEVC172649258",
"ShipmentAmount": "1",
"ShipmentCounter": "1",
"Customer": {
"CustomerCode": "DEVC",
"CustomerNumber": "11223344",
"Name": "Testaccount API PNP"
},
"ProductCode": "003085",
"ProductDescription": "Standaard Zending",
"Reference": "foobar",
"Dimension": {
"Height": {1400},
"Length": {2000},
"Volume": {3000},
"Weight": {4300},
"Width": {1500}
},
"Address": [
{
"AddressType": "01",
"Building": {},
"City": "Utrecht",
"CompanyName": {},
"CountryCode": "NL",
"DepartmentName": {},
"District": {},
"FirstName": "Ben",
"Floor": {},
"HouseNumber": "42",
"HouseNumberSuffix": {},
"LastName": "Cavens",
"Region": {},
"Remark": {},
"Street": "Awesome street",
"Zipcode": "3532VA"
},
{
"AddressType": "02",
"Building": {},
"City": "Hoofddorp",
"CompanyName": {},
"CountryCode": "NL",
"DepartmentName": {},
"District": {},
"FirstName": "Ben",
"Floor": {},
"HouseNumber": "42",
"HouseNumberSuffix": {},
"LastName": "Cavens",
"Region": {},
"Remark": {},
"Street": "Siriusdreef",
"Zipcode": "2132WT"
}
],
"Event": [
{
"Code": "A01",
"Description": "Zending wordt verwacht, maar zit nog niet in sorteerproces",
"DestinationLocationCode": {},
"LocationCode": "888888",
"RouteCode": {},
"RouteName": {},
"TimeStamp": "10-01-2019 16:20:27"
}
],
"Status": {
"TimeStamp": "10-01-2019 16:20:27",
"StatusCode": "1",
"StatusDescription": "Zending voorgemeld",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
},
"OldStatus": [
{
"TimeStamp": "10-01-2019 16:20:27",
"StatusCode": "1",
"StatusDescription": "Zending voorgemeld",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
},
{
"TimeStamp": "29-12-2018 03:30:00",
"StatusCode": "14",
"StatusDescription": "Voorgemeld: definitief niet aangenomen",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
},
{
"TimeStamp": "22-12-2018 07:00:00",
"StatusCode": "99",
"StatusDescription": "Niet van toepassing",
"PhaseCode": "99",
"PhaseDescription": "Niet van toepassing"
},
{
"TimeStamp": "20-12-2018 03:30:00",
"StatusCode": "13",
"StatusDescription": "Voorgemeld: nog niet aangenomen",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
},
{
"TimeStamp": "19-12-2018 13:03:06",
"StatusCode": "1",
"StatusDescription": "Zending voorgemeld",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
}
]
}
}
}
Example
CURL:
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/reference/
1045968?detail=false&language=EN&maxDays=2"
-H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"
Request URL:
https://api-sandbox.postnl.nl/shipment/v2/status/reference/Reference=1045968&
customerCode=DEVC&customerNumber=11223344&detail=false
Example
CURL:
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/signature/
3SDEVC172649258"
-H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"
Request URL:
https://api-sandbox.postnl.nl/shipment/v2/status/signature/3SDEVC172649258
{
"Signature": {
"Barcode": "3SDEVC987228363",
"SignatureDate": "2019-02-24T09:25:01.000+01:00",
"SignatureImage": "[BASE64 STRING]"
}
}
Example
CURL:
curl -X GET "https://api-sandbox.postnl.nl/shipment/v2/status/11223344/updatedshipments?
period=2019-01-14T10%3A00%3A00&period=2019-01-15T10%3A00%3A00"
-H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX"
Request URL:
https://api-sandbox.postnl.nl/shipment/v2/status/11223344/updatedshipments?
period=2019-01-14T10%3A00%3A00&period=2019-01-15T10%3A00%3A00
Example
[{
"Barcode": "3SDEVC987554824",
"CreationDate": "2019-02-25",
"CustomerNumber": "11223344",
"CustomerCode": "DEVC",
"Status": {
"Timestamp": "2019-02-25T10:16:40",
"StatusCode": "1",
"StatusDescription": "Zending voorgemeld",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
}
},
{
"Barcode": "3SDEVC987173551",
"CreationDate": "2019-02-19",
"CustomerNumber": "11223344",
"CustomerCode": "DEVC",
"Status": {
"Timestamp": "2019-02-20T14:26:43",
"StatusCode": "11",
"StatusDescription": "Zending afgeleverd",
"PhaseCode": "4",
"PhaseDescription": "Afgeleverd"
}
},
{
"Barcode": "3SDEVC987022147",
"CreationDate": "2019-02-21",
"CustomerNumber": "11223344",
"CustomerCode": "DEVC",
"Status": {
"Timestamp": "2019-02-22T13:14:41",
"StatusCode": "11",
"StatusDescription": "Zending afgeleverd",
"PhaseCode": "4",
"PhaseDescription": "Afgeleverd"
}
},
{
"Barcode": "3SDEVC987443181",
"CreationDate": "2019-02-21",
"CustomerNumber": "11223344",
"CustomerCode": "DEVC",
"Status": {
"Timestamp": "2019-02-22T15:15:01",
"StatusCode": "11",
"StatusDescription": "Zending afgeleverd",
"PhaseCode": "4",
"PhaseDescription": "Afgeleverd"
}
},
{
"Barcode": "3SDEVC987528402",
"CreationDate": "2019-02-25",
"CustomerNumber": "11223344",
"CustomerCode": "DEVC",
"Status": {
"Timestamp": "2019-02-25T10:59:10",
"StatusCode": "1",
"StatusDescription": "Zending voorgemeld",
"PhaseCode": "1",
"PhaseDescription": "Collectie"
}
}]
