DHL Paket DE Sendungsverfolgung (Post & Paket Deutschland)
v 1.0.0
Division: Post & Parcel Germany, Parcel

Geeignet für:

Mit der DHL Sendungsverfolgung API können Privat- und Geschäftskunden jederzeit den Sendungsstatus und -verlauf von Sendungen abfragen.

Region: Deutschland
Used for: Verfolgung
Übersicht

Sie befinden sich auf der Dokumentations-Seite der DHL Paket DE Sendungsverfolgung API der Post & Paket Deutschland GmbH. In den folgenden Kapiteln bieten wir Ihnen:

Umfang

Mit der DHL Sendungsverfolgung API können Sie jederzeit den Sendungsstatus und -verlauf von Sendungen abfragen.

Die Abfrage erfolgt anhand von unterschiedlichen Requests:

  • Sendungsverfolgung-API für öffentliche Nutzung ("public"-Abfrage) - es werden die Daten analog zur öffentlichen Sendungsverfolgung ( www.dhl.de) geliefert.
  • Sendungsverfolgung-API für Geschäftskunden ("business"-Abfrage) - es werden, eingeschränkt auf die Sendungen eines Geschäftskunden, alle relevanten Sendungsdaten geliefert.

Benutzung der API

Folgende Informationen werden bereitgestellt:

  • Detaillierte Informationen zum Sendungsstatus (ggf. nach Eingabe der Empfänger-PLZ)
  • Anzeige des Sendungsverlaufs
  • Produkt / Services Informationen
  • Voraussichtlicher Zustelltag / voraussichtliches Zustellzeitfenster (gesondertes Recht erforderlich)
  • Details zum Absender, Empfänger und zur Zustellung (Sendungsverfolgung für Geschäftskunden)

Die DHL Sendungsverfolgung API stellt Sendungsdaten zu folgenden Produkten bereit:

  • DHL Paket (national/international) Sendungen
  • DHL Retouren (national/international)
  • Warenpostsendungen
  • DHL 2-Mann-Handling Sendungen
  • Importsendungen

Für DHL Express Sendungen steht die MyDHL API zur Verfügung. Alle relevanten Informationen sind hier einsehbar.

Darüber hinaus besteht die Möglichkeit, über einen HTTP-Direktaufruflink das Suchergebnis zu einer bestimmten Sendung direkt auf www.dhl.de anzuzeigen.

Anwenderhandbuch

Integrationsmöglichkeiten durch APIs

Der Service Sendungsverfolgung kann auf verschiedene Weise integriert werden. Nachfolgend finden Sie eine Übersicht über die verschiedenen Integrationsmöglichkeiten.

Lösung Anwendungsfälle und Zielgruppen
Sendungsverfolgung-API für öffentliche Nutzung ("public"-Abfrage) Integration in Kundensysteme zur Anzeige des aktuellen Sendungsstatus (z.B.: in Bestellübersicht). Nutzung der Sendungsdaten für das After-Sales-Management (z.B.: Versendung von Bewertungsanfragen nach Zustellung der Sendung.)
Sendungsverfolgung-API für Geschäftskunden ("business"-Abfrage) Integration und Weiterverarbeitung des Sendungsstatus in betriebsinterne Systeme zur Unterstützung von Prozessen wie Kundenservice, Rechnungsstellung oder Mahnwesen.

Sendungsverfolgung-API für öffentliche Nutzung ("public"-Abfrage)

Es können bis zu 15 Sendungsnummern oder Referenznummern*) gleichzeitig abgefragt werden. Die Suche erfolgt über die letzten 3 Monate.
Für die Anzeige der Daten, z. B.  für "Ort" sowie die Lageradresse von Filiale/Packstation etc. ist die Mitgabe der Empfänger-PLZ erforderlich. Bei Onlineretouren ist die die Eingabe der Absender-PLZ erforderlich, um weitere Informationen zu erhalten.
Die Response enthält keine datenschutzrelevanten Informationen zum Absender / Empfänger.

*) Die Referenznummer muss eindeutig einer Sendungsnummer zugeordnet werden können.

Zugangsvoraussetzungen:
Um diese Schnittstelle nutzen zu können, benötigen Sie einen Zugang zur DHL-Sendungsverfolgung. Bitte wenden Sie sich an Ihren DHL-Kundenberater, um eine Benutzerkennung und ein Passwort zu erhalten.

Hinweis: Die zur Verfügung gestellte Benutzerkennung und das dazugehörige Passwort dürfen aus Datenschutzgründen nicht an Dritte weitergegeben werden. Weiterhin sind Beschränkungen des Abfragevolumens und eine performance-optimierte Gestaltung der Abrufe zu beachten.

Sendungsverfolgung-API für Geschäftskunden ("business"-Abfrage)

Bei Einzelabfragen empfehlen wir, im Request die PLZ mitzugeben, um die maximalen Sendungsinformationen abzurufen.

Es können bis zu 20 Sendungsnummern oder Referenznummern*) eines DHL-Geschäftskunden gleichzeitig abgefragt werden. Bei diesen Sammelabfragen ist die Angabe einer PLZ nicht möglich.

Der Auslieferungsnachweis kann über einen weiteren Request abgefragt werden.

*) Die Referenznummer muss eindeutig einer Sendungsnummer zugeordnet werden können.

Zugangsvoraussetzungen:
Um diese Schnittstelle nutzen zu können, benötigen Sie einen Geschäftskunden-Zugang. Um als DHL-Vertragskunde aufgeschaltet zu werden und eine Benutzerkennung und ein Passwort zur DHL-Sendungsverfolgung für Geschäftskunden zu erhalten, wenden Sie sich bitte an Ihren DHL Kundenberater.

Hinweis: Da der Aufruf sensible Kundendaten liefert, dürfen diese Informationen ausschließlich in Ihren internen Systemen angezeigt werden. Die zur Verfügung gestellte Benutzerkennung und das dazugehörige Passwort dürfen aus Datenschutzgründen nicht an Dritte weitergegeben werden. Weiterhin sind die Beschränkung des Abfragevolumens und eine performance-optimierte Gestaltung der Abrufe zu beachten.

Integrationsmöglichkeiten durch HTTP-Direktaufruflink

Der HTTP-Direktaufruflink ist ein parametrisierter URL Aufruf, der das Suchergebnis zu einer bestimmten Sendung direkt auf www.dhl.de anzeigt.

Dieser Direktaufruflink kann beispielsweise in einer Versandbestätigungs-E-Mail, die der Empfänger der Sendung erhält, eingesetzt werden, um den direkten Aufruf des Sendungsstatus in der Funktion "Verfolgen" (DHL Sendungsverfolgung) zu ermöglichen. Eine weitere Einsatzmöglichkeit ist die Verlinkung des Sendungsstatus aus einer Bestellübersicht des Versandhändlers.

Es können bis zu 15 Sendungsnummern oder Referenznummern gleichzeitig abgefragt werden. Die Suche erfolgt über einen fest definierten Zeitraum der vergangenen 3 Monate.

Vorteile einer Weiterleitung auf die DHL Paket Sendungsverfolgung:

  • Anzeige des aktuellen Sendungsstatus
  • Anzeige Live-Tracking (wenn verfügbar)
  • Auswahl von Empfängerservices wie z.B. Hinterlegung eines bestimmten Ablageorts, Lieferung an einen Nachbarn, eine Filiale oder Packstation statt an die Hausanschrift des Empfängers sowie Änderung des Liefertags.
  • Kontextbezogene Verlinkung auf weiterführende Hilfeseiten und Kontaktmöglichkeit zum DHL-Kundenservice

 

Da es sich bei der DHL-Sendungsverfolgung um eine öffentliche Beauskunftung handelt, liefert die Anzeige keine datenschutzrelevanten Informationen zum Absender / Empfänger.
Für detaillierte Sendungsinformationen zum Versender / Empfänger muss die Postleitzahl eingegeben werden.

 

Beispiel - Integration eines Direktaufruflinks in einer E-Mail:

Example - integration of a direct access link in an e-mail

 

Technische Beschreibung des HTTP-Direktaufruflinks

URL: https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html

 

Attribute

Beschreibung

Beispiel

piececode

Suche nach Sendungsnummer oder Referenznummer

https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=XXXXXXXXXX

lang

Gewünschte Sprache für die Ergebnismeldung in Deutsch oder Englisch (2-stelliger ISO-Ländercode "de" für Anzeige in Deutsch oder "en" für Anzeige in Englisch)

https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=XXXXXXXXXX&lang=de

https://www.dhl.de/en/privatkunden/pakete-empfangen/verfolgen.html?piececode=XXXXXXXXXX&lang=en

 

Für die Sprachen Deutsch und Englisch sollte immer dieser Direktaufruflink genutzt werden, da die Funktion "Verfolgen" auf www.dhl.de folgende weitere Optionen anbietet.

Beispiel für die Auswahl von Empfängerservice-Optionen wie z.B. die Wahl des Zustellorts und Liefertags:

Beispiel Herunterladen

 

Erweitere Sprachauswahl:

Möchten Sie in Ihren Versandbestätigungs-E-Mails erweiterte Sprachen (außer Deutsch "de" und Englisch "en") auswählen, dann nutzen sie bitte diese URL:
https://nolp.dhl.de/nextt-online-public/

Attribute

Beschreibung

Beispiel

piececode

Suche nach Sendungsnummer oder Referenznummer

https://nolp.dhl.de/nextt-online-public/?piececode=XXXXXXXXXX

Übernahme Browsersprache:

beim Aufruf dieses Links wird die Browsersprache des Benutzers erkannt und die DHL Sendungsverfolgung in folgenden Sprachen ausgespielt:
-    Französisch
-    Spanisch
-    Italienisch
-    Niederländisch
D.h. Wenn der Benutzer als bevorzugte Browsersprache z.B. "Französisch" ausgewählt hat, so wird ihm auch die DHL Sendungsverfolgung auf Französisch angezeigt. Für alle Browser-Spracheinstellungen, die nicht Französisch, Spanisch, Italienisch oder Niederländisch beinhalten, erfolgt die Anzeige automatisch auf Englisch.

Zugang erhalten

Wie erfolgt die Registrierung ihrer DHL Paket DE Sendungsverfolgung API und wie bekommen Sie die Zugangsdaten:

  1. Klicken Sie auf die Schaltfläche "Zugang erhalten" oben auf dieser Seite und das Formular "App erstellen" wird geöffnet, wobei die Sandbox-Umgebung der API vorausgewählt ist.
    • Falls erforderlich, ändern Sie die Auswahl in "DHL Paket DE Sendungsverfolgung API".
    • Wenn Sie das Formular ausgefüllt haben, klicken Sie auf die Schaltfläche "App erstellen".
    • Unter Meine Apps finden Sie nun ihre App.
    • Klicken Sie auf dem Bildschirm Meine Apps auf den Namen Ihrer App. Der Bildschirm mit Details erscheint.
    • Wenn Sie Zugang zu mehr als einer API haben, klicken Sie auf den Namen der relevanten API.
      Hinweis: Die APIs sind im Bereich "Zugangsdaten" aufgelistet.
    • Klicken Sie auf den Link Anzeige unter den Sternchen, die die Zugangsdaten verdecken. Der Benutzer-Schlüssel wird angezeigt. 

    Jeder Aufruf der API erfordert einen Benutzerschlüssel. Dieser Schlüssel muss im Request-Header angegeben werden (DHL API-Key).

    Bitte beachten Sie, dass für die Sandbox- bzw. Produktionsumgebung unterschiedliche Schlüssel erforderlich sind. Beide können über das oben beschriebene Verfahren angefordert und aus dem Abschnitt API-Anmeldeinformationen kopiert werden.

    Alternativ zu "Zugang erhalten" können Sie auf der Portal-Website zu Meine Apps gehen und auf die Schaltfläche + App erstellen:

    • Das Formular "App erstellen" erscheint.
    • Füllen Sie das Formular "App erstellen" aus und wählen Sie "Parcel DE Tracking (Post & Parcel Germany)".
      • In der Liste finden Sie zwei Einträge der API: einen für die Sandbox, einen für die Produktion.

    Authentifizierung

    Um die Sendungsverfolgung API nutzen zu können, benötigen Sie:

    • Rest-Gateway (Apigee) Authentifizierung
      - kann über den Get Access Button oben auf dieser Seite angefordert werden
      - besteht aus API key und API secret als Basic authorization

    • Sendungsverfolgung Benutzerkonto (Benutzername / ZT-Kennung und Passwort)
      - wird explizit für jeden Kunden vergeben
      - wird beim Anlegen Ihres Kundenkontos generiert

    Dies gilt sowohl für die Sandbox als auch für die Produktionsumgebung. 

    Diese Schlüssel müssen bei jeder Anfrage als Autorisierungsinformation im Header übermittelt werden. Weitere Details finden Sie unter Wie testet man die API .

    Sandbox

    Für die Nutzung der Sendungsverfolgungs-API haben Sie die Möglichkeit, ihren Aufruf mit den folgenden Benutzerdaten zu verwenden: 

    • User:           ZT-Kennung mit DASS Freigabe --> zt12345
    • Passwort:  Password ZT-Kennung --> geheim

    Der oben angegebene Benutzername und das Passwort müssen im XML-Teil der Anfrage eingetragen werden:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?> <data appname="ZTKennung" language-code="de" password="Passwort ZT-Kennung" piece-code="Sendungsnummer" request="d-get-piece-detail"/>

    Hinweis: Wenn Sonderzeichen im Passwort in HTML eine bestimmte Bedeutung haben, müssen Sie diese Zeichen maskieren.
    https://wiki.selfhtml.org/wiki/Referenz:HTML/Zeichenreferenz


    Produktion

    Für die Nutzung der Sendungsverfolgung Produktions-API haben Sie die Möglichkeit, ihren Aufruf mit den folgenden Benutzerdaten zu verwenden: 

    • User:           ZT-Kennung mit DASS Freigabe
    • Passwort:  Password ZT-Kennung

    Der oben angegebene Benutzername und das Passwort müssen im XML-Teil der Anfrage eingetragen werden:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?> <data appname="ZTKennung" language-code="de" password="Passwort ZT-Kennung" piece-code="Sendungsnummer" request="d-get-piece-detail"/>

    Falls Sie noch keinen Zugang für die Produktion haben, kontaktieren Sie bitten den DHL PAKET Vertrieb.

    Hinweis: Wenn Sonderzeichen im Passwort in HTML eine bestimmte Bedeutung haben, müssen Sie diese Zeichen maskieren.
    https://wiki.selfhtml.org/wiki/Referenz:HTML/Zeichenreferenz

    Test- und Produktions-Umgebung 

    Die API ist über folgende Endpunkte erreichbar: 

    Umgebung Beschreibung Kommentar
    https://api-sandbox.dhl.com/parcel/de/tracking/v0/shipments Sandbox- Umgebung Die Nutzung der Sandbox ist auch für nicht Geschäftskunden direkt nach Anforderung der API möglich.
    https://api-eu.dhl.com/parcel/de/tracking/v0/shipments Produktions-Umgebung Die produktive Verwendung wird durch DHL freigeschaltet.

    Allgemeine Fehlerhandhabung

    Statuscodes

    Nachfolgende Listen (deutsch und englisch) bietet einen Überblick über die verfügbaren Statuscodes der DASS Schnittstelle zum Zeitpunkt der Dokument-Erstellung. Der Statuscode und Statustext wird über die Attribute code und error oder piece-status und piece-status-desc für NOLP Aufrufe, bereitgestellt.

    Code Sprache Fehler
    -1000 de Ein technischer Fehler ist aufgetreten! Bitte kontaktieren Sie den Support!
    -3 de Abfrage unbekannt.
    -2 de Interner SQL-Datenbank-Abfrage-Fehler.
    -1 de Keine Verbindung zur Datenbank.
    5 de Anmeldung fehlgeschlagen.
    6 de Zu viele ungültige Logins. Versuchen Sie es bitte später erneut.
    41 de IDC-Prüfsumme ungültig.
    45 de Kein Piece-Code eingegeben.
    57 de Zur vorgegebenen PLZ sind keine Informationen verfügbar.
    58 de Parameter ekp-no fehlt.
    59 de Weder Parameter piece-code noch Parameter tas-order-no spezifiziert.
    60 de Nur ein Parameter piece-code oder tas-order-no erlaubt.
    61 de Keine Sendungsdaten zur TAS-Auftragsnummer gefunden.
    62 de Bearbeitung wegen fehlender Berechtigung abgebrochen (Servlet-Request).
    63 de Unterschriften sind wegen fehlender Verbindung zum Archiv-Server nicht verfügbar.
    64 de Keine Bearbeitung möglich: Recht zur Anfrage ohne Prüfziffer fehlt.
    100 de Keine Daten gefunden.
    200 de Es liegen keine elektronischen Sendungsdaten vor.

     

    Code Language Error
    -1000 en A technical error has occurred! Please contact support!
    -3 en Unknown request.
    -2 en Internal error executing SQL query.
    -1 en No connection to the database.
    5 en Login failed. Not authorized.
    6 en Too many invalid logins. Please try again later.
    41 en IDC-Checksum invalid
    45 en No Piece-Code supplied.
    57 en No information available using the specified ZIP-code
    58 en Parameter ekp-no is missing.
    59 de Neither parameter piece-code nor tas-order-no specified.
    60 en Only one parameter piece-code or tas-order-no allowed.
    61 en No shipment data found for TAS order number.
    62 en Processing canceled due to missing authorization (servlet request).
    63 en Signatures are not available due to lack of connection to the archive server.
    64 en No processing possible: right to request without check digit missing.
    100 en No data found.
    200 en There are no electronic shipment data available.
    Postman Collection

    Wir empfehlen die Verwendung der Software Postman zum testen der API. Postman ist eine Kollaborations Platform für API Entwicklung und Testing. Post & DHL Deutschland stellt Ihnen eine umfangreiche Postman Test Collection für jede API zur Verfügung. Folgen sie der Anleitung in diesem Kapitel, um die Test Collection in Ihren Postman Workspace zu importieren und schnell mit der Integration unserer API zu beginnen.

    Die folgenden Schritte müssen zuvor durchgeführt werden, um die API zu testen:

    Sie müssen den Zugang zur Sandbox-Umgebung beantragen um einen API-Schlüssel (dhl-api-key) zu erhalten.
    Eine ausführliche Anleitung dazu finden Sie unter Zugang erhalten.

    Einrichten der Postman Test Collection

    • Laden sie die Postman Test Collection im Download Bereich herunter.
    • Importieren Sie die Postman Test Kollektion (siehe offizielle Dokumentation der Postman-Lernplattform) 
    • Ersetzen Sie den Wert der Variable "dhl-api-key" durch Ihren persönlichen API-Schlüssel

    Bitte beachten Sie auch unsere Schritt-für-Schritt Anleitung zur Benutzung der Postman Test Collection.

    Anwendungsfälle

    Übersicht

    In diesem Kapitel werden die ersten Schritte der Systemfunktionalität anhand von praktischen Beispielen erläutert:

    • get-status-for-public-user
    • d-get-piece-detail
    • d-get-signature

    Weitere technische Informationen finden Sie im Kapitel "Wie testet man die API".

    Operationen

    Sendungsverfolgung-API für öffentliche Nutzung ("public"-Abfrage)

    • Die öffentliche Sendungsverfolgung-API liefert bereits prinzipbedingt einen geringeren Datenumfang, welcher der Sendungsverfolgung für Privatkunden entspricht
    • Zukünftig erfordert jedoch die Anzeige der Daten für "Ort" sowie die Lageradresse von Filiale/Packstation die Mitgabe der Empfänger-PLZ
    • Bei Online Retouren muss die Absender-PLZ verwendet werden
    • Wichtige Hinweise:
      • Die PLZ-Mitgabe funktioniert nur bei Abfrage per Sendungsnummer (keine Referenzen)
      • Die PLZ-Mitgabe funktioniert nur mit jeweils einem Request für eine Sendung (es sind keine Sammelabfragen mit PLZ-Mitgabe möglich)
    • Sollten diese Daten benötigt werden, ist die Übergabe der PLZ als Parameter beim API-Aufruf erforderlich
    • Wir empfehlen eine Umsetzung hiervon bis zur KW 25

    Sendungsverfolgung-API für Geschäftskunden ("business"-Abfrage)

    • Im Falle einer Einschränkung der Sendungsdaten bleiben in der API-Response Felder, die personenbezogene Daten enthalten, leer.
    • Sollen die Daten voll angezeigt werden, ist die Übergabe der Empfänger-PLZ als Parameter beim API-Aufruf erforderlich
    • Bei Online Retouren muss die Absender-PLZ verwendet werden
    • Wichtige Hinweise:
      • Die PLZ-Mitgabe funktioniert nur bei Abfrage per Sendungsnummer (keine Referenzen)
      • Die PLZ-Mitgabe funktioniert nur mit jeweils einem Request für eine Sendung (es sind keine Sammelabfragen mit PLZ-Mitgabe möglich)
    • Die PLZ kann somit präventiv direkt mit dem ersten Request übergeben werden, um sicher zu gehen, dass in der ersten Response alle Daten enthalten sind

    Privatkunden

    • get-status-for-public-user:
      Abfrage des aktuellen Sendungsstatus für öffentliche Nutzung

    Geschäftskunden

    • d-get-piece-detail:
    • Kombinierter Aufruf von Sendungsstatus und Laufweg
    • d-get-signature:
      Abfrage der Unterschrift des Empfängers bzw. Ersatzempfängers (Zustellnachweis / POD)

    Allgemeines

    Über die Sendungsverfolgung API werden keine statistischen Daten über den Versand von Paketen bereitgestellt.

    Bei Abfragen mehrerer Sendungsnummern / Referenznummer wird das Ergebnis in Form einer Liste zurückgeliefert.
    Sofern eine Sendung nicht eindeutig identifiziert werden kann (z.B. bei unzulässiger Doppelvergabe einer Sendungsnummer innerhalb eines Jahres), werden die Sendungsergebnisse ebenfalls in Form einer Liste zurückgeliefert.

    Um die Ergebnismenge von vornherein einzuschränken, sollten beim Aufruf die Attribute zip-code und from-date/ to-date für eine detaillierte Suchanfrage mitgegeben werden.

    Wichtige Hinweise zu den Parametern

    Alle Funktionen haben folgende gemeinsame Abfrageparameter:

    • Benutzerkennung appname
      Kennung mit der sich der Kunde für die Benutzung der Schnittstelle authentifiziert
    • Passwort password
      Das zur Benutzerkennung gehörende Passwort
    • Sprachcode (ISO Language Code) language-code
      Der Sprachcode definiert die Sprache, die für die Ergebnisdarstellung ausgewählt wird. Derzeit sind folgende Codes möglich:
      en für englisch
      de für deutsch

     

    Alle Funktionen besitzen ein identisches Antwortverhalten:

    Wie wurde die Funktion aufgerufen? Antwortverhalten
    Die Parameter waren unvollständig oder fehlerhaft Die Anfrage wird mit einer entsprechenden Fehlermeldung abgebrochen.
    Die Parameter waren vollständig und korrekt Es werden die gesuchten Sendungsinformationen zurückgemeldet, sofern zur Sendung Daten vorliegen..
    Die DHL Sendungsverfolgung war zum Zeitpunkt des Aufrufes nicht verfügbar Falls es sich um eine Störung des Backendsystems handelt, meldet das System einen Fehler zurück. Handelt es sich um eine Störung des Webservers, wird die Anfrage nach einem Timeout mit einem Fehler beendet.

    Wichtig: Die Attribute mit dem Hinweis steht nicht mehr zur Verfügung! sollten für eine clientseitige Auswertung nicht mehr herangezogen werden, da sie in Zukunft nicht mehr in der Antwort enthalten sein werden!

    Rechte und Authentifizierung

    Als Geschäftskunde von DHL können Sie alle Funktionen verwenden. Die einzelnen Funktionen sind allerdings an Rechte gekoppelt, die gesondert vergeben werden. Ist für Sie eine Funktion nicht freigeschaltet, so wird über den Aufruf eine entsprechende Fehlermeldung geliefert. Bitte wenden Sie sich in diesem Fall an Ihren DHL-Kundenberater, der die Berechtigung für Ihren Geschäftskunden-Account überprüft und entsprechend erweitern lässt.

    Mit jedem Aufruf der Sendungsverfolgung API müssen Sie sich als Nutzer bzw. das nutzende Programm mit einer Benutzerkennung und einem Passwort authentifizieren (siehe Abfrageparameter). Bitte beachten Sie, dass die Berechtigungen zur Sendungsabfrage im Bereich der DHL-Sendungsverfolgung für Geschäftskunden an Ihre DHL-Kundennummer (EKP) bzw. an die Ihrem Geschäftskunden-Account zugewiesene Sendungsnummernbereiche geknüpft sind. Auf diese Weise ist sichergestellt, dass ein Zugriff auf den Sendungsstatus fremder Sendungen ausgeschlossen ist.

    Für Aufrufe ohne DHL-Geschäftskundenvertrag steht Ihnen ausschließlich der Zugriff auf den Bereich der Sendungsverfolgung-API für öffentliche Nutzung ("public"-Abfrage) zur Verfügung.

    get-status-for-public-user

    Die Funktion "get-status-for-public-user" liefert Informationen, wie sie heute im Bereich der DHL öffentlichen Sendungsverfolgung (www.dhl.de) dargestellt werden.

    Folgende Besonderheiten gelten für die Operation "get-status-for-public-user":

    • Die Sendungsabfrage ist über eine Sendungsnummer möglich. Dabei können bis zu 15 Sendungsnummern pro Aufruf übergeben werden.
      Die einzelnen Nummern müssen hierbei durch ein Semikolon voneinander getrennt werden. Sind mehrere Sendungsnummern in der Abfrage enthalten, sind entsprechend auch mehrere Elemente in der Antwort.
       
    • Sofern eine Sendung nicht eindeutig identifiziert werden kann (z.B. bei unzulässiger Doppelvergabe einer Sendungsnummer innerhalb eines Jahres), werden die Sendungsergebnisse in Form einer Liste zurückgeliefert. Um die Ergebnismenge von vornherein einzuschränken, sollte beim Aufruf das Attribute "zip-code" mitgegeben werden.
       
    • Für die Anzeige der Daten für "Ort" sowie die Lageradresse von Filiale/Packstation die ist die Mitgabe der Empfänger-PLZ erforderlich. Bei Online-Retouren muss die Absender-PLZ übergeben werden stellt.  Personenbezogenen Daten werden nicht bereitgestellt.
       
    • Wichtige Hinweise:
      • Die PLZ-Mitgabe funktioniert nur bei Abfrage per Sendungsnummer (keine Referenzen)
      • Die PLZ-Mitgabe funktioniert nur mit jeweils einem Request für eine Sendung (es sind keine Sammelabfragen mit PLZ-Mitgabe möglich)
         
    • Auf der DHL Seite wird eine Prüfung des Nummernformats durchgeführt. Entspricht der Aufbau nicht einem gültigen Sendungsnummernformat, wird die Sendungssuche für diese Sendung abgebrochen.

     

    Beispieldaten

    Request

    https://api-eu.dhl.com/parcel/de/tracking/v0/shipments?xml=

    <data
                    request="get-status-for-public-user"
                    appname="Benutzerkennung"
                    password="Passwort"
                    language-code="de">
                    <data
                                   piece-code="961001046136"
                                   piece-customer-reference=""
                                   date-from="YYYY-MM-DD"
                                   date-to="YYYY-MM-DD"
                                   zip-code="12345"
                    />
    </data>

    Response

    <?xml version="1.0" encoding="UTF-8" ?>
    <data request-id="379d9788-5a8e-49dd-9f7e-d30e17746c2a">
    <data name="piece-status-public-list"
        code="0"
        _piece-code="0231234
        _zip-code="32584">
        <data name="piece-status-public"
            piece-identifier="231234"
            _build-time="2012-06-06 18:18:10.000607"
            piece-id="3b048653-aaa9-485b-b0dd-d16e068230e9"
            leitcode=""
            searched-piece-code="0231234"
            piece-status="0"
            identifier-type="2"
            recipient-name="Hr. Hannes Testler"
            recipient-id="1"
            recipient-id-text="Empfänger (orig.)"
            pan-recipient-name=" "
            street-name=""
            house-number=""
            city-name=""
            last-event-timestamp="11.03.2012 11:59"
            shipment-type=""
            status-next=""
            status="Die Sendung wurde ausgeliefert."
            error-status="0"
            delivery-event-flag="1"
            upu=""
            international-flag="0"
            piece-code="0231234"
            ice="DLVRD"
            ric="ACCPT"
            division="DPEED"
            dest-country="de"
            origin-country="de"
            product-code="00"
            product-name="DHL PAKET"
            searched-ref-no="034234"
            standard-event-code="ZU"
            pan-recipient-street=""
            pan-recipient-city=""
            event-country="de"
            event-location=""
            shipment-length="0.0"
            shipment-width="0.0"
            shipment-height="0.0"
            shipment-weight="0.2" />
        </data>
    </data>

    I/O Reference "get-status-for-public-users"

    Request Parameter

    Folgende Attribute können über das <data> Element übergeben werden:

    Attribut

    Beschreibung

    appname Benutzerkennung, die der Geschäftskunde für die Nutzung API Sendungsverfolgung erhalten hat
    password Das dazugehörige Passwort
    request Ist bei diesem Aufruf standardmäßig "get-status-for-public-user"
    zip-code Die PLZ wird zur eindeutigen Identifizierung einer Sendung genutzt. Darüber hinaus ermöglichlich die Mitgabe der  PLZ die Bereitstellung  als "private" eingestufer Sendungsdaten
    language-code Gewünschte Sprache für die Ergebnismeldung (de oder en)
    piece-code Sendungsnummer für die der Status abgefragt werden soll. Es können bis zu 15 Sendungsnummern übergeben werden. Die einzelnen Sendungsnummern sind mit Semikolon zu trennen.

    Bei einer optionalen Zeitraumabfrage sind folgende Parameter zu definieren:

    Attribut

    Beschreibung

    from-date Beginn des Zeitraumes (Format: jjjj-mm-tt)
    to-date Ende des Zeitraumes (Format: jjjj-mm-tt)


    Response Parameter

    Die Attribute einer Antwort haben folgende Bedeutung:

    Attribut

    Beschreibung

    name Bezeichnung für das <data> Element. Das erste Element besitzt den Namen "piece-status-public-list". Das Nachfolgende den Namen "piece-status-public".
    code Statuscode für den Request
    error-status Fehlerstatus für die aktuelle Sendung
    piece-code piece-code
    piece-identifier Sendungsnummer ohne Prefix
    identifier-type Beschreibt den Barcodetyp der Sendungsnummer (1 = IDC, 2 = LP EAN, 3 = LP Ansi/Fact, etc.)
    searched-piece-code Sendungsnummer, nach der gesucht wurde
    leitcode Barcode der Sendung mit Routinginformationen
    routing-code-ean Barcode der Sendung mit Routinginformationen
    pslz-nr Internes Feld
    recipient-name Nicht befüllt
    recipient-id Empfängerkennzeichen aktuell nicht befüllt!
    recipient-id-text Auflösung Empfängerkennzeichen (Original Empfänger, Nachbar, Ehegatte, andere anwesende Person) - aktuell nicht befüllt!
    street-name Nicht befüllt
    house-number Nicht befüllt
    city-name Nicht befüllt
    pan-recipient-name Nicht befüllt
    pan-recipient-street Nicht befüllt
    pan-recipient-city Nicht befüllt
    dest-country ISO-Code für das Zielland der Sendung (z.B. FR für Frankreich)
    origin-country ISO-Code für das Absenderland der Sendung (z.B. DE für Deutschland)
    delivery-event-flag Zustell-Flag (1=zugestellt 0=nicht zugestellt)
    international-flag International-Fag (1=internationale Sendung, 0=nationale Sendung)
    ruecksendung Rücksendungs-Flag (true=Rücksendung, false=keine Rücksendung)
    matchcode Ausländische Sendungsnummer
    domestic-id Sendungsnummer Empfangsland
    upu Internes Feld
    airway-bill-number Express Sendungsnummer bei Transport durch DHL Express im Zielland
    product-code Produktcode
    product-name Produktnamen (z.B. DHL-Paket)
    shipment-length Paket: Länge (EDI Daten)
    shipment-width Paket: Breite (EDI Daten)
    shipment-height Paket: Höhe (EDI Daten)
    shipment-weight Paket: Gewicht (EDI Daten)
    delivery-date voraussichtlicher Zustelltag
    delivery-timeframe-from voraussichtliches Zustellzeitfenster von
    delivery-timeframe-to voraussichtliches Zustellzeitfenster bis
    order-preferred-delivery-day Beauftragung-Zustelltag-Flag (true=es wurde ein Zustelltag beauftragt, false=es liegt keine Beauftragung eines Zustelltags vor
    preferred-delivery-day Gebuchter Zustelltag
    preferred-delivery-timeframe-from Nicht mehr genutzt
    preferred-delivery-timeframe-to Nicht mehr genutzt
    preferred-timeframe-refused-text Nicht mehr genutzt
    shipment-type routing-code-ean
    last-event-timestamp Zeitstempel des aktuellen Events
    status Status-Text des aktuellen Events
       
    Events  
    event-timestamp Zeitstempel Event
    event-status Status-Text Event
    event-text Status-Text Event
    event-short-status Kurz-Status-Text Event
    division Kennzeichnet die interne Produktionslinie
    ice "International Coded Event" (siehe Anhang ICE/RIC)
    ric "Reason Instruction Code" (siehe Anhang ICE/RIC)
    standard-event-code Standardcode für das Sendungsereignis (siehe Anhang standard-event-code)
    event-location Ort der Erstellung des Sendungsereignisses
    event-country Land der Erstellung des Sendungsereignisses


    Wichtig: Die Attribute mit dem Hinweis Steht nicht mehr zur Verfügung! sollten für eine clientseitige Auswertung nicht mehr herangezogen werden, da sie in Zukunft nicht mehr in der Antwort enthalten sein werden!

    Anhang: ICE Event RIC Kombinationen_11_2023.csv
     

    d-get-piece-detail

    Die Funktion "d-get-piece-detail" ruft alle Informationen zu einer Sendung über eine Anfrage ab. Dies erfolgt durch eine Kombination aus der Abfrage des Sendungsstatus und der Abfrage für den Sendungsverlauf (Ereignisliste).

    Folgende Besonderheiten gelten für die Operation "d-get-piece-detail":

    • Die Funktion kann mit einer Sendungsnummer und einer Sendungsreferenz aufgerufen werden.
       
    • Je Anfrage können bis zu 20 Sendungsnummern oder -referenzen übergeben werden. Die einzelnen Nummern müssen hierbei durch ein Semikolon voneinander getrennt werden.Sind mehrere Sendungsnummern oder -referenzen in der Abfrage, sind entsprechend auch mehrere Elemente in der Antwort enthalten.
       
    • Auf der DHL Seite wird eine Prüfung des Nummernformates durchgeführt. Entspricht der Aufbau nicht einem gültigen Sendungsnummernformat, wird die Sendungssuche für diese Sendung abgebrochen.
       
    • Sofern eine Sendung nicht eindeutig identifiziert werden kann (z.B. bei unzulässiger Doppelvergabe einer Sendungsnummer innerhalb eines Jahres), werden die Sendungsergebnisse in Form einer Liste zurückgeliefert. Um die Ergebnismenge von vornherein einzuschränken, sollte beim Aufruf das Attribute "zip-code" mitgegeben werden.
       
    • Wichtige Hinweise:
      • Die PLZ-Mitgabe funktioniert nur bei Abfrage per Sendungsnummer (keine Referenzen).
      • Die PLZ-Mitgabe funktioniert nur bei Einzelabfragen, also bei jeweils einem Request je Sendung (es sind keine Sammelabfragen mit PLZ-Mitgabe möglich.
         
    • Um eine Abfrage für einen bestimmten Zeitraum zu definieren, können der Beginn (from-date) und das Ende (to-date) des Zeitraumes der Suche angegeben werden.
       

    Beispieldaten

    Request
    https://api-eu.dhl.com/parcel/de/tracking/v0/shipments?xml=
    
    <?xml version="1.0" encoding="UTF-8" ?>
    <data appname="Benutzerkennung"
             password="Passwort"
             request="d-get-piece-detail"
             language-code="iso-sprachcode" - de oder en
            zip-code= PLZ
             piece-code="Sendungsnummer"
              oder
            piece-customer-reference="Sendungsreferenz"
              oder
             from-date="2023-01-01"
             to-date="2023-03-31">
    </data>
    Response
    <?xml version="1.0" encoding="UTF-8" ?>
    <data name="pieceshipmentlist"
    	request-id="379d9788-5a8e-49dd-9f7e-d30e17746c2a"
    	code="0">
    	<data name="pieceshipment"
    		error-status="0"
    		piece-id="3b048653-aaa9-485b-b0dd-d16e068230e9"
    		shipment-code=""
    		piece-identifier="26633445"
    		identifier-type="1"
    		piece-code="266334453"
    		event-location=""
    		event-country="DE"
    		status-liste=""
    		status-timestamp="16.03.2012 15:29"
    		status="Die Sendung wurde erfolgreich zugestellt."
    		short-status="Zustellung erfolgreich"
    		recipient-name="TestMustermann"
    		recipient-street="Am Musterhaus 5"
    		recipient-city="23221 Testmannsdorf"
    		pan-recipient-name="TestMustermann"
    		pan-recipient-street="Am Musterhaus 5"
    		pan-recipient-city="23221 Testmannsdorf"
    		pan-recipient-address="Am Musterhaus 5 23221 Testmannsdorf"
    		shipper-name="VersandhausHeileWelt"
    		shipper-street="Testerstraße 111"
    		shipper-city="53113 Meindorf"
    		shipper-address="Testerstraße 111 53113 Meindorf"
    		product-code="00"
    		product-key=""
    		product-name="DHLPAKET"
    		delivery-event-flag="1"
    		recipient-id="2"
    		recipient-id-text="Ehegatte"
    		upu=""
    		shipment-length="0.0"
    		shipment-width="0.0"
    		shipment-height="0.0"
    		shipment-weight="0.2"
    		international-flag="0"
    		division="DPEED"
    		ice="DLVRD"
    		ric="ACCPT"
    		standard-event-code="ZU"
    		dest-country="DE"
    		origin-country="DE"
    		searched-piece-code="26633445"
    		searched-ref-nr=""
    		piece-customer-reference="034234"
    		shipment-customer-reference="111234"
    		leitcode="" />
    	<data name="pieceeventlist"
    		piece-identifier="2343265"
    		_build-time="2012-10-06 18:18:10.000607"
    		piece-id="3b048653-aaa9-485b-b0dd-d16e068230e9"
    		leitcode="34634543453">
    		<data name="pieceevent"
    			event-timestamp="14.03.2012 00:00"
    			event-status=
                            "Die Sendung wurde im Start-Paketzentrum bearbeitet."
    			event-text=
                            "Die Sendung wurde im Start-Paketzentrum bearbeitet."
    			ice="LDTMV"
    			ric="MVMTV"
    			event-location="Saulheim"
    			event-country="Deutschland"
    			standard-event-code="AA"/>
    			  .
    			  .
    			  .
    		<data name="pieceevent"
    			event-timestamp="16.03.2012 15:29"
    			event-status="Die Sendung wurde erfolgreich zugestellt."
    			event-text=" Die Sendung wurde erfolgreich zugestellt."
    			ice="DLVRD"
    			ric="ACCPT"
    			event-location="Bonn"
    			event-country="Deutschland"
    			standard-event-code="ZU"/>
    	</data>
    </data>
    
    

    I/O Reference "d-get-piece-detail"

    Request Parameter

    Folgende Attribute können über das <data> Element übergeben werden:

    Attribut

    Beschreibung

    appname Benutzerkennung, die der Geschäftskunde für die Nutzung API Sendungsverfolgung erhalten hat
    password Das dazugehörige Passwort
    request Ist bei diesem Aufruf standardmäßig "d-get-piece-detail"
    zip-code Die PLZ wird zur eindeutigen Identifizierung einer Sendung genutzt. Darüber hinaus ermöglichlich die Mitgabe der  PLZ die Bereitstellung  als "private" eingestufer Sendungsdaten
    language-code Gewünschte Sprache für die Ergebnismeldung (de oder en)
    piece-code Sendungsnummer für die der Status abgefragt werden soll. Es können bis zu 15 Sendungsnummern übergeben werden. Die einzelnen Sendungsnummern sind mit Semikolon zu trennen.
    piece-customer-reference Kundenreferenz für die der Status abgefragt werden soll. Es können bis zu 15 Kundenreferenzen übergeben werden. Die einzelnen Referenzen sind mit Semikolon zu trennen. Um die Referenznummer für die Sendungsverfolgung zu verwenden, sollte sie mindestens 8 Zeichen lang und eindeutig sein.

    Bei einer optionalen Zeitraumabfrage sind folgende Parameter zu definieren:

    Attribut

    Beschreibung

    from-date Beginn des Zeitraumes (Format: jjjj-mm-tt)
    to-date Ende des Zeitraumes (Format: jjjj-mm-tt)


    Response Parameter

    Die Attribute einer Antwort haben folgende Bedeutung:

    Attribut

    Beschreibung

    name Bezeichnung für das <data> Element.
    Das erste Element besitzt den Namen "piece-shipment-list". Das Nachfolgende den Namen "piece-shipment".
    code Statuscode für den Request
    error-status Fehlerstatus für die aktuelle Sendung
    shipment-code Nicht genutzt
    piece-identifier Sendungsnummer ohne Prefix
    identifier-type Beschreibt den Barcodetyp der Sendungsnummer (1 = IDC, 2 = LP EAN, 3 = LP Ansi/Fact, etc.)
    piece-code Sendungsnummer
    searched-piece-code Sendungsnummer, nach der gesucht wurde
    piece-customer-reference Sendungsreferenz, nach der gesucht werden kann
    searched-ref-nr Sendungsreferenz, nach der gesucht wurde
    shipment-customer-reference  
    status-liste Internes Feld
    status-timestamp Zeitstempel des aktuellen Events
    status Status-Text des aktuellen Events
    short-status Kurz-Status-Text des aktuellen Events
    recipient-name Empfänger: Name
    recipient-id Empfängerkennzeichen
    recipient-id-text Auflösung Empfängerkennzeichen (Original Empfänger, Nachbar, Ehegatte, andere anwesende Person)
    recipient-street Empfänger: Straße und Hausnummer
    recipient-city Empfänger: PLZ und Stadt
    pan-recipient-name Empfängername aus EDI Daten
    pan-recipient-street Empfängerstraße und Hausnummer aus EDI Daten
    pan-recipient-city PLZ Stadt aus EDI Daten
    pan-recipient-address Empfängerstraße,Hausnummer, PLZ, Stadt aus EDI Daten
    pan-recipient-postalnumber Empfänger: Postnummer
    pan-recipient-email Empfänger: eMail
    shipper-name Absender: Name
    shipper-street Absender: Straße und Hausnummer
    shipper-city Absender: PLZ und Stadt
    shipper-address Absender: Straße, Hausnummer, PLZ und Stadt
    product-code Produktcode
    product-key Produktschlüssel
    product-name Produktnamen (z.B. DHL-Paket)
    delivery-event-flag Zustell-Flag (1=zugestellt 0=nicht zugestellt)
    international-flag International-Fag (1=internationale Sendung, 0=nationale Sendung)
    ruecksendung Rücksendungs-Flag (true=Rücksendung, false=keine Rüxcksendung)
    notification-cases Benachrichtigungs-Flags (true=Empfänger hat Benachrichtigungen zum Sendungsstatus erhalten, false= Empfänger konnte auf Grund fehlender Kontaktdaten nicht benachrichtigt werden)
    upu Internes Feld
    matchcode Ausländische Sendungsnummer
    domestic-id Sendungsnummer Empfangsland
    airway-bill-number Express Sendungsnummer bei Transport durch DHL Express im Zielland
    leitcode Barcode der Sendung mit Routinginformationen
    routing-code-ean Barcode der Sendung mit Routinginformationen
    shipment-length Paket: Länge (EDI Daten)
    shipment-width Paket: Breite (EDI Daten)
    shipment-height Paket: Höhe (EDI Daten)
    dest-country ISO-Code für das Zielland der Sendung (z.B. FR für Frankreich)
    origin-country ISO-Code für das Absenderland der Sendung (z.B. DE für Deutschland)
    delivery-date voraussichtlicher Zustelltag
    delivery-timeframe-from voraussichtliches Zustellzeitfenster von
    delivery-timeframe-to voraussichtliches Zustellzeitfenster bis
    order-preferred-delivery-day Beauftragung-Zustelltag-Flag (true=es wurde ein Zustelltag beauftragt, false=es liegt keine Beauftragung eines Zustelltags vor
    preferred-delivery-day Gebuchter Zustelltag
    preferred-delivery-timeframe-from Nicht mehr genutzt
    preferred-delivery-timeframe-to Nicht mehr genutzt
    preferred-timeframe-refused-text Nicht mehr genutzt
    cod-amount Betrag Nachnahme
    cod-currency Nachnahme Währung
    notification-card-printed Benachrichtigungs-Flag (true: Benachrichtigungskarte wurde gedruckt, da Empfänger nicht angetroffen wurde)
    has-digital-notification-cases digitale Benachrichtigung (Mail / Push-Notification) über die Weiterleitung eines zuzustellbaren Sendungen in eine Filiale / Packstation
       
    Events  
    event-timestamp Zeitstempel Event
    event-text / event-status Status-Text Event
    event-short-status Kurz-Status-Text Event
    division Kennzeichnet die interne Produktionslinie
    ice "International Coded Event" (siehe Anhang ICE/RIC)
    ric "Reason Instruction Code" (siehe Anhang ICE/RIC)
    standard-event-code Standardcode für das Sendungsereignis (siehe Anhang standard-event-code)
    event-location Ort der Erstellung des Sendungsereignisses
    event-country Land der Erstellung des Sendungsereignisses

     

    Wichtig: Die Attribute mit dem Hinweis Steht nicht mehr zur Verfügung! sollten für eine clientseitige Auswertung nicht mehr herangezogen werden, da sie in Zukunft nicht mehr in der Antwort enthalten sein werden!

    Anhang: ICE_Event_RIC_Kombinationen_11_2021.csv
     

    d-get-signature

    Die Funktion "d-get-signature" kann die Unterschrift des Empfängers bzw. des Ersatz-Empfängers abgerufen werden. Die Unterschriften werden auch POD = Proof of Delivery genannt.

    Folgende Besonderheiten sind hier zu beachten:

    • Empfängerunterschriften können nur über die Sendungsnummer abgerufen werden.
    • Die Unterschrift selbst wird in Form eines GIF-Bildformates bereitgestellt. Da dieses Bildformat binäre Daten enthält und diese bei der Übertragung in XML Probleme verursachen würden, werden die Daten byteweise in Hexadezimal-Schreibweise umgewandelt.
    • Die Zugriffe sind typischerweise sehr ressourcenintensiv. Es empfiehlt sich Unterschriften nur für ausgelieferte Sendungen (delivery-event-flag = 1) mit dest-country = DE abzurufen, da nur für diese Sendungen Unterschriften im System verfügbar sind. Die Unterschriften dürfen nur einmalig abgerufen werden. Wenn Sie eine Unterschrift bereits abgerufen haben, sollten Sie diese in Ihrem System abspeichern, um später darauf zugreifen zu können.
    • Bitte beachten Sie hierbei die Vorschrift der Datenminimierung gemäß Art. 5 Abs. 1c EU-DSGVO. 
      Der Download der Empfänger-Unterschrift als Auslieferungsnachweis darf nur in strittigen Fällen oder beim Vorliegen rechtlicher Vorgaben erfolgen.
       

    Hinweis: Zur Anzeige der Unterschrift als Bilddatei, muss die Zeichenfolge in das gif-Bildformat umgewandelt werden. Dabei gilt, jeweils zwei Zeichen der Bilddaten aus der Antwort, entsprechen einem Hexadezimal-Code. Ein Wert FF entspricht beispielsweise 255 dezimal, somit ist das ASCII Zeichen für den Code Nr. 255 die korrekte Interpretation. Die Transformation aller Zeichen liefert das gültige Bild.
     

    Beispieldaten

    Request
    https://api-eu.dhl.com/parcel/de/tracking/v0/shipments?xml=
    
    <?xml version="1.0" encoding="UTF-8" ?>
    <data appname="Benutzerkennung"
             password="Passwort"
             request="d-get-signature
             zip-code= PLZ
             piece-code="Sendungsnummer"
             date-from="2023-01-01"
             date-to="2023-03-31">
    </data>
    Response
    <?xml version="1.0" encoding="UTF-8" ?>
    <data name="signaturelist"
    	code="0"
    	request-id="379d9788-5a8e-49dd-9f7e-d30e17746c2a">
    	<data name="signature"
    		event-date="11.03.2012"
    		mime-type="image/gif"
    		image="4749463.....3b" />
    </data>
    HTTP-Direktaufruflink

    Aufruf der Funktion "Verfolgen" (DHL Sendungsverfolgung für Privatkunden) über einen HTTP-Direktaufruflink

    Syntaxbeschreibung:

    Technische Beschreibung des HTTP-Direktaufruflinks. 
    URL: https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html

     

    Attribute Beschreibung Beispiel
    piececode Suche nach Sendungsnummer oder Referenznummer https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=XXXXXXXXXX
    lang Gewünschte Sprache für die Ergebnismeldung in Deutsch oder Englisch (2-stelliger ISO-Ländercode "de" für Anzeige in Deutsch oder "en" für Anzeige in Englisch)

    https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=XXXXXXXXXX&lang=de

    https://www.dhl.de/en/privatkunden/pakete-empfangen/verfolgen.html?piececode=XXXXXXXXXX&lang=en

     

    Wie testet man die API

    Um unsere API zu testen, können Sie unsere Testsuite hier herunterladen.

    Das bekannte API-Tool Postman können Sie hier beziehen: Postman API Platform | Sign Up for Free: Postman API Platform | Sign Up for Free

    Um sie zu nutzen, müssen folgende Schritte durchgeführt werden:

    • Zugang zur Sandbox-Umgebung beantragen und einen API-Schlüssel erhalten (siehe Get Access für weitere Details)
    • Sammlung in Postman importieren (siehe offizielle Dokumentation der Postman Lernplattform)
    • Hinzufügen von "Authorization" durch base64 kodierten "username:password"
    • Ersetzen Sie den Wert der Variable "dhl-api-key" durch Ihren persönlichen API-Schlüssel

    Wichtige und nützliche Hinweise

    • Mit der Testsuite ist es derzeit nicht möglich, die die Operation "get-status-for-public-user" zu nutzen. Ebenfalls können mehrere Sendungsnummern in einer Anfrage nicht in der Testsuite verarbeitet werden.
       
    • Die Sendungsverfolgungs-API funktioniert ausschließlich mit der GET-Methode. Bitte berücksichtigen Sie dieses entsprechend bei der Entwicklung.
       
    • Die Testsuite arbeitet in der Sandboxumgebung ausschließlich mit den von uns bereitgestellten und hinterlegten Sendungsnummern:
      00340434161094042557 
      00340434161094038253
      00340434161094032954
      00340434161094027318 
      00340434161094022115
      00340434161094015902
       
    • Bei den zurück gelieferten Daten in der Response handelt es sich z.T. um sog. Rohdaten, die ggf. noch weiter für den Endkunden aufbereitet werden müssen.

    Um die Abkürzungen der einzelnen Events genau zuordnen zu können, bzw. um eine selbstredende Erklärung anzureichern, empfehlen wir Ihnen den Download der hier bereitgestellten Tabelle mit den verschiedenen Kombinationen in der jeweils aktuellen Version.

    Anhang: ICE_Event_RIC_Kombinationen_03_2023.csv

    RIC_2023

    FAQ

    Warum erhalte ich bei gültigen Sendungsnummern keine Auskunft über die DASS Business-Funktionen?

    Da über die Business-Funktionen detaillierte Informationen (Adressdaten) zur Verfügung gestellt werden, dürfen Geschäftskunden nur die für sie relevanten Sendungen sehen. Hier erfolgt eine Prüfung, ob die Sendung im Nummernbereich des Kunden liegt. Sollte das nicht der Fall sein, ist die Sendungssuche erfolglos.

    Warum werden Sendungen auch nach längerer Zeit nicht als zugestellt ausgewiesen, obwohl einige sogar schon zugestellt sind?

    Bei diesen Sendungen handelt es sich ausschließlich um internationale Sendungen. In Abhängigkeit des Ziellandes, kann es vorkommen das eine Sendung mehr als 3 Wochen unterwegs ist. Hinzu kommt das wir von einigen Partnerländern keine Rückmeldung über die Zustellung erhalten. Wir bemühen uns aber diesen Kommunikationsaustausch sukzessive zu verbessern.

    Warum erhalte ich beim Absenden einer DASS-Abfrage die Meldung "The request sent by the client was syntactically incorrect."?

    Prüfen Sie den Request noch einmal im Detail. Meist ist ein kleiner Tippfehler im Request selbst die Ursache. Dies kann ein fehlendes Anführungszeichen oder ein nicht geschlossenes Element sein. Prüfen Sie auch, ob Sie die richtige URL für den Funktionsaufruf verwenden. Diese unterscheiden sich nach Business und Public.

    Support

    Sie können in unserem Kunden-Center Unterstützung anfordern. Sie können ein Ticket erstellen, mit dem Sie direkten Support vom DHL Support anfordern können. Bitte beschreiben Sie Ihre Anfrage so detailliert wie möglich und senden Sie uns auch reproduzierbare Auszüge aus der Webservice-Kommunikation. Wir werden versuchen, Ihnen in den folgenden Zeiten so schnell wie möglich bei Ihrem Problem zu helfen:

    IT Customer Support & Integration Paket

    Geschäftszeiten: Mo-Fr 8 bis 16 Uhr

    Allgemeine Geschäftsbedingungen

    Freigabebedingungen

    Diese rechtlichen Hinweise ersetzen und/oder ändern nicht die geltenden "Allgemeinen Geschäftsbedingungen von DHL Paket für Geschäftskunden", die unter https://www.dhl.de/de/geschaeftskunden/paket/rund-um-den-versand/agb.html abrufbar sind, oder andere Versanddienstleistungsverträge, die für Ihre Paketsendungen gelten.

    Diese rechtlichen Hinweise ersetzen und/oder ändern nicht die geltenden "Allgemeinen Geschäftsbedingungen von DHL Paket für Privatkunden" die unter https://www.dhl.de/de/privatkunden/information/agb.html abrufbar sind, oder andere Versanddienstleistungsverträge, die für Ihre Paketsendungen gelten.

    Falls Sie als Drittsoftwareanbieter, Verkäufer, Marktplatzbetreiber oder anderweitig als Handelsvertreter im Auftrag von DHL und/oder den mit ihr verbundenen Unternehmen handeln, d.h. mit Zustimmung von DHL und/oder den mit ihr verbundenen Unternehmen, sind Sie verpflichtet, den Kunden (d.h. den jeweiligen Absender der Sendung) auf die geltenden Versandbedingungen hinzuweisen.

    Sie dürfen die Services und/oder Daten, die Sie über die DHL Paket DE Sendungsverfolgung API erhalten, nur für die rechtmäßigen vertraglichen Zwecke und nur in Verbindung mit Ihren bzw. den DHL-Sendungen der Versandkunden verwenden.

    Für die Nutzung und/oder den Zugriff auf die DHL Paket DE Sendungsverfolgung API gelten die folgenden Voraussetzungen und/oder Einschränkungen:

    • Hinterlegung der Zugangsdaten zur DHL Sendungsverfolgung (ZT-Kennung, Passwort). Bei Shopsoftware-Anbietern und Marktplätzen müssen diese Zugangsdaten für jeden teilnehmenden Versandhändler konfigurierbar sein.
    • Übergabe der Zugangsdaten im XML Request
    • Die Anzahl der Abfragen pro Mandant darf folgende Grenzwerte nicht überschreiten:
      • pro Tag (zwischen 0:00 und 23:59 Uhr) max. 1.000 Abfragen mit insgesamt 10.000 Sendungen
      • max. 3 Anfragen pro Sekunde
    • Für bereits zugestellte Sendungen darf keine erneute Abfrage des Sendungsstatus erfolgen.
    • Bei Einbindung des DHL Paket Logos in Webanwendungen müssen die Logovorgaben unter https://www.dpdhl-brands.com/de/dhl/logo-and-claim beachtet werden.
    1.0.0
    14.Nov.2023

    Wechsel des API Customer Integration Gateways (CIG) mit dem Endpunkt https://cig.dhl.de auf neuen Endpunkt der API https://api-eu.dhl.com/parcel/de/tracking/v0/