Geeignet für:
Mit der DHL Sendungsverfolgung API können Privat- und Geschäftskunden jederzeit den Sendungsstatus und -verlauf von Sendungen abfragen.
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:
- Einen Überblick der fachlichen Funktionen, die die API abdeckt
- Die technische Dokumentation der API
- Das Anwenderhandbuch enthält Themen zu Verbindungen und Authentifizierung
- WADL als technische Beschreibung mit Beispielen unter Referenzen
- Eine Testsuite mit Beispiel-Aufrufen als Postman Collection unter Downloads.
- Weiterhin finden Sie Themen zu Anwendungsfällen, FAQ und Support Kontakt
- Am Ende befinden sich die Release Notes
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.
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:
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:
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:
- 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.
-
- 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 DHL Paket DE Sendungsverfolgung API nutzen zu können, benötigen Sie:
-
API Gateway Authentifizierung "App"
- kann über den Get Access Button oben auf dieser Seite angefordert werden
- besteht aus API key und API secret und wird als Basic authorization verwendet
Mit dieser Authentifizierung kann die DHL Paket DE Sendungsverfolgung API für öffentliche Abfragen ("public"-Abfrage) genutzt werden.
Für die Nutzung der DHL Paket DE Sendungsverfolgung API für Geschäftskunden ("business"-Abfrage) muss zusätzlich ein Benutzerkonto im Post & DHL Geschäftskundenportal (GKP) eingerichtet werden.
-
Benutzer des Post & DHL Geschäftskundenportals
- die Anlage eines Benutzers im Post & DHL Geschäftskundenportal erfolgt durch einen Administrator des Geschäftskunden
- zur Nutzung der Sendungsverfolgungs-API für Geschäftskunden muss die Funktion „Verfolgen Paket & Waren“ eingerichtet werden
Dies gilt sowohl für die Sandbox als auch für die Produktionsumgebung.
Sandbox
Für die Nutzung der DHL Paket DE Sendungsverfolgung API benötigen Sie zunächst die Authentifizierung Ihrer App in der Umgebung: .
Zusätzlich müssen im Webservice die folgende Zugangsdaten angegeben werden:
- Benutzer: zt12345
- Passwort: geheim
Der oben angegebene Benutzer und das Passwort müssen im XML-Teil der Anfrage eingetragen werden:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <data appname="zt12345" language-code="de" password="geheim" 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 DHL Paket DE Sendungsverfolgung API benötigen Sie zunächst die Authentifizierung Ihrer App in der Umgebung: Production (Global), Production (Europe).
Zusätzlich müssen im Webservice die folgende Zugangsdaten angegeben werden:
- Benutzer: GKP User mit Freigabe der Funktion „Verfolgen Paket & Waren“
- Passwort: "Passwort des oben genannten Benutzers".
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="Benutzer" language-code="de" password="Passwort" 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. |
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.
Ü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 englischde
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=
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>
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 |
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.
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.
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
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
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/