This API provides an interface for Deutsche Post International packet shipping and tracking services. It enables open integration channels for our customers and partners. 

Who is it for?

• European business customers(EU an non-EU) shipping worldwide

Services

SHIPPING

GOODS

Our shipping products cover tracked and untracked services for light-weight goods of up to 2kg. Depending on your contract with us, the following services are available

• Packet Tracked
• Packet Plus
• Packet (Standard / Priority)
• Packet Return

 DOCUMENTS

• Business Mail Registered / Letter Plus
• Business Mail (Standard / Priority) / Letter

Generally, the API provides:

1. Packet label
2. Airwaybill (AWB = transportation document)
3. Customs document (CN22)

TRACKING

The tracking service operation is used to inform you about the status of your trackable shipments. The resulting response will provide tracking events advising the whereabouts and status of your packets.

You can either track on the shipment level based on the AWB number or on single item (= packet) level based on the item barcode. For further details please go to the dedicated tracking section. 

More details on the relation between order, shipment, item and content item can be found here.

Using the API

The API is provided as REST API using OAuth 2.0 for authentication and authorization and JSON format for request and response messages. 

The API uses HTTPS (over SSL) protocol, the HTTP GET is used to retrieve data and HTTP POST is used to create, update or delete data. 

Get Access

1. To request access for our Production and Sandbox environments you have to sign up. To sign up, please get in touch with your local sales representative. You can contact them via the contact form. 
2. You will receive your credentials.
3. Check this User Guide documentation to understand how to get a valid Access Token and submit shipments or get tracking information.

Note: The Sandbox environment is currently not directly accessible from this documentation page - except for the Get AccesToken request.

Authentication

Access Token 

The API provides an OAuth 2.0 access token with various authorization scopes. 

The access token can be used to authorize access for the Deutsche Post Shipping API.

Get Access Token 

The Get Access Token API call provides OAuth 2.0 Bearer token with authorization scope, assigned to your client id, which will grants you an access to the Deutsche Post International Shipping APIs.

The API operation is secured by HTTP Basic authentication, therefore you have to provide Consumer Key and Consumer Secret as an username and password, when calling the API.

Example:

You will receive Consumer Key and Consumer Secret from Deutsche Post International representative in following format.
Credentials bellow could be used in this Sandbox environment to get the Access Token. (Business related requests are not possible with these credentials.)

Consumer Key: 5qsFCFLzeoz4C6PKJ7yH3NDQHgBEJLt7
Consumer Secret: P6mEGGaAZ2TdkLpD

When passing the Consumer Key and Consumer Secret via HTTPS request, using HTTP Basic authentication, you have to populate HTTP Header Authorization in following format.

Note: Consumer Key and Consumer Secret has to be encoded in base64-encoding. There is a space characeter between Basic and the base64-encoded string. There is a : character between the Consumer Key and Consumer Secret, when encoded in base64-encoding.

Authorization: Basic base64-encoded(Consumer Key:Consumer Secret)
Authorization: Basic NXFzRkNGTHplb3o0QzZQS0o3eUgzTkRRSGdCRUpMdDc6UDZtRUdHYUFaMlRka0xwRA==

Note: You can test the Get Access Token API directly from the documentation page. The Authorization HTTP Header was populated for you in the Console View on the right side of the screen.

You will receive following response in the JSON format.  

{
"access_token": "tlFkkjplZ8CyAKLq9BFyP1vqBMxX",
"token_type": "Bearer",
"expires_in": 17999,
}

Understanding of the response fields: access_token: Contains Access Token string for the Shipping / Tracking API authentication and authorization.

• token_type: Type of the OAuth 2.0 access token. Default value is "Bearer".
• expires_in: Time to live of the access token. Default value is 18000 seconds / 5 hours. After this time the token expires.
• scope: Authorization scope of access token. Default value for Shipping API is "dpilabel". It could contain multiple scope values, which will be separated by space character.

Access Token Info 

The Get Access Token Info API call provides an information about the issued token.

Revoke Access Token 

The Revoke Access Token API call provides you an option to revoke your Access Token, which not yet expired.
 

Environments

Deutsche Post International provides Production environment as well as Sandbox for development and testing.

Access to both environments is managed and you have to use OAuth 2.0 Access Token, when accessing the API resources.

Access Token could be requested via Get Access Token API, where you have to provide your API credentials: Consumer Key and Consumer Secret.

Note: You will have different identities for Production and Sandbox environment.

Sandbox:

You can use the Sandbox environment for development and testing purpose.

Sandbox Base URL: https://api-sandbox.dhl.com

Sandbox provides the same APIs as Production environment. > Note: The sandbox APIs cannot be called directly from this documentation at this time. Please see "Get Access" how to get credentials.

Production

For production purposes please use the production environment. The production environment hosts the same APIs as the sandbox, but with different base URL.

Production base URL: https://api.dhl.com

Important note: Please keep in mind that sandbox credentials are not valid for the production environment. To access the latter, please use the production set of credentials provided to you during on boarding.

Rate limits

For all API calls there is a rate limit applied. Default limit is set to for each client to allow 15 requests per second per API call.

For Trackings API ("Get Trackings" and "Get Tracking - Shipment"), there is applied the additional limit allowing to send only 1 tracking request with a specific barcode/awb in 1 hour.

When the limit is reached you will recieve an HTTP Status code 429: Too many requests.

Additional information

First of all it is important to understand the relation between order, shipment, item and content item in our context.

Items (or Single Shipment) are the packages, which you want to send to your customer with his address and eventually a S10-Barcode on the item label.

The order is some kind of wrapper, where you can add all your items you want to send. After finishing the order creation process, your items will be split into different shipments which can be identified by an Airwaybill (AWB) Number. The AWB Transport document issued by a carrier or a forwarder towards the business customer. The content item is relevant for customs declaration only, where you have to show, which contents are inside of an item (package).

Splitting the items into different shipments depends on which combination of product and service level they have. Items with the same product and service level are referred to the same shipment (and AWB Number).

Order content relation

There are 3 ways to create an order via our API:

1. Workflow 1 – low flexibility
   Create an order, where you add all items at once
   Create an order where you send all items at once during the create Order API call (Note: orderStatus = FINALIZE).
   This is recommended, if you know all items you want to ship at once. This workflow does not allow you to delete items from a shipment. Once items are assigned to a shipment, they should be sent out with that particular AWB.
    
2. Workflow 2 – medium flexibility
   Create an order, where you add items one by one
   Create an order where you add items one by one during the day/your process (Note: orderStatus = OPEN) and finalize the order at the end of the day/your process.
   This is the recommended way, if you don’t have all information about the items you want to send at once but incoming orders are processed step by step. This workflow allows you to delete or update items from an order/shipment.
    
3. Workflow 3 – high flexibility
   Create and print labels throughout the day without creating an order
   Items are processed and labels are printed individually after creation or in bulk at the end of the day/your process. It is not decided until later, which packages will be sent out at the end of the day/your process. An order is created and the AWB are printed once it is clear which items are going to be shipped.
   This workflow is recommended for customers and partner platforms seeking full flexibility in the processing of their incoming orders

Workflow 1: Create an order, where you add all items at once

1. Create Order (orderStatus = FINALIZE) by requesting CreateOrder, sending all information for items and paperwork at once. The response includes important information about itemIds and AWB Number, which you need in the further process.
    
2. Get all item labels per AWB by using the AWB Number you got from the first call by requesting Get Item Labels for each AWB Number.
   Or print labels individually by itemId you received in the createOrder-response.
    
3. Get all AWB labels for each AWB Number you got from the first call by requesting Get AWB Labels API for each AWB Number.

Workflow 2: Create an order, where you add items one by one

1. Create Order (orderStatus = OPEN), sending no extra information about paperwork or items at this point. The response includes information about the order ID, which you’ll need in the further process to add items to this order. (Note: You can open several orders in parallel if suitable differentiated by orderId).
    
2. Add items to an order by requesting Add Items to an Order. This step can be executed multiple times until all items you want to send are published.
    
3. Get label for each item you created in step 2 by requesting Get Item Label. Or print all labels per AWB in one call (see step 6).
    
4. Finalize the order by requesting Finalize Order and sending some further information explained in the API documentation.
    
5. Get all AWB labels for each AWB Number you got from the first call by requesting Get AWB Labels for each AWB Number.
    
6. Get all item labels per AWB by using the AWB Number you got from the finalize call by requesting Get Item Labels for each AWB Number.

Workflow 3: Create and print labels throughout the day without creating an order

1. Create single item.
    
2. Print label by requesting Get label for item.
   These two steps can be executed multiple times, until all items you want to send are published.
    
3. Creating an order for existing single items with the order data/paperwork and the items that shall be assembled to a new order by requesting CreateOrder.  
    
4. Print AWB by requesting Get AWB Label.

Specifics for the use of deutsche post international api

These Legal Terms do not replace and/or modify the “General Terms and Conditions Deutsche Post AG International Business, Dialogue Marketing, Packet” or any other mail and/or shipment services agreement, which govern Your Deutsche Post International shipments and mailings.

In case You act as a commercial agent on DEUTSCHE POST AG’s and/or its affiliates’ behalf, i.e. with DEUTSCHE POST AG’s and/or its affiliates’ consent, You are obliged to refer the customer (i.e. the sender of the shipments/mailings) to the relevant terms and conditions for shipment and mailings of Deutsche Post International (https://www.deutschepost.com/en/business-customers/tac.html).

You shall use the services and/or data that You receive via the DEUTSCHE POST INTERNATIONAL API only for the legitimate contractual purposes and only in connection with Your Deutsche Post International shipments and mailings or other services, and in compliance with all applicable laws and regulations, including but not limited to, laws regarding the use of personal data. 

When data or information has been sent or received outside of Deutsche Post International’s business hours, the processing of data and/or execution of the services will start according to the terms and conditions set out in the applicable Agreement or, absent thereof, as soon as reasonably practicable.

The following additional prerequisites and/or restrictions apply for the usage of data or information received via the DEUTSCHE POST INTERNATIONAL API:

• Shipping:
  • Please note that the receipt or printing of the airway bill or label does not constitute the contract of shipment. Such contract will be concluded when the labeled shipment is picked up or posted and accepted by Deutsche Post International. 
• Tracking:
  • You may only share tracking information with the shipper and the recipient of the Deutsche Post International shipment/mailing and no third party.
  • The submission of tracking information shall always be in compliance with applicable laws in the field of data protection and competition law, which includes that the data shall not be combined with advertisement or presented in a way that it could be regarded as advertisement.
  • If You are neither the sender nor the recipient of Deutsche Post International shipments/mailings, the tracking information refers to,
    • You shall ensure, that you are authorized to act on behalf of the sender;
    • You shall make the sender aware of the restrictions set out in these Legal Terms 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.
  • In no case shall you reveal and/or provide third parties with the airway bill number/shipment ID and/or tracking information and/or analyze, modify such information in any form and/or derive data/information especially for competitive reasons from it without our prior written consent.
  • Tracking information 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.
  • You shall delete the airway bill number/shipment ID and tracking information 180 days after the last tracking event is completed. Last tracking event shall be defined as the actual delivery unless otherwise agreed.