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:

1. 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.
   
    
2. 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.
   
    
3. 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.
   
    
4. 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 Sendungen (shipmentState ):

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

1. Paketabholung an einem vereinbarten Abholort
2. 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:

Fehler- und Status-Codes

In der folgenden Tabelle sind die möglichen Statuscodes zur Information der Ausführung von Abholungen aufgeführt:

Fehlercodes: 

Statuscodes: 

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.