The Track & Trace API comes in two versions that enables you to use services to access Order information provided by DHL Supply Chain in the MySupplyChain Track & Trace visibility solution (previously called Connected View).

Track and Trace - All Orders Types

- This API has two calls, the first returns a list of orders matching the key and country.    A second API is then called with a unique reference to return the order details.
         The order types available are Customer Order, Warehouse Order and Transport Order.

Documents and POD documents

- This API is used to search and download existing documents available in Track and Trace including system generated POD documents. The API has two calls, the first call returns details for POD and other documents available for a particular order. Document details returned in first call is used in second call which returns the actual document. When retrieving the document, there are two different call options depending on whether the document is a system generated POD  document or a document listed under order documents tab in Track and Trace .

Scope

The type of information available through the All Order Types API is the same as the one users can find on the MySupplyChain Track & Trace public web search without logging in.

The type of information available through the public API is the same as the one users can find on the MySupplyChain Track & Trace public web search without logging in.

Using the API

The All Order Types API takes only 2 key parameters in the first call.  An order reference and country code.
Within the payload returned by this API will be a unique key,  "order_id", this must be used as the required parameter for the second API call.

Calling the second API with the  "order_id" will return the Order Detail information regardless of the Order type.

The Document and POD documents API consist of two calls , the first call returns details for POD and other documents available for a particular order. The second call is used to obtain the document

1. Call 1. Search Document and POD Documents. This call is used to retrieve document details needed to obtain document in second call. 

2. Call 2. Download of the system generated POD  document or other document

There are two call options depending on type of document being downloaded, both require document details obtained from response in Call 1There are two call options depending on type of document being downloaded, both require document details obtained from response in Call 1There are two call options depending on type of document being downloaded, both require document details obtained from response in Call 1There are two call options depending on type of document being downloaded, both require document details obtained from response in Call 1There are two call options depending on type of document being downloaded, both require document details obtained from response in Call 1.

Download Other Documents. Used to download documents listed under order documents tab in Track and Trace. Parameters "resourceId" and "orderId" is used to obtain document

Download POD documents. Used to download system generated POD documents. The parameter "documentId" is used to obtain document.

The MySupplyChain Track & Trace public API is a Restful API which uses GET HTTP requests.

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.
 

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.
 

Get information on shipment Status
Some customers want to be informed of the current status of their request.   Is it "Awaiting Dispatch", "In Transit" or "Delivered".  These APIs can provide them with the information regarding shipment Status.   With the "All Order Types" API it is possible to return the status events for Purchase, Customer and Warehouse Orders along with the Transport Order information.  For example: have the goods been picked in the warehouse?
 

Obtain POD document available in Track and Trace

A customer may want to download the POD document available in Track and Trace using the API solution compared to doing so via the web page.

Get Access

 All Orders Types

All Orders Types API requires a Work Request in GSN for further engagement of DHL LINK Build team. . A guideline for our Work Request process is available in this wiki page.

 MySupplyChain Track & Trace API – Request Process

If you are not a DHL Supply Chain Customer, contact one of our experts here.

Documents and POD documents

To request access to these API’s, an azure service principal will be required.

Once created, a request to Track  and Trace support team via the following request form must be submitted so that correct level of access is granted to the service principal. Level of access granted is typically customer/business partner specific

Using the id and password for the service principal, you can call following API:

OAuth

The following API’s can be called using a bearer token provided by OAuth API:

Search Documents And POD Documents

Download Documents Other

Documents

Authentication

The API Key and the key secret should be sent as HTTP basic authentication credentials. 

This is the successful response which you will see when successfully authenticated.

HTTP Response Status Code 200 OK

This is the failed response which you will see in the browser in case of invalid credentials.

HTTP Response Status Code 401 Unauthorized

Available Authentication Methods

DHL provides access to its APIs via the following mechanisms:

• OAuth 2.0
• Basic Authentication

Each API will describe its particular access mechanism with regards of how to transmit the authentication within a single request. Credentials to use a certain API can be requested via the DHL Developer Portal.

Resource Owner Password Grant Type

For Mobile and Desktop apps,  T&T Service supports the Resource Owner Password OAuth 2.0 grant type. This password grant type is for highly trusted apps where resource owners share their credentials directly with the app.

Resource Owner Password Grant Type Roles - OAuth 2.0

The Resource Owner Password grant type uses the following roles:

• Resource Owner: A person or system capable of granting access to a protected resource.
• App: A client that makes protected requests using the authorization of the resource owner.
• Authorization Server (T&T): The server that issues access tokens to client apps after successfully authenticating the resource owner.
• Resource Server (T&T): The server that hosts protected resources and accepts and responds to protected resource requests using access tokens. Apps access the server through APIs.

Resource Owner Password Flow

The diagram shows the flow for the Resource Owner Password grant type

The flow of the Resource Owner Password grant type is:

1. Authenticate: The user authenticates with the app using their username and password
2. POST /auth/oauth/token?grant_type=password: The app sends the username and password in Auth section (common technical user for all API calls but different per environment) and username and password in request body (different per customer) to the authorization server for validation.
3. Response (access_token, token_type, refresh_token, expires_in, scope): The authorization server validates the username and password and response an access token, token_type, refresh_token, expires_in and scope.
4. Request resource server: The app attempts to access the resource from the resource server by presenting the access token (instead of access token has to be used refresh token if access token expires).
5. Return Resource: If the access token is valid, the resource server returns the resources that the user authorized the app to receive.

Access Token

An OAuth Access Token is a string that the OAuth client uses to make requests to the resource server.

Access tokens may be either "bearer tokens" or "sender-constrained" tokens. Sender-constrained tokens require the OAuth client to prove possession of a private key in some way in order to use the access token, such that the access token by itself would not be usable.

Access tokens issued for the Management API and access tokens issued for any custom API that you have registered with Auth0 follow the JWT standard, which means that their basic structure conforms to the typical JWT structure, and they contain standard JWT claims asserted about the token itself.

Refresh Token

An OAuth Access Token is a string that the OAuth client uses to make requests to the resource server.

Environments

The addressable API base URL/URI environments are: 

Rate limits

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

The standard spike arrest limit per client is set to 1,000 messages per minute

Shared limits across all clients also applies. The limit is in terms of a quota, when quota is reached all clients will receive message below

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

429: Too many requests.  

Please contact api.dsc@dhl.com to get more information about it.

It is important that project teams share the expected Customer API volumes on their implementation with LINK team

Additional Information

There is a rate card in place for the use of the MySupplyChain Track & Trace API.   Please discuss potential commercials with your local MySupplyChain Track & Trace contact prior to API usage.

Example requests - All Order Types API

The following parameters need to be included in the URL for the All Order Types API:

API Call 1 (allorders):

API Call 2 (orderdetails):

API Call 2 (Document and POD documents):

This API is used to obtain the document id required to download the document

Body

It is possible to search using both order numbers and additional references.

API Call 3 (Documents):

This API is used to download POD docuemts

API Call 4 (Documents Others):

This PIS is used to download other documents.

specifics for the use of Track & Trace (formally CONNECTEDVIEW) (DHL SUPPLY CHAIN) API

In addition to the preceding section, the following terms and conditions apply only to Your usage of data or information received through the Track & Trace (DHL SUPPLY CHAIN) API:

• Data requested and received via the Track and Trace (DHL SUPPLY CHAIN) API, such as estimated delivery date, actual delivery date, transport status, transport history 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 our prior written consent.
• Tracking Data is provided to You and/or the entity you are authorized to represent (hereinafter “You”/”Your”) under the prerequisite, that You retrieved the according housebill number (DHL shipment 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.
• 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.
• 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 (including the transport history) 120 days after the last delivery is completed. DHL Supply Chain shall not be required to provide Tracking Data to You that is 120 days after the last delivery. Should You share Tracking Data with Your Customers "Delivered by Deutsche Post DHL Group" shall be displayed to Your Customers in text (minimum font size 12) at the time it is presented/submitted to them.