Mail Communication Tracking Push (Post & Parcel Germany)
v 2.0.0
Division: Post & Parcel Germany, Post

Best for:

  • Business Customers using Mail Communication Services (discounted rate) (Verfolgen Brief Teilleistungen)
  • Subscribing to DPDHL Mail Communication Tracking Push API
    • Register for Push API subscription
    • Provide your client URL and business customer portal user
    • Start receiving daily mail shipment status pushed from DPDHL to your endpoint
Region: Germany
Used for: Tracking
Overview

The Tracking Push-API allows business customers that use mail communication services to subscribe to daily push notifications on the shipment status of their mail items.

Scope

Currently the API can be used by customers with mail communication services on discounted shipments (Verfolgen Brief Teilleistungen).

The API implements following operations to manage subscriptions:

  • retrieve a certificate to verify signed push messages
  • create a push subscription
  • delete a push subscription
  • retrieve information on active push subscriptions
  • edit a push subscription

API Flow

Using the API

The API has been designed for use by developers. You will need basic knowledge of REST APIs, JSON, and HTTPS.

In order to receive push notifications you must provide a consumer endpoint (URL) to which notifications can be send.

  1. The endpoint must be able to receive HTTP PUT/POST requests and process shipment update notifications, which will be send to it in either JSON or XML format.
  2. The endpoint must support secure communication via HTTPS, i.e. it must use a valid TLS certificate.
User Guide

The following provides an overview on how to get access to the API.

  • Technical Details on the API calls can be found here: API Specification
  • Further hints on API usage are given in section "Hints" and following.

Get Access

In order to use the Mail Communication Tracking Push API your organization has to agree to the terms and conditions for mail communication services (Verfolgen Brief Teilleistungen) within the business customer portal. After that we'll enable your business customer portal user to subscribe to push notification services.

 

You must register any push client application you develop.

To register your push client and get your API subscription keys:

  1. Click Get Access Button on top of this page and the create App form will open with the sandbox environment of the API "pp-post-de-push-sandbox" being pre-selected.
  2. If required, change selection to "pp-post-de-push-prod"
  3. When you have completed the form, click the Create App button.
  4. You will now find your App under My Apps.
  5. From the My Apps screen, click on the name of your app.
    The Details screen appears.
  6. 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.
  7. Click the Show link below the asterisks that are hiding the Consumer Key.
    The Consumer Key appears.

Alternatively to "get access" you can go to My Apps on the portal website and click the + Create App button:

  • The "Create App" form appears.
  • Complete the Create App form and select either the entry "pp-post-de-push-sandbox" or "pp-post-de-push-prod".

Authentication

Every call to the API requires a consumer key. This key needs to be specified in the request header (DHL-API-Key). 

Please note that different keys are required for sandbox respectively production environment. Both can be requested via above procedure and copied from API credentials section.

    Environments

    The addressable API base URL/URI environments are:

    Environment Inbound IPs Outbound IPs Description
    https://api-eu.dhl.com/post/de/tracking/push/v2/

    34.89.220.138

    52.157.254.11

    20.56.189.152

    to

    20.56.189.159

    Production environment

    https://api-sandbox.dhl.com/post/de/tracking/push/v2/

    34.89.220.138

    35.229.17.35

    35.198.247.238

     

    52.157.254.11

    20.56.189.152

    to

    20.56.189.159

    Sandbox environment

    please use following business customer portal user (GKP Benutzer)

    Username: sandbox-testuser
    Password: sandbox-passw0rd

    Inbound: WebService calls for the domains api-eu.dhl.com and api-sandbox.dhl.com are routed to these IP addresses

    Outbound: PUSH messages are sent from these IP addresses. Please make sure that these IP addresses are unblocked in your firewall for incoming requests to your endpoints.

    Error codes

    See the section "Error Handling" below for more detailed information on Troubleshooting

    Error Code Description Troubleshooting/Action
    400 Bad Request The request contains incorrect data or is incorrectly formatted. Please check the data in the request.
    401 Unauthorized The supplied user account and credentials could not be authenticated.
    403 Forbidden The user account has insufficient or no permissions to perform the action.
    404 Not Found The ID that should be changed or deleted is not known.
    429 Too many requests The rate limit was exceeded (see "Rate Limits").
    500 Internal Server Error Request failed due to an internal error. Please try again later

    Rate limits

    The API enforces limits on the number of requests and the maximum rate. These limits are specific to environment and API key. Please note the following restrictions:

    • a maximum of 3 (three) subscriptions per user is allowed.
    • a maximum of 7 (seven) replay requests per day is allowed.

    They will not usually impose a limitation for your regular use. However, should the limit be reached, you will receive an HTTP Status code:

    429: Too many requests.
    

    Simple HTTP request example

    curl -X GET 'https://api-eu.dhl.com/post/de/tracking/push/v2/subscriptions' -H 'accept: application/json' -H 'DHL-API-Key:PasteHere_ConsumerKey' -H 'Authorization:Basic gkp_user_pass_base64_encoded'
    Hints

    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.
    Use Cases

    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

    Param Description
    dataCallbackURL

    URL of the endpoint used to receive the daily push notification documents.

    validationCallbackURL

    URL of the endpoint used once to validate the push notification.

    numberOfRecords

    Amount of shipments that will get enclosed in a single push notification message.

    • min = 1
    • max = 10.000
    exportFormat

    Either XML (""application/xml") or JSON ("application/json") may be chosen as format for the notification documents.

    language

    We provide descriptions of the shipment status in either English ("en") or German ("de") language.

    email

    You have to provide an email address. We we will use this email to send warning messages in case of technical problems with the delivery of push notifications (e.g. your endpoint couldn't be reached by our service).

    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

    status code title detail recommended action
    400 Id ist not valid The provided ID is not valid and cannot be parsed.

    The sent request required a push subscription ID to be provided. The ID provided does not have a valid format.
    This error can occur with all webservices that require a subscription ID as part of the URL

    • POST /subscriptions/{id}/confirmation
    • DELETE /subscriptions/{id}
    • PUT /subscriptions/{id}
    • GET /subscriptions/{id}
    • POST /subscriptions/{id}/replay
    400 Request is not valid Request cannot be processed due to invalid data.

    One or more of the parameter provided isn't valid.

    For "POST /subscriptions" (create subscription) and "PUT /subscriptions/{id}" (change subscription).

    • make sure that the protocol for both of the callback URLs is "https" (only for POST request, callback URLs cannot be changed with the PUT request)
    • the batch size (numberOfRecords) must be in the range from 1 to 10.000
    • the export format must be "application/json" or "application/xml"
    • the language must be "de" or "en"
    • the email adress must be syntactically correct

    Please check here for further details on valid push subscription configurations.

     

    for "POST /subscriptions/{id}/replay"

    • make sure the provided date in the field "forDate" contains a valid date in the format "yyyy-MM-dd".
    • the provided date in the field "forDate" must not be before the deletion period of 21 days. We keep shipment updates for 21 days to allow for resend requests. Requesting push data from earlier dates will return an error message.
    401 User is not authenticated User is not authenticated.

    We couldn't authenticate the business customer portal user provided with this request. This might happen due to:

    • The sent username or password is not correct. Please check username and password.
    • User got deleted in business customer portal -> please check if the provided user account still exists. If not, you have to create a new push subscription with another user
    403 User is not authorized User is not allowed to perform this action.

    We couldn't authorize the business customer portal user provided with this request. This might happen due to:

    • User locked due to inactivity -> please see following hints
    • User password expired -> please see following hints
    • User got deactivated in business customer portal -> please check if user is still active; if not, please contact our business customer portal support.
    • User does not have the necessary permissions for mail communication services -> Please check the user rights in business customer portal and adjust as needed
    404 Verification failed Verification token was not valid or has expired.

    This response is returned, if the confirmation of a newly created subscription failed, when calling the service
    POST /subscriptions/{id}/confirmation.

    Reasons for this response might be

    • the signature does not match the subscription ID.
    • There is no push subscription for the supplied subscription ID

    Please note that the confirmation of the subscription must be within 24 hours. In case of no validation within 24h we will cancel the subscription. Please check by calling GET /subscription/{id} if the subscription exists. If this request returns 404, the subscription wasn't verified in time. Please create a new one.

    404 Subscription not found The referenced subscription does not exist.

    The request required a push subscriptionID to be provided. The ID provided does have a valid format, but no push subscription could be found with this ID.

    Please check the ID provided. If correct, we might have deleted your push subscription. This happens in case your business customer portal user got deleted or the endpoint of the push subscription hasn't been reachable for long time. Please contact our customer support for further information.

    This error can occur with the following webservices

    • PUT /subscriptions/{id}
    • GET /subscriptions/{id}
    • DELETE /subscriptions/{id}
    • POST /subscriptions/{id}/replay
    500 Internal error Request failed due to an internal error. Due to a technical error your request could not be processed. Please try again later

     

    Shipment data
    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.

    Level 1 Level 2 Level 3 example content description
    error        
      code   "USER_PASSWORD_EXPIRED" error code in case we pause data transmission
      message   "Push not executed: Password of user expired" error message in case we pause data transmission
    shipments(1-n)       one push notification message contains up to 10.000 shipments
      shipmentIds (1-n)**      
        shipmentIdType* "FRANKIT_DMC" franking
        shipmentId   franking ID resp. shipment ID
        frankingDate* "2021-05-03" franking date as per matrix code
      referenceId  

    "123456AB-78CD-1234-AB12-A12B3456789A"

    unique reference ID of the shipment (all notifications on a shipment will contain the same reference ID)
      sender frankingMaschineId* "1D23001A01" serial number of the franking machine used for this letter (10-digit hexadecimal)
      recipient      
        name* "Frau Martina Mustermann" recipient name
        street*

    "Musterstraße"

    recipient street
        housenumber*

    "10a"

    recipient house number
        postalcode*

    "53115"

    recipient postal code
        postalcodeType*

    "1"

    ORIGINAL_POSTCODE
        city*

    "Musterstadt"

    recipient city
        cityDistrict*

    "Musterstadtteil"

    recipient district
        postbox* "Postfach 10 20 30 " recipient P.O. box
        country* "DE" recipient country code (2-character ISO code)
        countryName* "Deutschland" name of the recipient country (provided according to push subscription's language settings, e.g. "Deutschland" or "Germany")
      orderId***   "56789432101274" 14-digit order ID
      flags finalState true indicates whether the enclosed shipment status is the final status on the shipment tracking (boolean)
      product      
        productNameShort* "Brief mit Einschreiben" short description of the basic product plus additional letter mail service
        productNameBasis* "Standardbrief" short description of the basic product
        productNameAddOn* "Einschreiben Rückschein" short description of the additional letter mail service
      estimatedDeliveryDate delivery* "2021-05-03" estimated delivery date (yyyy-mm-dd)
      currentEvent      
        state "BZE" query status
        status "Ihre Sendung wurde am 24.05.2021 bearbeitet" description of the shipment status in the language chosen when subscribing to push notifications
        shortStatus "Transport" short description of the shipment status in the language chosen when subscribing to push notifications
        timestamp* "2021-05-24T10:01:04.000000000+00:00" time stamp of the current shipment status (ISO 8601)
        processingDate  "2021-05-24"

    processing date of the letter (yyyy-mm-dd)

    please note: the processing date starts at 7am and ends at 6:59am of the following calendar day

      events (1-n)      
        historicalState* "BZE" query state history
        finalState* true indicates whether the enclosed shipment status has been the final status on the shipment tracking history (boolean) 
        status* "Ihre Sendung wurde am 24.05.2021 bearbeitet" description of the shipment status history in the language chosen when subscribing to push notifications
        shortStatus* "Transport" short description of the shipment status history in the language chosen when subscribing to push notifications
        timestamp* "2021-05-24T10:01:04.000000000+00:00" time stamp of the shipment status history (ISO 8601)

    *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:

    query state   (currentEvent.state)

    short description   (currentEvent.shortStatus)

    long description (currentEvent.status)

    REDIRECTED Transport

    Die Sendung wurde am <<TT.MM.JJJJ>> auf Wunsch des Empfängers nachgesandt bzw. an eine abweichende Anschrift weitergeleitet.

    BZE Transport

    Ihre Sendung wurde am <<TT.MM.JJJJ>> bearbeitet.

    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.

    error code error message annotation
    USER_NOT_EXISTS
    Push not executed: unknown user

    Please ensure the business customer portal user provided at creation of the subscription still exists.

    In case the according user got deleted, we won't provide any data on related subscriptions. You will have to create a new subscription with another user account.

    Please note:

    In case of inactivity (no login with that user) we automatically delete the user account after a while. For further explanation please see corresponding hints within this documentation.

    After a grace period we will delete the push subscriptions of deleted users.

    USER_STATUS_INVALID

    Push not executed:  Wrong user status

    If applicable we've deactivated your user account. Please get in touch with our customer service.
    USER_PASSWORD_EXPIRED
    Push not executed: Password of user expired

    The password of the user applied for this push subscription expired. For further explanation please see corresponding hints within this documentation.

    INTERNAL_ERROR
    Push not executed: internal error

    Internal error: We'll catch up on push notifications as soon as possible.

    Where required, please contact our customer service.

     

     

    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>
    
    
    
    How to test the API

    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

    screenshot dhl-api-key variable

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

    screenshot endpoint configuration

    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.

    screenshot path variables

    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.

     

    FAQ

    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".

    Support
    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

    Legal Terms

    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.
    Json Schema Shipment Data OCTET-STREAM - 3.15 KB
    Postman Collection OCTET-STREAM - 48.84 KB
    1.0.0
    10.Jun.2022
    • Initial version
    1.0.1
    28.Jun.2022
    • sandbox specific functions added
    • revised xml example

     

    1.1.0
    17.Oct.2022
    • new swagger file including resend function
    • updated postman collection
    • schema files added for XML and JSON shipment data format

     

    2.0.0
    10.May.2023

    Change of webservice URLs

    The URLs of the web services have changed, see the following table.
    Mostly only the URL changes: "/subscription/" became„/subscriptions/“.

    New Webservice

    Description

    Old Webservice

    GET /certificates/default

    Gets the certificate chain of the push service (X.509).

    GET /cert.pem

    GET /subscriptions

    Accesses all push subscriptions for the logged-in user

    GET /subscription

    POST /subscriptions

    Create push subscription with settings

    POST /subscription

    GET /subscriptions/{id}

    Gets a push subscription by its id

    GET /subscription/{id}

    PUT /subscriptions/{id}

    Update push subscription by UUID

    PUT /subscription/{id}

    DELETE /subscriptions/{id}

    Deletes a subscription

    DELETE /subscription/{id}

    POST /subscriptions/{subscriptionID}/confirmation

    Confirms the validity of the subscription

    GET /verify/{id}

    POST /subscriptions/{subscriptionID}/replay

    Requests events to be replayed

    GET /repush/{id}/{day}

     

    Data Structure for Subscription

    Within the JSON data structure for subscriptions, field names have changed

    • exportEndpoint becomes dataCallbackURL
    • documentAmount becomes numberOfRecords

     

    Also, an additional field "validationCallbackURL" has been added.
    This allows a separate callback URL to be specified for subscription validation.
    Previously, the same callback URL was used for validation as for data delivery.

    Use the callback URL for data delivery at this point if you use this callback URL already for validations

    Provide the callback URL for data delivery if this callback URL is already used for validations

     

    Changed values for export format

    The possible values for the "ExportFormat" field have been changed to the corresponding content types

    Instead of                   "json"                   now     "application/json"

    Instead of                   "xml"                    now     "application/xml"

     

    Change when saving subscriptions

    When creating or modifying subscriptions via

       POST /subscriptions

       PUT /subscriptions/{id}

    in case of success (status 200)

    • instead of the status object sent in the response body (code, message, timestamp)
    • now an object with the input data is returned.

    When creating new subscriptions, in addition the generated ID of the subscription is returned.

     

    Change when validating subscriptions

    The one-time validation for newly created subscriptions changes.

    With the upcoming release, a separate callback URL for validation can be specified in the subscription (see above)

     

    For validation, this callback URL is called with a modified record:

    • the attribute name of the URL to be called changes from "validationUrl" to "confirmationURL".
    • the field "pushSubscriptionId" is omitted, it is included in the "confirmationURL", and is also supplied when creating subscriptions.
    • a field "signature" is added, which is used as additional security measure

     

    Call the web service provided in the "confirmationURL" for confirmation. This is the call of

    POST /subscriptions/{subscriptionID}/confirmation

     

    Compared to the previous confirmation the HTTP method changes from GET to POST.

    As POST parameter the content of the field "signature" must be supplied (from the callback URL)

     

    Change when reading subscriptions

    If individual or all existing subscriptions are read via

    GET /subscriptions

    GET /subscriptions/{id}

    only the data of the subscription(s) will be delivered as response.

    Previously, this data was encapsulated in an object that also contained status information.
    This status information and the encapsulating object are omitted.

     

    Change when replaying PUSH messages

    To resend PUSH messages, the web service

       POST /subscriptions/{subscriptionID}/replay

    can be used

     

    The HTTP method has changed from GET to POST. The requested replay date must be supplied as POST parameter.

     

    Omission of the sandbox web service

    The web service

      POST /sandbox/generate/{id}

    which was previously only available in the sandbox environment for generating test PUSHs in the development environment is no longer available.

    To generate test PUSHs you can use the replay web service

     

    Change of http status code on successful calls

    For some web services, a different status code is sent instead of http status 200 on a successful call

     

    Status 201 „Created“

    HTTP status 201 is returned in case of success

    • POST /subscriptions/{subscriptionID}/replay

     

    Status 204 „No Content“

    For the following web services no data is provided in the response.
    Therefore, the more appropriate HTTP status 204 is used instead of 200

    • POST /subscriptions/{subscriptionID}/confirmation
    • DELETE /subscriptions/{id}

     

    Change of error handling

    There are two changes in error handling that affect all web services

    The possible 4xx error codes have changed

    • some web services may return different error codes than before
    • a new error code 403 "Forbidden" can be returned.
    • error codes 406 and 422 are omitted and are no longer returned

     

    The error status data object returned in the event of an error (status 4xx) has a different structure.
    Instead of code, message, timestamp now the attributes title, statusCode, detail, instance are returned