Documentation
Shippingstatus webservice
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
Response CurrentStatus
Without details /old statuses
| Parameter | | | Description | Example |
| Addresses | | | List of Addresses | |
| Amounts | | | List of 0 ore more Amount types. An amount represents a value of a shipment. | |
| Barcode | | | Barcode of the Shipment | 3SABCD6659149 |
| DeliveryDate | | | The desired delivery date and time as indicated by the receiver.
This field is only available for Extra@Home products. | 2016-04-20T00:00:00+02:00 |
| Dimension | | | Dimension information of a Shipment | |
| Expectation | | | ExpectationType | 2016-04-20T00:00:00+02:00 |
| Groups | | | List of Group information of a Shipment | |
| Productcode | | | Product code of the Shipment | 003052 |
| ProductOptions | | | List of 0 or more ProductOption types. | |
| Reference | | | Your own reference of a shipment | 2016014567 |
| Status | | | Status information of a Shipment. See the Status Codes document for an overview of possible statuses. | |
| Warnings | | | List of 0 or more Warnings. | |
Address type
| Parameter | | | Description | Example |
| AddressType | | | Type of the address. This is a code. You can find the possible values at the Guidelines. | 02 |
| Building | | | Building name of the address | AA |
| City | | | City of the address | Hoofddorp |
| CompanyName | | | The company name of the address | PostNL |
| CountryCode | | | The ISO2 country codes | NL |
| DepartmentName | | | Send to specific department of a company. | IT |
| District | | | Area/District of the address | Beukenhorst |
| Doorcode | | | Door code of the address | 123 |
| FirstName | | | The person's first name | Peter |
| Floor | | | The specific floor of a company | 4 |
| HouseNumber | | | The house number of the address | 42 |
| HouseNumberSuffix | | | The house number extension of the address | A |
| LastName | | | The person's last name of the address | de Ruiter |
| Region | | | The region (for instance, the province) | Noord-Holland |
| RegistrationDate | | | The registration date of the address. If no registration date is entered, a default value will be shown: 01-01-0001 00:00:00 | 01-01-0001 00:00:00 |
| Remark | | | Remark of the address | No doorbell |
| Street | | | The streetname of the address | Siriusdreef |
| Zipcode | | | Zipcode of the address | 2132WT |
Amount type
| Parameter | | | Description | Example |
| AccountName | | | Name of bank account owner | C. de Ruiter |
| AmountType | | | Amount type. This is a code. Possible values are: 01 = Cash on delivery (COD) value.· 02 = Insured | 01 |
| Currency | | | Currency code according ISO 4217. E.g. EUR | EUR |
| Reference | | | Personal payment reference | 1234-5678 |
| TransactionNumber | | | Transaction number | 1234 |
| Value | | | Money value in EUR | 10.00 |
Dimension type
| Parameter | | | Description | Example |
| Height | | | Height of the shipment in milimeters (mm). | 1400 |
| Length | | | Length of the shipment in milimeters (mm). | 2000 |
| Volume | | | Volume of the shipment in centimeters (cm3). | 30000 |
| Weight | | | Weight of the shipment in grams | 4300 |
| Width | | | Length of Width of the shipment in milimeters (mm). | 1500 |
Group type
| Parameter | | | Description | Example |
| GroupType | | | Group sort that determines the type of group that is indicated. This is a code. Possible values: 01 = Collection request 03 = Multiple parcels in one shipment (multi-colli) 04 = Single parcel in one shipment | 03 |
| MainBarcode | | | Main barcode for the shipment (in case of multi-colli shipments) | 3SABCD6659149 |
| ShipmentAmount | | | Total number of colli in the shipment (in case of multi-colli shipments) | 4 |
| ShipmentCounter | | | Sequence number of the collo within the complete shipment (e.g. collo 2 of 4) | 2 |
ProductOption type
| Parameter | | | Description | Example |
| Characteristic | | | The characteristic of the ProductOption. | 6 |
| Option | | | The product option code for this ProductOption. | 118 |
Status type
| Parameter | | | Description | Example |
| PhaseCode | | | Code of the phase | 4 |
| PhaseDescription | | | Description of the phase | Afgeleverd (delivered) |
| StatusCode | | | Code of the status | 11 |
| StatusDescription | | | Description of the status. | Zending afgeleverd. (shipment is delivered) |
| StatusTimeStamp | | | Timestamp of the status | 06-06-2016 18:00:41 |
Warning type
| Parameter | | | Description | Example |
| Code | | | Warning code | 2 |
| Description | | | Warning description | De ColloWebservice heeft geen Colli gevonden (No collo found) |
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: A01. | A01 |
| 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"
}
]
}
}
}
Request
/v2/status/reference/{referenceId}
|
|
| Parameter | Mandatory | Format | Description | Example |
| apikey | M | String [32] | Authenticate using your API key.
| R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX |
| customerCode | M | String [1-4] | Customer code as known at PostNL Pakketten. | DEVC |
|
| customerNumber | M | Integer [1-8] | Customer number as known at PostNL Pakketten. | 11223344 |
| referenceId | M | String [0-35] | Your own reference of the shipment. |
|
| 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 value: 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/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
Request GetSignature
|
|
| 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 |
| |
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
Response GetSignature
SignatureResponse type
| Attribute | | | Description | Example |
| Signature | | | List of GetSignatureResponseSignature | |
| Warning | | | List of warning codes | |
GetSignatureResponseSignature type
| Attribute | | | Description | Example |
| Barcode | | | Barcode of the shipment | 3SABCD6659149 |
| SignatureDate | | | Date of the signature | 2016-06-04T10:03:51+02:00 |
| SignatureImage | | | Image contents of the signature. The image is always returned as a GIF image and is base64 encoded. | |
Warning type
| Attribute | | | Description | Example |
| Code | | | Warning code | 02 |
| Description | | | Warning description | De HandtekeningWebservice heeft geen handtekening gevonden (no signature found) |
{
"Signature": {
"Barcode": "3SDEVC987228363",
"SignatureDate": "2019-02-24T09:25:01.000+01:00",
"SignatureImage": "[BASE64 STRING]"
}
}
Request Updatedshipments
/v2/status/{customernumber}/updatedshipments
|
|
| Parameter | Mandatory | Format | Description | Example |
| apikey | M | String [32] | Authenticate using your API key.
| R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX |
| customernumber | M | Integer [1-8] | Customer number as known at PostNL Pakketten. | 11223344 |
| period | O | Array[string] | Optional array which defines a specific period in which to return updated shipments. Please use the following format: YYYY-MM-DDTHH:MM:SS. If only one variable is provided, it is interpreted as ‘period from’ up until the current datetime. If you provide two periods, the first is interpreted as ‘period from’, the second as ‘period to’ (e.g. /updatedshipments?period=2019-01-14T10:00:00&period=2019-01-15T10:00:00). | 2019-01-14T10:00:00 |
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
Response Updatedshipments
See CurrentStatus
| Attribute | | | Description | Example |
| barcode | | | Barcode of the Shipment | 3SDEVC172649258 |
| creationdate | | | The creationdate the shipment | 2019-02-25 |
| customerNumber | | | Customer number as known at PostNL Pakketten. | 11223344 |
| customerCode | | | Customer code as known at PostNL Pakketten. | DEVC |
| Status | | | Status information of a Shipment. See the Status Codes document for an overview of possible statuses. |
|
| Warnings | | | List of 0 or more Warnings. | |
Status type
| Parameter | | | Description | Example |
| PhaseCode | | | Code of the phase | 4 |
| PhaseDescription | | | Description of the phase | Afgeleverd (delivered) |
| StatusCode | | | Code of the status | 11 |
| StatusDescription | | | Description of the status. | Zending afgeleverd. (shipment is delivered) |
| StatusTimeStamp | | | Timestamp of the status | 06-06-2016 18:00:41 |
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"
}
}]
