Die Sendungsverfolgungs-API bietet minutengenaue Sendungsstatusberichte. Benutzer dieser API können:

• Tracking-Informationen für Sendungen abrufen
• an der Sendung beteiligten Dienstleister von Deutsche Post DHL (DHL) Identifizieren
• sicher stellen, dass DHL die richtige Lieferadresse verwendet. Dadurch kann die Anzahl falsch zugestellter Sendungen reduziert werden.

Umfang

Diese API deckt folgende Dienste / Produkte ab, die von DPDHL unter diesen Markennamen bereitgestellt werden:

• Post & Parcel Germany
  • Einschreiben National, Einschreiben, Einschreiben Rückschein, Einschreiben Eigenhändig, Einschreiben Einwurf, Wert, Prio, Nachname, Einschreiben International, Einschreiben Rückschein International, Einschreiben Eigenhändig International, Wert National, Warenpost Tracked International, Ländernachweis, Postzustellungsauftäge (PZA),
  • Internetmarke
  • Paket
     
• DHL Express
  • DHL Express 9:00, DHL Express 10:30, DHL Express 12:00, DHL Express Worldwide, DHL Express Envelope, DHL Express Easy, DHL Economy Select, DHL Express Domestic 9:00, DHL Express Domestic 10:30, DHL Express Domestic 12:00, DHL Express Domestic 18:00, DHL Medical Express, DHL Express Breakbulk
     
• DHL Global Forwarding (incl. DHL Same Day)
  • AirFreight, OceanFreight Shipments
  • SameDay: SameDay Jetline Unaccompanied shipment, SameDay Jetline accompanied shipment, Same Day Speedline, SameDay Sprintline 
  • eCommerce shipments
     
• DHL Freight
  • EuroConnect, Eurapid, EuroLine, EuroNet, Customs Services, Coldchain,Trade Fairs & Events, Standard Pallet Domestic, Premium Pallet Domestic, Lead Logistics Provider, Transport Related Warehousing, RailConnect, RailLine, Parcel, Home Delivery
     
• DHL eCommerce Solutions
  • EU (Belgium, Luxemburg, Netherlands, Poland, Portugal, Spain)
    • Cross-border products (Parcel Connect, Return Connect, Parcel International, Connect PLUS, Return International) 
  • US, Canada:
    • Domestic Ground, Expedited, Expedited Max, Parcel International, Packet International
       
  • Asia-Pacific Domestic Shipments Data for Thailand & Malaysia
     
  • Parcel UK: 
    • Parcel Connect, Return Connect, Worldwide Air, Parcel International, International Road Economy  
       
• DHL Supply Chain

Es umfasst nicht:

• Services die einen Login benötigen z.B. B2B Systeme

The API provides users with tracking information on:

• Shipment location
• Shipment delivery time*
• Shipment travel history*
• The Proof of Delivery*
• Shipment timestamp
• Origin and destination information
• Shipment number of pieces*
• Shipment piece level events*
• Shipment dimensions*
• Shipment weight*

* Not available for all DPDHL services.

Using the API

You must have an eligible tracking code for the shipment and an API subscription key (this key needs to be specified in the request header).

Example Use Cases
 

Find the location of a shipment

You can use the API to help you build a website or application that enables DPDHL customers to see the location of their shipment.

The API will also identify the DPDHL service provider involved.

Discover when a shipment will arrive 

You can use the API to help you build a website or application that enables DPDHL customers to see when they can expect a delivery.

The system will also identify the DPDHL service provider involved.

Discover where a shipment has been (location history)

Some customers want to know their shipments’ travel history. 

You can use the API to help you build a website or application that enables DPDHL customers to see location history information such as:

• The timestamps 
• The locations traveled

The API will also identify the DPDHL service provider involved.

Check if DPDHL will ship to the correct address

You can help DPDHL customers verify the DPDHL service provider is using the correct delivery address. 

You can use the API to build query forms where users needs to enter the Tracking ID for a shipment. 

Discover which DPDHL service I used

You can help DPDHL customers find out which DPDHL service provider is delivering their shipment. 

You can use the API to build query forms where users needs to enter the Tracking ID for a shipment. 

Get the Proof of Delivery 

DHL’s Electronic Proof of Delivery lets you get delivery details and an image of the receiver’s signature, if it is captured digitally. When a shipment is delivered by DHL, the recipient signs and writes their name on the driver’s hand-held device. The digital signature is available the next day after delivery.

Some ordering clients want Proof of Delivery, because they want to charge their customers. 

The API can provide users with a Proof of Delivery.

The API will also identify the DPDHL service provider involved.

Get information on shipment delays

Some customers want to be informed of any potential delays to a delivery.

The API can provide them with the information regarding potential shipment delays.

The API will also identify the DPDHL service provider involved.

Customize my web application

You can use optional parameters and customize your web application based on your users’ needs. 

You can use the API to create language-specific web applications, so that customers can track their shipment in their native language.

Get Access

You must request credentials for any applications you develop

To register your app and get your API subscription keys:

1. Click My Apps on the portal website.
2. Click the + Add App button.
   The “Add App” form appears.
3. Complete the Add App form. 
   You can select the APIs you want to access.
4. When you have completed the form, click the Add App button.

Authentication

Every call to the API requires a subscription key. This key needs to be passed through a request header (DHL-API-Key).

To view your API subscription keys:

1. From the My Apps screen, click on the name of your app.
   The Details screen appears. 
2. If you have access to more than one API, click the name of the relevant API. 
   Note: The APIs are listed under the “Credentials” section. 
3. Click the Show link below the asterisks that is hiding the Consumer Key. 
   The Consumer Key appears.    

Environments

The addressable API base URL/URI environments are:  

Rate limits

Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.

When you first request access to the Shipment Tracking - Unified API, you will get the initial service level which allows 250 calls per day with a maximum of 1 call per second.

Additional rate limits are available and they are granted according to your specific use case. If you would like to request for additional limits, please proceed with the following steps:

1. Create an app as described under Get Access section. 
2. Click My Apps on the portal website.
3. Click on the App you created
4. Scroll down to the APIs list and click on the "Request Upgrade" button.
5. Please refer to the example below:

If the limit is reached, you will receive an HTTP Status code: 

429: Too many requests.  

Additional Information

Message Format

This API uses RESTful JSON format to represent any resource affordances and link relations between resources. Any non-error response of application/json media type shall be interpreted as defined in RESTful JSON specification.

JSON-LD

Furthermore, the RESTful JSON responses are in JSON-LD-compatible format.

General conventions

Enums defined in the API response entities might hold just a subset of possible values (e.g. new values can be added to enum in future non-breaking versions). In the case, when the value doesn’t meet clients expectation, client should process it as undefined.

Error Message Format

In the case of error, the application/problem+json (Problem Detail) is used to communicate details about an error.

Date & Time format

Date and Time always conform to the ISO 8601 format e.g.: 2017-06-21T14:07:17+2:00 (date time) or 2017-06-21T14:07:17Z (date time) or 2017-06-21 (date). If no time zone information is provided the time zone should be interpreted as in the place of the respective shipment event.

Error Responses

This API might use the full range of common HTTP response statuses as defined in RFC7231.
This API documentation shows only the 404 for illustration purposes on how an error response might look like.

Language

The API request might return localized messages (e.g. human readable description of a shipment status code). It is possible to indicate the language preferred by the calling user agent using the language query parameter. If the requested language is not available but the shipment is still found the API returns a successful response and indicates the actual langaguage of the response in the Content-Language header.

API Client Recommendation

Clients of the API should expect, that enums defined in the API response entities might hold just subset of possible values (e.g. new values can be added to enum in future non-breaking versions). In the case, when the value doesn’t meet clients expectation, client should process it as undefined.
Clients are advised, that optional fields may not be included in response when their value is not defined.

Selecting the preferred language

The API request can return localized messages (e.g. a human readable description of a shipment status code). 

To select your preferred language:

• Use the language query parameter when calling the user agent.

If the requested language is not available but the shipment is still found, the API returns a successful response and indicates the actual language of the response in the Content-Language header.

Permitted HTTP methods

DHL Parcel queries and responses

DHL Parcel Germany

For our parcel services in Germany, you can add recipientPostalCode to your query. This will provide you with more detailed information about the shipment.

DHL Parcel Netherlands

For our parcel services in the Netherlands, you can add recipientPostalCode to your query. This will provide you with more detailed information, such as status information.

Example requests to the API

Simple HTTP request example

curl -X GET 'https://api-eu.dhl.com/track/shipments?trackingNumber=7777777770' -H 'DHL-API-Key:PasteHere_ConsumerKey'

An explanation of the simple HTTP request example

Detailed HTTP request example

curl -X GET 'https://api-eu.dhl.com/track/shipments?trackingNumber=7777777770&service=express&originCountryCode=NZ&requesterCountryCode=GB' -H 'DHL-API-Key:PasteHere_ConsumerKey'

The cURL example contains these parameters:

Note: See the DHL Shipment Tracking API Reference Guide for more information on the available parameters.

Simple Python code sample

import http.client
import urllib.parse
import json

params = urllib.parse.urlencode({
    'trackingNumber': '7777777770',
    'service': 'express'
})

headers = {
    'Accept': 'application/json',
    'DHL-API-Key': 'ApiKeyHere'
}

connection = http.client.HTTPSConnection("api-eu.dhl.com")

connection.request("GET", "/track/shipments?" + params, "", headers)
response = connection.getresponse()

status = response.status
reason = response.reason
data = json.loads(response.read())

print("Status: {} and reason: {}".format(status, reason))
print(data)

connection.close()

specifics for the use of Tracking Data

• Data requested and received via the SHIPMENT TRACKING – UNIFIED API, such as transport status, estimated delivery time, including the tracking number is hereinafter referred to as “Tracking Data”.
• Tracking Data is Confidential Information in the meaning of section “Communication” of the General Developer Portal Terms of Use. Other than set forth below You must not reveal and/or provide third parties with the Tracking Data and/or analyze, modify such data in any form and/or derive data/information especially for competitive purposes from it without DP DHL’s prior written consent.
• Tracking Data is provided to You and/or the entity you are authorized to represent (hereinafter “You”/”Your”) via this SHIPMENT TRACKING – UNIFIED API under the prerequisite, that You retrieved the according tracking number in compliance with the applicable law, especially in the field of data protection and competition law and that You use the Tracking Data solely for Your own or Your customers’ legitimate tracking purposes.
• You shall not combine Tracking Data with advertisement or present it in a way that it could be regarded as advertisement.
• Unless otherwise agreed, You shall delete the Tracking Data 30 days after the delivery (of the shipment) to the recipient is completed.
• Tracking Data shall be used in accordance with the following specification:
  • Display “Delivered by Deutsche Post DHL Group“ in text (minimum font size) as soon as it is presented/submitted to recipient and/or Your customers.
• The use and submission of Tracking Data – including submission to any of Your subcontractors – shall always be in compliance with applicable laws and regulations, including – without limitation – data protection laws and competition/antitrust law.
• If You are neither the sender nor the recipient of DP DHL Group-shipment/s, the Tracking Data refers to,
  • You shall ensure, that you are authorized to act on behalf of the sender and/or the recipient;
  • You shall make the sender and/or the recipient aware of the restrictions set out in this User Guide just as the General Developer Portal Terms of Use;
  • You shall make the sender aware of the necessity to inform the recipient transparently about the processing of his/her personal data according to applicable data protection laws;
  • You shall inform the sender and/or recipient transparently that the use of Your Application may result in the disclosure of data being subject to postal secrecy and data protection laws to third parties (including You).