Hereinafter we provide some important hints regarding the business customer portal user employed for the Push-API. Please read before implementing.

User role "system user" recommended to be used for push subscriptions

The API requires to apply credentials of your business customer portal user (GKP Benutzer) for authorization. On our business customer portal you can have multiple users under your customer account which are all allowed to be used for push-service subscriptions. However, we recommend to use a system user for your calls to the tracking push API.

• System user's password has to be changed once a year while it expires after 90 days for all other users. 
• System users cannot log in to the business customer portal as such. But they can use the "forgot password" function for recovery in case their password expires: Geschäftskundenportal (dhl.de).
• Please note: If the password of a user expires, related subscriptions won't receive any more push notifications.

User accounts get locked after 120 days of inactivity

In order to avoid that a user gets locked due to inactivity you have to call the API at least every 119 days. Any request to the API which requires user credentials will reset the inactivity timer. We recommend to use a regular call of the API operation "GET /certificates/default" for this purpose.

• In case your user gets locked anyways, please use the "forgot password" function on the business customer portal login page to recover: Geschäftskundenportal (dhl.de).
• As soon as a user got locked, it isn't possible to administrate related push subscriptions anymore (e.g. create or delete a subscription) . However, at first we'll continue sending push notifications to the registered endpoint.
• After another 185 days (305 days of inactivity in total) the according business customer portal user gets deleted by an automatic process. In consequence the related push subscriptions get deleted  as well and no further push notifications will be send to the push client. In such case you have to create a new system user with your admin user on business customer portal and all push subscriptions for this user must be created afresh.

Overview

Subscribe to our daily push notifications and increase transparency by receiving a message once your discounted shipment got processed in a destination mail center.

Enable your customer service to trouble shoot potential customer complaints on mail services.

Hereinafter you find a description and hints for each available API call.

Subscribe to push notifications (POST /subscription)

When subscribing to our push service you have to provide some basic parameter

Please note:

• Up on subscription to our service the provided validation endpoint must be available instantly as we may send a validation request immediately to this endpoint.
• We won't verify the provided email address except for a basic format check. Hence, please make sure to provide the correct email address up on creating a subscription.

If the request is valid, a status 201 is returned. In the response body the subscription ID is transmitted (as field "id").

Example response when creating a subscription:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "dataCallbackURL": "https://your-callback-url",
  "validationCallbackURL": "https://your-validation-url",
  "numberOfRecords": 10000,
  "exportFormat": "application/json",
  "language": "de",
  "email": "sample@mail.com"
}

At this point the subscription is not persisted and might undergo further internal validation. When this validation is successful, we'll send a validation message to the provided validation endpoint. The message will contain the confirmation URL as well as a signature string.

Example content of a validation message:

{
  "confirmationURL": "https://api-eu.dhl.com/post/de/tracking/push/v2/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6/confirmation",
  "signature": "nvf3984ht789ch42to34z78c5fzn2389z89234ztcf8923zc5t8234895t"
}

To confirm your subscription, call the URL "POST /subscriptions/{id}/confirmation" and pass the string that was provided as "signature" to your validation endpoint.

Please note:

• Please keep the subscription ID safe as you might need it for further administration of your push subscription.
• In case we cannot reach the provided endpoint we will retry delivery of the validation message every 60 minutes up to 24h.
• Please respond to the request providing the validation url. Otherwise, we'll assume your endpoint isn't reachable.
• Confirmation of the subscription by calling the validation url is mandatory. We won't provide push notifications until successful validation. In case of no validation within 24h we'll cancel the subscription.
• In case the validation message doesn't come through unexpectedly you can fetch data on your subscriptions via "GET /subscriptions" (see below) and check the provided endpoint for typos or the like. If the URL is faulty, please delete the subscription an create another one by providing the correct endpoint url.

Example request to the provided validation url (see the OpenAPI specification described as callback event "onValidation" within the method "POST /subscriptions" for further details):

curl -X POST 'https://api-eu.dhl.com/post/de/tracking/push/v2/subscriptions/62b31bb989806f4123456789/confirmation'
-H 'DHL-API-Key:PasteHere_ConsumerKey'
-H 'Authorization:Basic gkp_user_pass_base64_encoded'
-H 'Content-Type: application/json' -d '{ "signature": "string" }'

Receive daily push notifications

Once the subscription got validated we'll provide push notifications on a daily basis, starting at 2pm Central European Time.

Any status changes that occur after this time will not be sent in the push notifications for the current day, but will be sent the next day.

When sending push notifications, there may be a high volume of data. Therefore, it may take some time before your push notifications are sent.

Please note:

• All push notifications get signed by DPDHL. The certificate is meant to verify that the according push message was send by us. The verification by you is optional.
  • Request a certificate using "GET /certificates/default"
• We retry to send push notifications in case your client cannot be reached
  • Your push client application must acknowledge receipt of a push notification message by an http status code 200. In case this doesn't happen, the push service retries delivery for up to 5 days.
• No retroactive push notifications for newly created subscriptions
  • Once you subscribed successfully for push notifications via the tracking push API, we will start caching your shipment data for daily notification. So, even if you subscribe to push notifications before 2pm it might happen that you won't receive shipment data the same day yet if there is no data available for the last processing day.
• The OpenAPI specification for the PUSH notification is described as callback event "onDataEvent" within the method "POST /subscriptions" (see the API Specification)
• Details about the data structure are described in the section "Shipment data".

Example Push Request:

{
  "timestamp": "2022-08-19T09:30:14.930741Z",
  "principal": null,
  "session": null,
  "request": {
    "method": "POST",
    "uri": "http://localhost/api/v1/",
    "headers": {
      "content-length": [
        "506"
      ],
      "host": [
        "x"
      ],
      "x-signature": [
        "x"
      ],
      "content-type": [
        "application/json; charset=UTF-8"
      ],
      "x-signature-id": [
        "x"
      ],
      "accept": [
        "*/*"
      ],
      "user-agent": [
        "AHC/2.1"
      ]
    },
    "body": {
      "shipments": [
        {
          "shipmentIds": [
            {
              "shipmentId": "99999999860031CCD95F"
            }
          ],
          "referenceId": "228e771e-f7c5-43b8-916b-55a262d3ed3a",
          "flags": {
            "finalState": false
          },
          "currentEvent": {
            "state": "BZE",
            "status": "lang808",
            "shortStatus": "kurz807",
            "processingDate": "2022-08-19"
          }
        },
        {
          "shipmentIds": [
            {
              "shipmentId": "99999999860031CCD95F"
            }
          ],
          "referenceId": "fffac672-0558-4c8a-a689-bee54acf093d",
          "flags": {
            "finalState": false
          },
          "currentEvent": {
            "state": "REDIRECTED",
            "status": "lang816",
            "shortStatus": "kurz815",
            "processingDate": "2022-08-19"
          }
        }
      ]
    },
    "remoteAddress": null
  },
  "response": {
    "status": 200,
    "headers": {
    }
  },
  "timeTaken": 9
}

Administrate active subscriptions

Delete a subscription (DELETE /subscriptions/{id})

If push notifications are no longer required, please delete your push subscription.

Read back active subscriptions (GET /subscriptions)

By calling "GET /subscriptions" you will retrieve details on all active subscriptions related to the submitted user.

Please note: This request is only available on production environment. It will always return "User not allowed" when called on sandbox environment. Please provide the ID of your test subscription in order to retrieve configuration details.(see below)

You can also retrieve data of a single subscription by submitting the subscriptionId on the url: "GET /subscriptions/{id}"

Change an active subscription (PUT /subscriptions/{id})

You can change following parameters on an active subscription.

• exportFormat
• numberOfRecords
• language
• email

Please note: If our push service has already started to prepare the push messages, a change of settings might not apply the same day anymore.

The endpoint url and the applied business customer portal user cannot be changed on active subscriptions. If a change's needed, you have to delete the subscription and create a new one applying the other user and/or new endpoint.

Requests to resend a push message (POST /subscriptions/{id}/replay)

In case of data loss on your client system you can request the push service to re-send all push notifications delivered on a particular date.

Please note, the parameter "forDate" has to be provided as POST-Parameter in format yyyy-MM-dd.

{
  "forDate": "2023-03-20"
}

The data will get resend instantly. Please note that old shipment updates get regularly deleted from our database. Currently you can request to resend push notifications of the past 21 days. Depending on operational needs we might shorten this period in future.

Error Handling

Please find below an overview of potential error responses and related recommended actions.

Error messages are delivered in the following format

{
  "title": "ok",
  "statusCode": 200,
  "instance": "string",
  "detail": "string"
}

The "instance" field contains the path to the resource on which the error occurred, i.e. the called API URL

Different IDs

As a business customer, the items you post with us are processed as part of orders that are identified with a unique order number.
Each order contains multiple items.

If you use IT franking, the same franking ID can be used several times on different items over extended periods of time.
For the above reasons, we assign a unique reference number when your item is first scanned, under which all further events affecting the item will be processed. If franking IDs repeat, the reference number ensures that events are only assigned to the item if they are plausible in terms of aspects such as time.
Regarding item information with our Push API or data transfer via SFTP, we will send you information when your item undergoes a status change for which notification is a contractual requirement. A separate data record will be provided for each change of status of an item. The data record contains the current logistical status and always quotes the same reference number, the associated order number and the franking ID.

We recommended that you process item status updates using the combination of franking ID (which appears as shipmentID in the data record), order number (orderID) and reference number (referenceID).

Data Structure

The following table gives an overview on the information provided per shipment within the push notifications. Please note that one push message might contain status events of up to 10.000 shipments.

Please note: Due to structural differences between json and xml format, the element names in xml differ slightly from those of the properties in json. The structure of below table follows the json format. However the data fields as such have the same name and content in both formats.

Please note: for discounted shipments (Teilleistungen) the push notification will only include fields in bold.

*earliest available in 2023

** Please note: As the underlying data format is generic for different types of shipments, "shipmentIds" got specified as an array. However, for discounted shipments (Teilleistungen) there will be always just one shipmentId (Frankier ID). So, all updates on a discounted shipment will contain the same shipment ID as well as the same reference ID. Each object on the array shipments will contain information related to exactly one shipment.

***Please note: In case of using IT franking as preferred franking method, shipment IDs (FrankierID) might recur over a longer period. In order to ensure an unambiguous mapping of your shipment updates, please retain the order of as well as the shipment ID (FrankierID). The combination of shipment ID (FrankierID) and order ID is always distinct.

Query states of discounted shipments (Teilleistungen)

Following status notification exist for discounted shipments:

Please note:

• At first we'll provide just the REDIRECTED event in case of redirected shipments. No further status update will be notified afterwards.
• In future the notification BZE will follow a REDIRECTED event, whereby it can happen that both events get provided within the same push operation (same date) or at two different push operations (two different dates). We recommend to regard this future development when implementing your push client.

Error messages in case of paused data transmission

In case we are not able to provide you with shipment updates on our daily push, we'll send an error message instead.

USER_NOT_EXISTS

USER_STATUS_INVALID

USER_PASSWORD_EXPIRED

INTERNAL_ERROR

Example Messages

JSON:

{
"shipments":
    [
        {
        "currentEvent":
            {
            "processingDate": "2023-06-28",
            "shortStatus": "Transport",
            "state": "REDIRECTED",
            "status": "Die Sendung wurde am 28.06.2023 auf Wunsch des Empfängers nachgesandt bzw. an eine abweichende Anschrift weitergeleitet."
            },
        "flags":
            {
            "finalState": false
            },
        "orderId": "123456789",
        "referenceId": "0F3C0AE6-9AF3-42B0-A333-0A822C6C6573",
        "shipmentIds":
            [
                {
                "shipmentId": "3D1400370100000ACC3A"
                }
            ]
        }
    ]
}

XML:

<?xml version='1.0' encoding='UTF-8'?>
<ShipmentDocument>
      <shipments>
            <shipmentIds>
                  <shipmentIds>
                        <shipmentId>3D1400370100000ACB50</shipmentId>
                  </shipmentIds>
            </shipmentIds>
            <referenceId>F5F8D697-DD30-4467-A46A-724C3CA2A3D8</referenceId>
            <orderId>123456789</orderId>
            <flags>
                  <finalState>false</finalState>
            </flags>
            <currentEvent>
                  <state>REDIRECTED</state>
                  <status>Die Sendung wurde am 28.06.2023 auf Wunsch des Empfängers nachgesandt bzw. an eine abweichende Anschrift weitergeleitet.</status>
                  <shortStatus>Transport</shortStatus>
                  <processingDate>2023-06-28</processingDate>
            </currentEvent>
      </shipments>
</ShipmentDocument>

Error Case XML:

<shipmentDocument>
  <error>
    <code>USER_STATUS_INVALID</code>
    <message>Push not executed: Wrong user status.</message>
  </error>
</shipmentDocument>

In order to further test our API you can download our test suite here

The test suite can be used as a collection on the software postman: Postman API Platform | Sign Up for Free

Following steps have to be taken in order to use it:

• request access to Sandbox environment and receive an API-key (see Get Access for further details)
• import collection into postman
• replace value of the variable "dhl-api-key" by your personal API-key

• update body of "create subscription" request: enter your test endpoints and adjust further configuration parameter as needed

Now you can create a push subscription. Please remember to call the validation link that's going to be send to the provided customer endpoint.

With the validation message you'll also receive a subscription ID. Set this as value for path variable "id" when using delete, get or update operation.

Please note:

We won't actively push data to your endpoint out of our sandbox environment. In order to receive push data you have to call "POST sandbox/generate//{id} ". This will trigger test data to be pushed instantly to the endpoint of the given subscription.

Network Access

Which firewall rules must be set up?

The relevant IP addresses are listed in the "Environments" section. To call the web services from your network, the listed "Inbound IPs" must be reachable. The push endpoints on your side must allow requests from the "Outbound IPs".

IT Customer Support & Integration Post

Tel: +49 (0)228 182-23500

Email: IT-CSP@deutschepost.de

Geschäftszeiten: Mo-Fr 8.00 bis 16.00 Uhr

Technischer Support Geschäftskundenportal

Tel +49 (0)228 76367679

Geschäftszeiten: Mo-Fr 8.00 bis 18.00 Uhr

Specific legal terms for the access to and use of the Mail Communication Tracking Push API 

• The (productive) use of the Mail Communication Tracking Push API and the related DPDHL Services has the following pre-requisites:
  • Activation of the Customer, who is using the mail communication tracking service (discounted rate) on Deutsche Post AG’s business customer portal (“Geschäftskundenportal”)
  • Existence of a valid business customer identifier (“GKP-Kennung”)
  • Acceptance of the terms and conditions for the provision and use of the mail communication tracking service (discounted rate) (“Allgemeine Geschäftsbedingungen für die Bereitstellung und Nutzung des Service “Verfolgen Brief Teilleistungen”) as published in the business customer portal (“Geschäftskundenportal”)
• In the event of a conflict or inconsistency between the General Developer Portal Terms of Use and the terms and conditions for the provision and use of the mail communication tracking service (discounted rate), the terms and conditions for the provision and use of the mail communication tracking service (discounted rate) shall prevail.

Besondere Bedingungen für den Zugang zu und die Nutzung der Push API für den Service „Verfolgen Brief Teilleistungen"

• Für die (produktive) Nutzung der Push API „Verfolgen Brief Teilleistungen“ und der damit verbundenen DPDHL Services ist die Erfüllung der folgenden Voraussetzungen erforderlich:
  • Aktivierung des Kunden, der den Service Verfolgen Brief Teilleistungen nutzen will, im Geschäftskundenportal der Deutschen Post AG
  • Vorhandensein einer gültigen Geschäftskunden-Kennung ("GKP-Kennung")
  • Akzeptanz der im Geschäftskundenportal veröffentlichten Allgemeinen Geschäftsbedingungen für die Bereitstellung und Nutzung des Service "Verfolgen Brief Teilleistungen"
• Im Falle eines Widerspruchs oder einer Unstimmigkeit zwischen den Allgemeinen Nutzungsbedingungen für das API Developer Portal („General Developer Portal Terms of Use“) und den Allgemeinen Geschäftsbedingungen für die Bereitstellung und Nutzung des Service "Verfolgen Brief Teilleistungen", gelten die Allgemeinen Geschäftsbedingungen für die Bereitstellung und Nutzung des Service "Verfolgen Brief Teilleistungen" vorrangig.