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).
• After recovery it is necessary to call up the endpoint in order to reactivate the system user.
• 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

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.

Receive daily push notifications

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:

• 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

• 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
}

Request to resend a push message

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

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.

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>

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.