Am besten geeignet für
- Kostenlose oder kostenpflichtige Paketabholungen über den Webservice buchen
- Abfrage der, dem Benutzer zugewiesenen, vereinbarten Abholorte
- Abfrage von Details und Status zu einer Abholung
Sie befinden sich auf der Dokumentations-Seite der DHL Paket DE Abholen API von Post & Paket Deutschland. 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
- Postman Collection
- Die Open API Spezifikation und Beispiel-Aufrufe unter Referenzen
- Weiterhin finden Sie Themen zu UseCases, FAQ und Support Kontakt unter Downloads.
- Am Ende befinden sich die Release Notes
Umfang
Geschäftskunden können:
- Abholaufträge an vereinbarten Abholorten in Deutschland (Abholkosten sind im Paketpreis enthalten) erteilen
Abholaufträge an vereinbarten Abholorten erfordern eine entsprechende Konfiguration der Abholorte in den DHL-Systemen - diese müssen im Post & DHL Geschäftskundenportal (GKP) vorhanden sein. Bitte prüfen Sie alle möglichen vereinbarten Abholorte und Informationen, bevor Sie Abholaufträge erteilen.
- Abholaufträge an einer beliebigen Adresse in Deutschland (zusätzliche Kosten pro Abholauftrag und -versuch) erteilen
Abholaufträge an beliebigen Adressen in Deutschland (Einzelabholauftrag) erfordern eine gültige Abrechnungsnummer, die im GKP des Kunden konfiguriert ist. Falls der Service "Einzelabholauftrag mit Etikettendruck” (der DHL Zusteller bringt das Versandetikett bei der Abholung mit) genutzt wird, muss eine Abrechnungsnummer im Verfahren 08 (DHL Retoure mit Abholung) im GKP konfiguriert sein.
- Alle vereinbarten Abholorte, die dem Benutzer zugewiesen sind, abfragen
Alle Abholorte, die dem Benutzer zur Beauftragung für “Abholaufträge an vereinbarten Abholorten” zugewiesen wurden, können abgefragt werden.
- Details und den Status eines Abholauftrages abfragen
Die Details zu einem beauftragten Abholauftrag können durch den Benutzer abgefragt werden. Ebenfalls erhält er Informationen in welchem Status sich die gesamte Abholung und je nach Abholart der detaillierte Abholstatus je Sendung aktuell befindet.
Status der Abholung (orderState):
Status der Abholung |
Bedeutung |
Status wird für die Abholart verwendet |
||
Abholung an vereinbarten Abholorten |
Abholung an einer beliebigen Adresse (Einzelabholung) |
|||
Einmalige Abholung |
Bedarfs-abholung |
|||
In Prüfung |
Die Umsetzung des Abholauftrages wird durch DHL geprüft. |
Ja |
Nein |
Nein |
Angenommen |
Der Abholauftrag wurde bestätigt. |
Ja |
Ja |
Ja |
Teilbestätigt |
Der Abholauftrag wurde bestätigt, aber in mehrere Teilaufträge aufgeteilt. |
Ja |
Nein |
Nein |
Abgelehnt |
Der Abholauftrag kann nicht durchgeführt werden und wurde daher abgelehnt. |
Ja |
Nein |
Nein |
In Durchführung |
Die Abholfahrt hat begonnen und erfolgt vermutlich heute |
Nein |
Ja |
Ja |
Verzögerung |
Die Abholfahrt wurde abgebrochen. Die Abholung erfolgt i.d.R. am nächsten Werktag. |
Nein |
Ja |
Ja |
Nicht abgeholt |
Die Abholung konnte nicht erfolgreich durchgeführt werden |
Nein |
Ja |
Ja |
Abgeholt |
Die Abholung konnte erfolgreich durchgeführt werden |
Nein |
Ja |
Ja |
Teilabholung |
Ein Teil der Sendungen, die in dieser Abholung enthalten waren, wurden abgeholt |
Nein |
Nein |
Ja |
Storniert |
Der Abholauftrag wurde storniert |
Ja |
Ja |
Ja |
Status der Sendungen (shipmentState ):
Status der Sendung |
Bedeutung |
Status wird für die Abholart verwendet |
|
Abholung an vereinbarten Abholorten |
Abholung an einer beliebigen Adresse |
||
Bedarfsabholung |
|||
AUFTRAG_IN_PRUEFUNG |
Der Auftrag für diese Sendung befindet sich aktuell in Prüfung. |
Ja |
Ja |
AUFTRAG_ENTGEGENGENOMMEN |
Der Auftrag für diese Sendung wurde entgegengenommen. |
Ja |
Ja |
ERFOLGREICH |
Die Sendung wurde erfolgreich abgeholt. |
Ja
|
Ja
|
ERFOLGREICH_OHNE_SENDUNGSNR |
Die Sendung ohne Sendungsnummer wurde erfolgreich abgeholt. |
Ja
|
Ja
|
ERFOLGREICH_WUNSCHORT |
Die Sendung wurde erfolgreich am Wunschort abgeholt. |
Ja
|
Ja
|
ERFOLGREICH_WUNSCHORT_OHNE_SENDUNGSNR |
Die Sendung ohne Sendungsnummer wurde erfolgreich am Wunschort abgeholt. |
Ja
|
Ja |
ERFOLGREICH_PAKETKASTEN |
Die Sendung wurde erfolgreich am Paketkasten abgeholt. |
Ja
|
Ja
|
ERFOLGREICH_PAKETKASTEN_OHNE_SENDUNGSNR |
Die Sendung wurde erfolgreich am Paketkasten abgeholt. |
Ja
|
Ja
|
NICHT ABGEHOLT (NICHT_ANGETROFFEN) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da niemand angetroffen wurde. |
Ja
|
Ja
|
NICHT ABGEHOLT (KEINE_SENDUNG) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da keine Sendung vorhanden war. |
Ja
|
Ja |
NICHT ABGEHOLT (UNBEKANNT) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da der Kunde unter dieser Adresse nicht vorzufinden war. |
Ja
|
Ja
|
NICHT ABGEHOLT (NICHT_AGB_KONFORM) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da sie nicht AGB konform war. |
Ja
|
Ja
|
NICHT ABGEHOLT (FRANKIERUNG_UNZUREICHEND) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da sie nicht ausreichend frankiert wurde. |
Ja
|
Ja
|
NICHT ABGEHOLT (NICHT_VERSANDFERTIG) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da sie nicht versandfertig war. |
Ja
|
Ja
|
NICHT ABGEHOLT (BEREITS_EINGELIEFERT) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da sie bereits eingeliefert wurde. |
Ja
|
Ja
|
NICHT ABGEHOLT (ABHOLUNG_ABGEBROCHEN) |
Die Sendung konnte nicht erfolgreich abgeholt werden, da die Abholtour abgebrochen werden musste. Die Abholung erfolgt i.d.R. am nächsten Werktag |
Ja
|
Ja
|
Voraussetzungen
Um Abholaufträge über die Abholen API zu erteilen, müssen die folgenden Voraussetzungen erfüllt sein:
- Geschäftskundenvertrag mit DHL Paket GmbH
- mind. ein GKP-Benutzer mit Zugriffsrechten für die Funktion "Abholung"
- je nach Anwendungsfall mindestens ein vertraglich vereinbarter Abholort oder eine Abrechnungsnummer, die für den GKP-Benutzer konfiguriert ist
Benutzung der API
Abholarten
Abhängig von der Anzahl und Beschaffenheit der Pakete und dem Ort, an dem die Abholung erfolgen soll, können über die Abholen-API verschiedene Dienstleistungen beauftragt werden
- Paketabholung an einem vereinbarten Abholort
- Paketabholung an einer beliebigen Adresse in Deutschland
Paketabholung an einem vereinbarten Abholort (Kosten sind im Paketpreis enthalten)
Erfordert mindestens einen vereinbarten Abholort für die verwendete Kundennummer (EKP), die mit DHL Paket besteht und im Post & DHL Geschäftskundenportal konfiguriert ist.
Abhängig von der Anzahl oder den Eigenschaften der Pakete erfolgt die Abholung als
- Bedarfsabholung durch den Zusteller (in der Regel bis zu 10 Pakete)
- Einmalige Abholung als geplante Abholtour (bei mehr als 10 Paketen/Tag oder Sperrgüter)
Bedarfsabholung durch den Zusteller
Für Geschäftskunden, die keine regelmäßige (tägliche) Abholung mit DHL vereinbart haben.
- Abholort muss mit dem DHL-Vertrieb vereinbart sein
- Abholaufträge für den nächsten Werktag müssen bis 22:00 Uhr erteilt werden
- Abholung Montag-Samstag möglich
- Abholung durch den DHL-Zusteller auf der regulären Zustelltour
- Max. 10 Pakete/Tag und Abholort
- Keine Sperrgüter
- Kosten sind im Paketpreis enthalten
- Nicht kombinierbar mit zusätzlichen Abholservices (z.B. Einzelabholauftrag mit Etikettendruck)
- In der Regel gibt es einen Abholscan pro Paket
Falls mehr als 10 Pakete/Abholaufträge pro Tag/Standort vorliegen, wird der Abholauftrag zu einem Einmaligen Abholauftrag umgewandelt.
Einmalige Abholung
Für Geschäftskunden, die keine regelmäßige (tägliche) Abholung durch DHL haben und eine Abholung für mehr als 10 Pakete, Sperrgüter oder ein höheres Volumen zusätzlich zu ihrer regulären Abholung bestellen möchten
- Abholort muss mit dem DHL-Vertrieb vereinbart sein
- Abholaufträge können für den nächsten Tag montags bis freitags bis 12 Uhr erteilt werden
- Ausführung muss von DHL bestätigt werden
- Ausführung mit einer separaten Abholtour
- Ausführung in der Regel Mo-Fr möglich, Samstag nicht in allen Regionen
- Abholung von mehr als zehn Paketen pro Standort/Tag oder Sperrgut- Sendungen. Die Sendungen müssen in Rollbehältern, Wechselbrücken oder auf Paletten für die Abholung bereitgestellt werden.
- Nicht kombinierbar mit zusätzlichen Abholservices (z.B. Einzelabholauftrag mit Etikettendruck)
- Kein Abholscan für jedes Paket
Die Einmalige Abholung ist lediglich ein Abholauftrag, er wird vorab von der DHL-Transportkoordination bewertet - eine Abholung am gewünschten Abholtag wird nicht automatisch gebucht. Wenn eine E-Mail im Abholauftrag angegeben und die Benachrichtigung “sendPickupConfirmationEmail” ausgewählt wurde, wird der Geschäftskunde per E-Mail über das Ergebnis dieser Prüfung informiert.
Eine weitere bilaterale Kommunikation kann erforderlich sein.
Der Status zu einer Abholung ist außerdem im Post & DHL Geschäftskundenportal oder per entsprechender Abfrage über die API ersichtlich.
Paketabholung an einer beliebigen Adresse in Deutschland (kostenpflichtige Einzelabholung)
Erfordert mindestens eine für den Benutzer eingerichtete Abrechnungsnummer im Post & DHL Geschäftskundenportal.
- Abholung von bis zu 10 Paketen oder Sperrgut-Sendungen je Standort und je Ausführungstag
- Abholaufträge für den nächsten Werktag müssen bis 22:00 Uhr erteilt werden
- Abholung Montag-Samstag möglich
- Abholung durch den DHL-Zusteller auf der regulären Zustelltour
- Abholung an jeder leitcodierbaren Adresse in Deutschland möglich
- Kostenpflichtig, auch wenn die Abholung nicht erfolgreich ist
- Zusätzlicher, kostenpflichtiger Service " Einzelabholauftrag mit Etikettendruck" möglich
o DHL druckt und bringt das Versandetikett mit
o Falls eine Abholung nicht möglich ist, wird das Versandetikett in den Briefkasten eingeworfen
o Für die Buchung des Services ist eine Abrechnungsnummer im Verfahren 08 erforderlich - Stornierung für einen Auftrag am nächsten Tag bis 22:00 Uhr möglich
- Abholscan für alle Pakete
Adressen
- Abholadresse: Adresse, bei der die Sendung abgeholt werden soll
- Zieladresse (nur wenn Etikettendruck beauftragt wird): Adresse, an die die Sendung zugestellt werden soll
Für die folgenden Abholadressen können keine Abholungen bestellt werden:
- Groß-Empfängeradressen ("Großempfänger")
- Postämter
- DHL Packstationen
- DHL-Paketshops
Bitte beachten Sie: Wenn eine Sendung in einem DHL Paketshop oder einer Packstation eingelagert ist, kann eine neue Zustellung über https://www.dhl.de/nochmal-zustellen durch den Kunden beauftragt werden.
Abholtermine
Paketabholung an einer beliebigen Adresse in Deutschland und Bedarfsabholung
- können bis 22:00 Uhr für den folgenden Werktag beauftragt und storniert werden
- können bis zu 14 Tage im Voraus beauftragt werden
- können montags bis samstags von 8:00 bis 18:00 Uhr erfüllt werden
- die Buchung von Zeitfenstern ist nicht möglich
- der Abholzeitrahmen wird erst am Abholtag bekannt gegeben
- wird im Abholauftrag eine E-Mail-Adresse und der Benachrichtigungstyp “sendPickupTimeWindowEmail” ausgewählt, kann, wenn verfügbar, der Abholzeitraum am Abholtag per E-Mail bekannt gegeben werden
Einmalige Abholungen
- können montags bis freitags bis 12 Uhr für den nächsten Werktag beauftragt werden (Ausnahme: Samstag)
- Beauftragungen für Samstage müssen am Donnerstag bis 12 Uhr aufgegeben werden, falls eine Einmalige Abholung am Samstag im PLZ-Gebiet möglich ist
- die Verfügbarkeit wird von der DHL-Transportkoordination geprüft - der Kunde kann sich darüber per E-Mail informieren lassen oder im Post & DHL Geschäftskundenportal und via API den Status erfahren.
- können bis zu 14 Tage im Voraus beauftragt werden
- Abholzeitfenster sind nicht möglich
- Abholung in der Regel vormittags, Öffnungszeiten werden nach Möglichkeit berücksichtigt
Hinweis:
Es ist möglich, in der API-Anfrage "asap" als Abholtag anzugeben. In diesem Fall wird ein Abholauftrag für den nächstmöglichen Tag erteilt. Dieser Tag wird in der API-Antwort zurück geliefert.
Services
Serviceleistungen sind nur bei Paketabholung an einer beliebigen Adresse in Deutschland möglich.
Sperrgut
Für die Abholung von Sperrgut ist das Feld "Bemerkung zum Sperrgut" ein Pflichtfeld und muss ausgefüllt werden.
Bitte beachten Sie: Die Definition von Sperrgut ist in den FAQs aufgeführt. Weitere Details zu den Geschäftskundenprodukten und -services von DHL Paket finden Sie unter: https://www.dhl.de/de/geschaeftskunden/paket/leistungen-und-services/paket.html
Etikettendruck
Das Versandetikett kann über den Etikettendruckservice von DHL erstellt werden. Hierfür muss neben der Abholadresse auch eine gültige deutsche Zieladresse angegeben werden.
Sendungsnummer/Tracking-ID
Wenn der Etikettendruck durch DHL nicht beauftragt wurde, muss die Sendung für eine erfolgreiche Abholung bereits ein gültiges Versandetikett haben.
Wird bei der Auftragserteilung keine Sendungsnummer angegeben, wird automatisch eine Sendungsnummer aus dem zentralen Nummernkreis von DHL verwendet.
Bitte beachten Sie:
- Geben Sie bei der Beauftragung von Abholungen immer die Sendungsnummer des Pakets an; dies erleichtert die Identifizierung der abzuholenden Sendung
- Bei Nutzung des Services "Einzelabholauftrag mit Etikettendruck " wird eine Sendungsnummer von DHL zur Verfügung gestellt.
Weitere Informationen und Empfehlungen
- Ein DHL-Produkt kann mehrere Abrechnungsnummern oder Teilnahmen haben, z.B. zur Unterscheidung von Standorten, Kunden oder Aktionen. Wir empfehlen Shop-Software-Anbietern und Marktplätzen, in diesen Fällen mehrere Felder für die Eingabe von Abrechnungsnummern oder Teilnahmen einzurichten.
- Wenn Sie als Marktplatz- oder Shopsoftware-Anbieter nicht alle DHL Produkte und Services über die API anbinden möchten, empfehlen wir Ihnen, zusätzlich einen direkten Aufruflink zum Post & DHL Geschäftskundenportal zu integrieren, den Sie über die Funktion "Abholung" aufrufen können.
Im Folgendem geben wir Ihnen einen Überblick wie Sie auf die API zugreifen können.
Zugang erhalten
Registrieren Sie Ihre DHL Paket DE Pickup API um die API Zugriffsschlüssel zu bekommen:
Nutzen Sie den "Zugang erhalten" Link (es wird eine neue APP erzeugt) oder fügen Sie die API einer existierenden APP zu.
Bitte beachten Sie, dass die Sandbox APP keine weitere Freigabe bedarf, die produktive Nutzung wird explizit von uns freigegeben. Sie erhalten eine Nachricht, sobald die APP den Status Approved erhält.
Hier finden Sie weitere Hilfe zum anlegen einer APP.
Authentifizierung
Access Token
Für den Zugriff auf APIs von Post & Paket Deutschland, müssen Sie sich zunächst gegen die Authentication API verifizieren. Im Austausch bekommen Sie einen Access Token, der für weitere API Zugriffe verwendet wird. Folgen Sie hierfür der Anleitung unter Authentication API (Post & Paket Deutschland).
Hinweis: Die Authentication API (Post & Paket Deutschland) wird Ihnen automatisch zugeordnet; Sie müssen nichts weiter tun.
Sandbox
Um die "DHL Parcel DE Pickup API" zu nutzen, müssen sie zunächst einen APP mit dieser API im Modus "Customer (Integration) Testing" angelegt haben. Unter Get Access wird die Anlage einer APP beschrieben.
Diesen Nutzername und Passwort verwenden Sie bitte um über die Authentication API einen Access Token zu bekommen.
Username: "user-valid" Password: "SandboxPasswort2023!" Description: Valider Post & DHL Geschäftskunden Benutzer
Der folgende curl Aufruf veranschaulicht die Abfrage eines Tokens sowie die Nutzung der Pickup API:
curl -k -i -X POST -H "accept: application/json" -H 'content-type: application/x-www-form-urlencoded' https://api-sandbox.dhl.com/parcel/de/account/auth/ropc/v1/token -d 'grant_type=password&username=user-valid&password=SandboxPasswort2023!&client_id=KH2iQ8YwGYtGs4XUBKaGaiyWBPEZnsRm&client_secret=V8yPDt8GlGlNMRCh'
Mit dem validen Access Token können Sie die Returns API nutzen.
Versuchen Sie den einfachen Zugriff der API version (ohne Access Token):
curl -H "accept: application/json" https://api-sandbox.dhl.com/parcel/de/shipping/pickup/v3/
Fragen Sie nun die Abholadressen ab (mit Access Token):
curl -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" https://api-sandbox.dhl.com/parcel/de/shipping/pickup/v3/locations
Eine genaue Beschreibung der Pickup API finden Sie in der "Open API Specification".
Den Download der "Open API Specification" finden Sie hier.
Produktion
Um die "DHL Parcel DE Pickup API" zu nutzen, müssen sie zunächst einen APP mit dieser API im Modus "Production (Europe)" angelegt haben. Unter Get Access wird die Anlage einer APP beschrieben.
Verwenden Sie innerhalb der Authentication API Ihren Post & DHL Geschäftskunden Benutzer um einen Access Token zu bekommen.
Bitte beachten Sie bei der Auswahl des Geschäftskunden Benutzers: Aus Sicherheitsgründen empfehlen wir die Nutzung einer "System Benutzers", da es mit diesem Benutzer nicht möglich ist, sich im Frontend des Post & DHL Geschäftskundenportals einzuloggen. "System Benutzer" dienen speziell der Anbindung von technischen Schnittstellen.
Wichtig! DHL Vertragskunden erhalten die Zugangsdaten für den Zugang zur Produktion aus dem Post & DHL Geschäftskundenportal über den DHL Paketvertrieb.
Hinweis:
- Für Paketabholung an einer beliebigen Adresse in Deutschland: Im GKP können Sie nachsehen, welche Abrechnungsnummern / Kundennummern für einen Benutzer verfügbar sind.
- Im Menü zuerst die persönlichen Daten aufrufen (1.), dann "Abholen" auswählen (2.).
Bitte beachten:
- Abholaufträge können nur für deutsche Adressen erteilt werden.
- Abholkosten für vereinbarte Abholorte sind im Paketpreis enthalten, die Abholorte müssen im Voraus vereinbart werden.
- Paketabholung an einer beliebigen Adresse in Deutschland (nicht im Voraus vereinbart) werden auch dann in Rechnung gestellt, wenn sie nicht erfolgreich sind.
Wir empfehlen:
- Eine Abrechnungsnummer im Verfahren 08 für Abholungen an einer beliebigen Adresse. Damit wird die Möglichkeit geschaffen, den Service " Einzelabholauftrag mit Etikettendruck" zu nutzen.
- Einen GKP-Benutzer mit der Rolle "Systembenutzer" - für solche Benutzer ist eine Passwortänderung nur einmal im Jahr erforderlich (persönlicher Benutzer: 3 Monate).
- Für Abholungen an vorher vereinbarten Orten: Bitte prüfen Sie alle verfügbaren Abholorte und die Informationen zu diesen im GKP. Hierfür ist ein GKP-Benutzer mit Zugriffsrechten für "Abholung" und zusätzlich für "Einstellungen" erforderlich.
Umgebungen
Die adressierbaren API-Basis-URL/URI-Umgebungen sind:
Umgebung | Description | Comment |
---|---|---|
https://api-eu.dhl.com/parcel/de/shipping/pickup/v3/ | Produktions- umgebung | Die produktive Verwendung wird nach erfolgreicher Nutzung der Sandbox durch DHL freigeschaltet. |
https://api-sandbox.dhl.com/parcel/de/shipping/pickup/v3/ | Sandbox- (Test.-) umgebung | Die Nutzung der Sandbox ist auch möglich, wenn Sie noch kein DHL Paket Geschäftskunde sind. |
Fehler- und Status-Codes
In der folgenden Tabelle sind die möglichen Statuscodes zur Information der Ausführung von Abholungen aufgeführt:
Fehlercodes:
Code | Beschreibung | Empfehlung |
---|---|---|
1 | Interner Fehler | Auftrag kann zurzeit nicht bearbeitet werden. Bitte DHL kontaktieren. |
2 | Autorisierung fehlgeschlagen | Bitte Post & DHL Geschäftskundenportal Benutzernamen und/oder Passwort prüfen. |
3 | Ungültiger Request | Bitte Request Struktur prüfen. |
4 | Fehlende Pflichtangabe | Bitte alle Pflichtangaben ergänzen. |
5 |
Ungültige Angabe |
Bitte Auftragsdaten prüfen. |
6 | Abholadresse nicht leitcodierbar | Bitte Abholadresse per PLZ-Suche der Deutsche Post Direkt www.postdirekt.de/plzserver auf Gültigkeit |
7 | Empfängeradresse nicht leitcodierbar | Bitte Empfängeradresse per PLZ-Suche der Deutsche Post Direkt www.postdirekt.de/plzserver auf Gültigkeit prüfen. |
8 | Anzahl Sendungen für Abholdatum oder Abholadresse überschritten | Bitte Anzahl abzuholender Sendungen oder Abholdatum anpassen. |
9 | Erforderliche Anzahl an Sendungen für den Ausführungstag nicht erreicht | Bitte anderes Abholdatum wählen. |
10 | Abholdatum ungültig | Bitte Abholdatum prüfen. |
11 | Abholdatum nach cut-off, in der Vergangenheit oder zu weit in der Zukunft | Bitte anderes Abholdatum wählen. |
12 | Abholdatum ist Feiertag oder Abholungen können an diesem Tag nicht ausführt werden | Bitte anderes Abholdatum wählen. |
13 | Abholdatum ist ein Sonntag | Bitte anderes Abholdatum wählen. |
14 | E-Mailadresse nicht akzeptiert | Bitte E-Mailadresse auf Gültigkeit prüfen. |
15 | Abrechnungsnummer fehlt | Bitte Kundenkonfiguration für die Funktion Abholen im Post & DHL Geschäftskundenportal prüfen, mindestens eine Abrechnungsnummer wird für diese Auftragsart benötigt. |
16 | Abrechnungsnummer nicht zulässig | Diese Abrechnungsnummer ist in der Kundenkonfiguration vom Post & DHL Geschäftskundenportal nicht für die Funktion Abholen konfiguriert. |
17 | Abholstelle unbekannt | Bitte Abholort prüfen oder kostenpflichtige Abholung beauftragen. |
18 | Am Abholdatum wird bereits eine Regelabholung von DHL am Abholort ausgeführt | Bitte Abholdatum prüfen. |
19 | Abholauftrag kann am Abholort nicht ausgeführt werden | Bitte Abholort prüfen oder kostenpflichtige Abholung beauftragen. |
Statuscodes:
Code | Beschreibung |
---|---|
200 | OK - Die Anfrage wurde erfolgreich bearbeitet. |
201 | Erstellt - Die Anfrage wurde erfolgreich bearbeitet und hat zur Erstellung einer oder mehrerer neuer Ressourcen geführt |
400 | Bad Request - Die Anfrage konnte vom Server aufgrund einer fehlerhaften Syntax nicht verstanden werden. |
401 | Unauthorized - Der Client konnte nicht authentifiziert werden, da der Anfrage der erforderliche HTTP-Header fehlt oder die Anmeldeinformationen falsch sind. |
403 | Verboten - Der Client wurde erfolgreich authentifiziert, konnte aber für die betreffende Anfrage nicht autorisiert werden. |
404 | Nicht gefunden. |
409 | Konflikt. |
422 | Unverarb.eitbare Entität |
429 | Too Many Requests - Der Aufrufer hat sein Anfragekontingent überschritten. |
500 | Interner Serverfehler. |
503 | Service nicht verfügbar. |
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 der Anwendungsfälle
- Abholauftrag
- Abholauftrag löschen
- Abholauftrags-Details und -Status abrufen
Beispiel Aufrufe
Hinweis: Diese Beispiel Aufrufe decken nur die grundlegenden Operationen der API ab. Ausführliche Beispiel Aufrufe für alle Produkte und Services finden Sie in unserer Postman Testsuite, weitere Erläuterungen im Kapitel wie testet man die API.
Abholauftrag
Erteilt einen Paketabholauftrag für eine Reihe von Paketen.
POST /parcel/de/transportation/pickup/v3/orders?validate=true HTTP/1.1
Host: https:api-sandbox.dhl.com
Authorization: Bearer <Token>
Content-Length: 1380
Content-Type: application/json
{
"customerDetails": {
"billingNumber": "22222222220801"
},
"pickupLocation": {
"type": "Address",
"pickupAddress": {
"name1": "Maxi Mustermann",
"name2": "",
"addressStreet": "Charles-de-Gaulle-Str.",
"addressHouse": "20",
"postalCode": "53113",
"city": "Bonn",
"country": "DE"
}},
"pickupDetails": {
"pickupDate": {
"type": "Date",
"value": "2099-01-01"
},
"comment": "Test API Abholen"
},
"shipmentDetails": {
"shipments": [
{
"transportationType": "PAKET"
}
]
},
"contactPerson": [
{
"name": "Maxi Mutermann",
"phone": "015155555",
"email": "maxi@post.de",
"emailNotification": {
"sendPickupConfirmationEmail": "true",
"sendPickupTimeWindowEmail": "true"
}
},
{
"name": "Max Mutermann",
"phone": "015166666",
"email": "max@post.de",
"emailNotification": {
"sendPickupConfirmationEmail": "false",
"sendPickupTimeWindowEmail": "false"
}
}
]
}
Abholauftrag löschen
DELETE /parcel/de/transportation/pickup/v3/orders?orderID=4f2cc6d60d9b4170b6f9101e30164857 HTTP/1.1
Host: https://api-sandbox.dhl.com
Authorization: Bearer <Token>
Content-Type: application/json
{
"confirmedCancellations": [
{
"orderID": "4f2cc6d60d9b4170b6f9101e30164857",
"orderState": "STORNIERT",
"message": "Erfolgreich storniert"
}
],
"failedCancellations": [
{
"orderID": "stringstringstringstringstringst",
"orderState": "string",
"message": "string"
}
]
}
Abholauftrags-Details und -Status abrufen
GET /parcel/de/transportation/pickup/v3/orders?orderID=4f2cc6d60d9b4170b6f9101e30164857 { OR &pickupDate=<string>&pickupName1=<string>&pickupStreetName=<string>&pickupHouseNumber=<string>&pickupPostalCode=<string>&pickupCity=<string> } HTTP/1.1
Host: https://api-sandbox.dhl.com
Authorization: Bearer <Token>
Content-Type: application/json
[
{
"orderDetails": {
"orderID": "4f2cc6d60d9b4170b6f9101e30164857",
"orderState": "STORNIERT"
},
"customerDetails": {
"accountNumber": "3333333333",
"billingNumber": "22222222220801"
},
"pickupLocation": {
"pickupAddress": {
"name1": "Maxi Mustermann",
"name2": "",
"addressStreet": "Charles-de-Gaulle-Str.",
"addressHouse": "20",
"postalCode": "53113",
"city": "Bonn"
}
},
"businessHours": [],
"contactPerson": [
{
"name": "Maxi Mutermann",
"phone": "015155555",
"email": "maxi@post.de",
"emailNotification": {
"sendPickupConfirmationEmail": true,
"sendPickupTimeWindowEmail": true
}
},
{
"name": "Max Mutermann",
"phone": "015166666",
"email": "max@post.de"
}
],
"pickupDetails": {
"pickupDate": {
"type": "Date",
"value": "2099-01-01"
},
"comment": "Test API Abholen"
},
"shipmentDetails": {
"shipments": [
{
"shipment": {
"transportationType": "PAKET",
"customerReference": ""
},
"shipmentState": {
"state": "AUFTRAG_IN_PRUEFUNG"
},
"orderDate": "2024-08-15 17:21:17"
}
]
}
}
]
Wie viele einzelne Abholaufträge sind pro vereinbartem Abholort zulässig?
Pro vereinbartem Abholort können maximal 10 Sendungen pro Tag als Bedarfsabholung beauftragt werden.
Wenn mehr als 10 Sendungen abgeholt werden sollen, können Sie die Auftragsart "Einmalige Abholung" verwenden.
Was bedeuten die Größen S, M, L?
Die Größen beziehen sich auf die längste Seite eines Paketes
- Bis zu 30 cm: S
- Bis zu 60 cm: M
- Bis zu 120 cm: L
Wann gilt ein Paket als Sperrgut?
Als Sperrgut gelten unter anderem folgende Sendungen:
Sendungen außerhalb des Standardmaßes oder die aufgrund ihrer Beschaffenheit (z. B. mit außergewöhnlichen Formaten, bei Verpackungsbesonderheiten oder mit bestimmten Verpackungsmaterialien) eine besondere betriebliche Bearbeitung erforderlich machen.
Abmessungen außerhalb des Standardmaßes:
Alle Sendungen, die die Abmessungen 120 x 60 x 60 cm überschreiten oder 15 x 11 x 1 cm unterschreiten, sind als Sperrgut zu versenden. In diesem Zusammenhang sind auch die maximale Länge von 200 cm und das maximale Gurtmaß* von 360 cm zu beachten.
Verpackungsform
- Runde Sendungen (Höchstmaße: Länge: 200 cm**; Durchmesser: 60 cm)
- Sendungen mit dreieckigem Querschnitt
- Sendungen, bei denen Teile der Verpackung abstehen
- Sendungen, die nicht quaderförmig sind
- Sendungen, die nicht stabil auf der Sortieranlage befördert werden können, z. B. durch unebene Auflagefläche oder abstehende Verpackungsteile und die instabil sind
- Mehrere zusammengeschnürte Pakete, die das Standardmaß überschreiten
Verpackungsbesonderheiten
- Sendungen mit loser/lockerer Schnürung oder Umreifung
- Sendungen, die aufgrund der äußeren Beschaffenheit oder ihres instabilen Inhalts sowie einer unzureichenden Innenverpackung nicht auf der Sortieranlage beförderbar sind
Verpackungsmaterial
- Bestimmte Kunststoffe/Folien
- Metall
- Holz/Holzwerkstoffe
- Stoff
- Sendungen mit Gummibändern oder -umreifung
- Sendungen, die komplett mit Paketklebeband beklebt sind
*längste Seite + 2 x Breite + 2 x Höhe
** Wenn Rollen mit einer zugelassenen Beförderungshilfe bis 120 cm mit Freigabenummer der Deutschen Post versehen werden, können diese ohne Sperrgutzuschlag versandt werden. Barcodes und Anschrift müssen sich hierbei auf der größten Fläche der Versandmanschette befinden.
Was bedeuten die Codes für den Ausführungsstatus der einzelnen Abholungen?
Abgeholt
10: Abholung erfolgreich
11: Abholung erfolgreich (ohne Sendungsnummer)
12: Abholung erfolgreich (am gewünschten Ort)
13: Abholung erfolgreich (am gewünschten Ort ohne Sendungsnummer)
Nicht abgeholt
30: Nicht angetroffen
31: Keine Sendung zur Abholung verfügbar
32: Unbekannt (Adresse, Kunde)
33: Sendung entspricht nicht den Bestimmungen und Bedingungen
34: Sendung nicht ausreichend frankiert
35: Sendung nicht versandfertig
36: Sendung bereits aufgegeben
Verspätung
37: Die Abholung erfolgt aus betrieblichen Gründen am nächsten Arbeitstag
Sie erhalten Unterstützung in unserem Help Center . Sie können ein Ticket eröffnen, um direkte Unterstützung durch den DHL Support zu bekommen. Bitte beschreiben sie ihre Anfrage so detailliert wie möglich und senden sie uns nachvollziehbare Auszüge der Webservice Kommunikation. Wir versuchen ihnen so schnell wie möglich in den folgenden Zeiten mit ihrem Problem zu helfen:
IT Kundensupport & Integration Paket
Geschäftszeiten: Mo - Fr von 8.00 - 16 Uhr
Besondere Bedingungen für die Nutzung und/oder den Zugang zur "DHL Paket DE Abholen API"
Um sich für die Nutzung der DHL Paket DE Abholen API zu registrieren, müssen Sie und/oder die juristische Person, die Sie zu vertreten berechtigt sind (im Folgenden "Sie"/"Ihr"), über ein aktives Kundenkonto im Post & DHL Geschäftskundenportal (im Folgenden "DHL") verfügen. Ein API-Produktivschlüssel und die Zugangsdaten werden Ihnen vorbehaltlich einer erfolgreichen Validierung Ihrer Anmeldedaten durch DHL zur Verfügung gestellt. Wenn Sie einen externen Entwickler oder einen anderen IT-Dienstleister damit beauftragen, Ihre Anwendung zu entwickeln, oder einen anderen Dritten damit beauftragen, in Ihrem Namen auf die DHL Paket DE Abholen API zuzugreifen und/oder diese zu nutzen, haften Sie in vollem Umfang für alle Handlungen oder Unterlassungen dieser Dritten im Zusammenhang mit dem Zugriff auf und/oder der Nutzung der DHL Paket DE Abholen API.
Diese rechtlichen Hinweise ersetzen und/oder ändern nicht die geltenden "Allgemeinen Geschäftsbedingungen von DHL Paket für Geschäftskunden", abrufbar unter https://www.dhl.de/de/geschaeftskunden/paket/rund-um-den-versand/agb.html, 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 Sendungen) auf die geltenden Versandbedingungen hinzuweisen.
Sie dürfen die Services und/oder Daten, die Sie über die DHL Paket DE Abholen API erhalten, nur für die rechtmäßigen vertraglichen Zwecke und nur im Zusammenhang mit Ihren bzw. den DHL-Sendungen der Kunden nutzen.
Für die Nutzung und/oder den Zugriff auf die DHL Paket DE Abholen API gelten die folgenden Voraussetzungen und/oder Einschränkungen:
- Gültige Abrechnungsnummer
- Gültiger Nutzername des Post & DHL Geschäftskundenportals (GKP)
- Gültiges Passwort
Bitte beachten Sie die folgenden zusätzlichen Hinweise und Empfehlungen:
Die o.g. Bedingungen müssen für jeden teilnehmenden Händler (etwa auf einem Marktplatz oder im Rahmen einer Shopsoftware) konfigurierbar sein und eine entsprechende Dokumentation für den Versandkunden erstellt werden.
3.0.0
- Einführung der Authentifizierungsmethode OAuth2 (anstelle von Basic Auth)
- Abfrage aller dem Benutzer zugewiesenen vereinbarten Abholorte
- Einführung einer zusätzlichen Möglichkeit der Beauftragung anhand der ID des Abholortes neben der per Adresse
- Auswahl der Informationen, die verschickt werden sollen (E-Mail-Benachrichtigungstyp)
- Angabe einer zweiten E-Mailadresse zur E-Mail-Kommunikation
- Überarbeitung des Status einer Abholung