5 Track and Trace
5.1 Intro
With the Track & Trace endpoint a shipment can be tracked throughout the delivery process. The most important information from a business perspective will be discussed.
Preconditions
-
Authentication token. See documentation on Authentication and authorization endpoint.
A token is only needed if you need to retrieve the tracker code through the label service. See documentation on Labels endpoints.
-
The tracker code and optional the postal code of the receiver.
The tracker code is a return value when creating the label. See documentation on Labels endpoints.
5.2 Services
5.2.1 Track and Trace
The Track & Trace endpoint is called with at least the tracker code, that is provided in the response of the Create label endpoint when the label has successfully been created.
A call to the T&T endpoint will result in a chain of events (technically an array), where each event falls into a category of the whereabouts of a shipment. A category holds a status which gives a more detailed description of what might be the exact current state of the shipment. Endpoints for the translation of these status fields can be found in the API gateway under Translations.
| Status category | Description |
|---|---|
| CUSTOMS | The shipment is being processed by customs |
| DATA RECEIVED | The shipment is registered |
| DELIVERED | Delivered at door or DHL ServicePoint |
| EXCEPTION | Something in the process went wrong, delay is expected |
| INTERVENTION | An intervention occurred in the delivery process |
| IN DELIVERY | The parcel is in transit |
| LEG | Usually the trace of a domestic delivery will start with some LEG events. It means that the shipment is registered. |
| PROBLEM | Same as exception |
| UNDERWAY | The parcel is being sorted |
| UNKNOWN | The status of the parcel is unknown |
For more extensive information (shipment details) in the track & trace response the postal code of the receiver can be added in the request.
- https://api-gw.dhlparcel.nl/track-trace?key=3SBPB0000094346+9999BB
5.2.1.1 Delivery date
Initially there is no planned delivery date, but it can be calculated by deriving the transit time set for the country of origin and destination through the Transit-times endpoint.
Based on the country codes of origin, destination and the postal code, the transit time in days is given as a result by the endpoint. To calculate the planned delivery date simply add the transit time days to the shipment date.
As soon as a parcel has left the sorting center the planned delivery timeframe (‘plannedDeliveryTimeframe’) should be available in the next event.
This planned delivery timeframe can change or might not be available in the last event due to for example problems with the receiver’s address. The shipment gets marked with category PROBLEM or INTERVENTION and the shipment will need to be re-planned.
The fact that, and when, a parcel actually is delivered is communicated through the attribute ‘deliveredAt’ (at top level in the json response).
5.2.1.1 Proof of Delivery (POD)
If there is a signature available and the request has been made with the tracker code and the postal code of the receiver, the response contains a field pod that contains the URL for the POD image.
5.3 API Usage
| Description | URL |
|---|---|
| Get Track & Trace info | https://api-gw.dhlparcel.nl/track-trace |
5.3.1 Get Track & Trace info
Request examples
Curl
curl -X GET "https://api-gw.dhlparcel.nl/track-trace?key=3SBPB0000094346%2B9999AA" -H "Accept: application/json"
Responses
Success (code 200)
[
{
"barcode": "3SBPB0000094346",
"date": "2017-11-28T23:00:00.000Z",
"events": [
{
"category": "LEG",
"leg": {
"accountId": "5880133",
"debtorNumber": "5880133",
"destinationFacility": "ARM",
"destinationServiceArea": "ARM",
"number": "7451930615",
"network": "DAY_DEFINITE",
"originFacility": "MAA",
"originServiceArea": "MAA",
"reference": "60832634"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_CREATED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "LEG",
"leg": {
"network": "DAY_DEFINITE"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_REFERENCE_ADDED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "LEG",
"leg": {
"network": "DAY_DEFINITE",
"reference": "60832634"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_REFERENCE_ADDED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "LEG",
"leg": {
"network": "DAY_DEFINITE",
"reference": "3SDSP004644834"
},
"localTimestamp": "2017-11-29T00:00:00.000+01:00",
"status": "LEG_REFERENCE_ADDED",
"timestamp": "2017-11-28T23:00:00.000Z",
"type": "LEG_EVENT"
},
{
"category": "DATA_RECEIVED",
"localTimestamp": "2017-11-29T21:56:54.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PRENOTIFICATION_RECEIVED",
"timestamp": "2017-11-29T20:56:54.000Z",
"type": "PIECE_EVENT"
},
{
"category": "LEG",
"leg": {
"accountId": "79807100",
"network": "ECOMMERCE"
},
"localTimestamp": "2017-11-29T21:57:07.000+01:00",
"status": "LEG_CREATED",
"timestamp": "2017-11-29T20:57:07.000Z",
"type": "LEG_EVENT"
},
{
"category": "UNDERWAY",
"facility": "RXD",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-29T23:50:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"powerOfAttorney": false,
"remarks": "",
"route": "0",
"scannedManual": false,
"serviceArea": "RXD",
"status": "DEPART_FACILITY",
"stopNumber": 0,
"timestamp": "2017-11-29T22:50:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "DD/RXD",
"localTimestamp": "2017-11-29T23:50:00.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PARCEL_SORTED_AT_HUB",
"timestamp": "2017-11-29T22:50:00.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"localTimestamp": "2017-11-30T00:11:27.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-01T14:00:00.000+01:00/2017-12-01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-30T18:00:00.000+01:00",
"status": "INFORMATION_ON_DELIVERY_TRANSMITTED",
"timestamp": "2017-11-29T23:11:27.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARM",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-30T03:55:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"plannedDeliveryTimeframe": "2017-11-30T08:00:00.000+01:00/2017-11-30T18:00:00.000+01:00",
"powerOfAttorney": false,
"remarks": "",
"route": "0",
"scannedManual": false,
"serviceArea": "ARM",
"status": "ARRIVED_AT_DELIVERY_FACILITY",
"stopNumber": 0,
"timestamp": "2017-11-30T02:55:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-11-30T04:42:41.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "20 17-12-01T14:00:00.000+01:00/2017-12-01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-30T18:00:00.000+01:00",
"route": "1",
"status": "DELIVERY_PLANNED_IN_ROUTE",
"timestamp": "2017-11-30T03:42:41.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARM",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-30T08:04:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"plannedDeliveryTimeframe": "2017-11-30T08:00:00.000+01:00/2017-11-30T18:00:00.000+01:00",
"powerOfAttorney": false,
"remarks": "DHL eCommerce Arnhem Zuid",
"route": "512150",
"scannedManual": true,
"serviceArea": "ARM",
"status": "IN_ROUTE_THIRD_PARTY",
"stopNumber": 1,
"timestamp": "2017-11-30T07:04:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-11-30T08:05:15.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-01T14:00:00.000+01:00/2017-12-01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-30T18:00:00.000+01:00",
"route": "2",
"status": "DELIVERY_PLANNED_IN_ROUTE",
"timestamp": "2017-11-30T07:05:15.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARM",
"height": 14,
"length": 18,
"localTimestamp": "2017-11-30T08:46:00.000+01:00",
"leg": {
"network": "DAY_DEFINITE"
},
"plannedDeliveryTimeframe": "2017-11-30T08:00:00.000+01:00/2017-11-30T18:00:00.000+01:00",
"powerOfAttorney": false,
"remarks": "DHL eCommerce Arnhem Zuid",
"route": "512150",
"scannedManual": true,
"serviceArea": "ARM",
"status": "FORWARD_DESTINATION",
"stopNumber": 1,
"timestamp": "2017-11-30T07:46:00.000Z",
"weight": 0.2,
"width": 14,
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ETTPAK",
"localTimestamp": "2017-11-30T09:11:09.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "2",
"status": "PARCEL_ARRIVED_AT_LOCAL_DEPOT",
"timestamp": "2017-11-30T08:11:09.000Z",
"type": "PIECE_EVENT"
},
{
"category": "PROBLEM",
"facility": "ARNPAK",
"localTimestamp": "2017-11-30T09:11:10.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-01T14:00:00.000+01:00/2017-12-01T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-11-30T14:00:00.000+01:00/2017-11-30T18:00:00.000+01:00",
"route": "2",
"status": "MISSORT",
"timestamp": "2017-11-30T08:11:10.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ETTPAK",
"localTimestamp": "2017-11-30T09:11:40.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "2",
"status": "PARCEL_ARRIVED_AT_LOCAL_DEPOT",
"timestamp": "2017-11-30T08:11:40.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "PI",
"localTimestamp": "2017-12-01T20:55:13.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PARCEL_SCANNED_AT_RETURN_HUB",
"timestamp": "2017-12-01T19:55:13.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "PI",
"localTimestamp": "2017-12-03T17:42:26.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "DEPOT_SCAN",
"timestamp": "2017-12-03T16:42:26.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "PI",
"localTimestamp": "2017-12-05T21:58:56.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "DEPOT_SCAN",
"timestamp": "2017-12-05T20:58:56.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "EC>144",
"localTimestamp": "2017-12-06T18:04:40.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"status": "PARCEL_SORTED_AT_HUB",
"timestamp": "2017-12-06T17:04:40.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"localTimestamp": "2017-12-06T18:07:37.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-07T18:00:00.000+01:00",
"status": "INFORMATION_ON_DELIVERY_TRANSMITTED",
"timestamp": "2017-12-06T17:07:37.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T04:14:46.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-07T18:00:00.000+01:00",
"route": "1",
"status": "DELIVERY_PLANNED_IN_ROUTE",
"timestamp": "2017-12-07T03:14:46.000Z",
"type": "PIECE_EVENT"
},
{
"category": "UNDERWAY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T08:14:50.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "1",
"status": "PARCEL_ARRIVED_AT_LOCAL_DEPOT",
"timestamp": "2017-12-07T07:14:50.000Z",
"type": "PIECE_EVENT"
},
{
"category": "IN_DELIVERY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T09:47:23.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-07T18:00:00.000+01:00",
"route": "1",
"status": "PARCEL_SCANNED_INTO_HAND-TERMINAL",
"timestamp": "20 17-12-07T08:47:23.000Z",
"type": "PIECE_EVENT"
},
{
"category": "IN_DELIVERY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T10:15:18.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-07T18:00:00.000+01:00",
"route": "1",
"status": "OUT_FOR_DELIVERY",
"timestamp": "2017-12-07T09:15:18.000Z",
"type": "PIECE_EVENT"
},
{
"category": "IN_DELIVERY",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T10:15:18.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"route": "1",
"status": "PARCEL_HANDED_OVER_TO_COURIER",
"timestamp": "2017-12-07T09:15:18.000Z",
"type": "PIECE_EVENT"
},
{
"category": "DELIVERED",
"facility": "ARNPAK",
"localTimestamp": "2017-12-07T16:58:41.000+01:00",
"leg": {
"network": "ECOMMERCE"
},
"nextPlannedDeliveryTimeframe": "2017-12-08T14:00:00.000+01:00/2017-12-08T18:00:00.000+01:00",
"plannedDeliveryTimeframe": "2017-12-07T14:00:00.000+01:00/2017-12-07T18:00:00.000+01:00",
"route": "1",
"status": "DELIVERED",
"timestamp": "2017-12-07T15:58:41.000Z",
"type": "PIECE_EVENT"
}
],
"type": "SHIPMENT",
"deliveredAt": "2017-12-07T16:58:41.000+01:00",
"id": "5a1f1f5f014129d859716df6"
}
]
5.4 Testing
These test cases with positive outcomes are merely suggestions and it is not an extensive test set, e.g. tests with a negative outcome should also be taken into scope. Please extend with test cases which are suitable for your line of business or wishes.
| Suggested Test Cases | Expected Result |
| Place a request with tracker code | Track and trace info is shown for given tracker code |
| Place a request with tracker code and zipCode of the receiver | Track and trace info is shown for given tracker code and the address details |