API Typ: REST
aktuelle Version

Download API Spec

 

Die Erteilung von Paketabholungen per Webservice ist möglich für:

1. Paketabholungen am vereinbarten Abholort in Deutschland (Abholkosten sind im Paketpreis inkludiert)
2. Paketabholungen von beliebiger Adresse in Deutschland (kostenpflichtig, je Auftrag und Ausführungsversuch)

Paketabholungen am vereinbarten (eigenen) Abholort erfordern, dass mindestens ein Abholort für die verwendete Kundennummer (EKP) vertrieblich vereinbart und systemisch durch DHL eingerichtet wurde. Bitte überprüfen Sie vor der ersten Beauftragung, dass die Angaben zum Abholort vollständig sind.

Paketabholungen von beliebiger Adresse (nicht vereinbart) erfordern, dass der zur Beauftragung verwendete Geschäftskundenportalbenutzer für mindestens eine Abrechnungsnummer berechtigt ist. Sofern der Service "Etikettendruck" (DHL erstellt für die Abholung das Versandlabel) beauftragt werden soll, muss der Benutzer für eine Abrechnungsnummer im Verfahren 08 (DHL Retoure mit Abholung) berechtigt sein.

Voraussetzungen zur produktiven Nutzung sind:

• Gültiger Geschäftskundenvertrag mit der DHL Paket GmbH
• Gültiger Post & DHL Geschäftskundenportalbenutzer mit Berechtigung für die Funktion "Abholen (neu)"
• Abhängig vom Anwendungsfall mind. ein vertraglich vereinbarter Abholort oder die Berechtigung des Geschäftskundenbenutzers für mind. eine Abrechnungsnummer

Tipp:
Für welche Abrechnungsnummern ein Benutzer berechtigt ist, kann im Post & DHL Geschäftskundenportal im Menü "Persönliche Daten" (oben rechts) unter dem Reiter "Abholen" jederzeit eingesehen werden.

Bitte beachten Sie:

• Paketabholungen können nur innerhalb Deutschlands ausgeführt werden können
• Die Kosten für Abholungen an Vereinbarten Abholorten sind im Paketpreis enthalten, die Abholorte müssen daher vertrieblich vereinbart werden
• Bei Abholungen anderen Adressen (nicht vereinbarte) wird der Abholversuch in Rechnung gestellt, also auch nicht erfolgreich ausgeführte Abholungen

Wir empfehlen:

• Eine Abrechnungsnummer im Verfahren 08 zu verwenden für Abholungen von beliebiger Adresse, damit der optionale Service Etikettendruck im Bedarfsfall genutzt werden kann.
• Die Verwendung eines Geschäftskundenportalbenutzers in der Rolle "Systembenutzer" mit einer Passwortgültigkeit von 12 Monaten für alle Webservice Beauftragungen.
• Vereinbarte Abholorte im Post & DHL Geschäftskundenportal auf Gültigkeit zu prüfen und ggf. zu vervollständigen. Dazu wird ein gültiger Geschäftskundenportalbenutzer mit Berechtigung für die Funktion "Abholen" und der Unterberechtigung für "Einstellungen" benötigt.

Tipp:
Welche Abholorte vereinbart sind, sowie die Pflege der Abholortdetails können Sie jederzeit im Post & DHL Geschäftskundenportal im Menü "Paket & Waren" --> "Abholen" --> "Einstellungen" einsehen.

Abhängig von der Anzahl an Sendungen, der Beschaffenheit und dem Ort, an dem die Abholung ausgeführt werden soll, können unterschiedliche Produkte per API Abholen 360° beauftragt werden:

1. Paketabholungen am vereinbarten Abholort

2. Paketabholung Abholung von beliebiger Adresse

Paketabholungen am vereinbarten Abholort (Abholkosten im Paketpreis inkludiert)

Erfordert, dass mindestens ein Abholort für die verwendete Kundennummer (EKP) vertrieblich vereinbart und systemisch durch DHL eingerichtet wurde.
Abhängig von der Sendungsmenge  oder Sendungsart erfolgt die Ausführung der Abholung als:

• Bedarfsabholung im Rahmen der Paketzustellung (i.d.R. für bis zu 10 Pakete)
• Einmalige Abholung per geondert geplanter Abholung (für größere Sendungsmengen oder Sperrgüter)

Bedarfsabholung

Für Kunden, die selten oder unregelmäßig Pakete produzieren, bei denen in Folge eine regelmäßig Abholung (z.B. täglich) nicht sinnvoll ist.

• Abholort muss mit DHL vereinbart sein
• Verbindliche Beauftragung bis 22:00 Uhr am Vortag der Ausführung möglich
• Ausführung Mo-Sa. möglich
• Abholung wird im Rahmen der Paketzustellung ausgeführt
• Abholung von bis zu 10 Paketen je Abholort und Ausführungstag
• Abholung von Sperrgütern nicht möglich
• Abholkosten im Paketpreis enthalten
• Ausführung der Abholung erfolgt im Rahmen der Paketzustellung
• Nicht mit Services kombinierbar (kein Etikettendruck)
• i.d.R. erfolgt ein Annahmescan der Pakete bei Abholung

Sobald die Sendungsmenge bei einer Bedarfsabholung 10 Pakete überschreitet, wird eine Bedarfsabholung in eine Einmalige Abholung gewandelt, sofern die Annahmefrist für Einmalige Abholungen noch nicht abgelaufen ist.

Einmalige Abholung

Für Kunden, die selten oder unregelmäßig Pakete produzieren und mehr als 10 Pakete an einem Tag zur Abholung beauftragen, oder zusätzlich zur Regelabholung eine Abholung größerer Sendungsmengen beauftragen möchten.

• Abholort muss mit DHL vereinbart sein
• Beauftragungen sind Mo.-Fr. bis 12:00 Uhr für den daraufolgenden Tag möglich
• Ausführung vorbehaltlich Bestätigung durch DHL
• Ausführung erfolgt per gesonderter Fahrt
• Ausführung Mo-Fr. i.d.R. möglich, Samstags nicht in allen Gebieten verfügbar
• Abholung von mehr als 10 Sendungen je Abholort und -tag, Sperrgütern oder zusammengefassten Sendungen in Rollbehältern, Wechselbrücken oder auf Palette
• Anlieferung von Rollbehältern, Wechselbrücken oder Paletten, auch zum Tausch bei Abholung 
• Nicht mit Services kombinierbar (kein Etikettendruck)
• i.d.R. erfolgt kein Annahmescan der Pakete bei Abholung

Bei einem Auftrag für eine einmalige Abholung wird lediglich eine Abholanfrage bei der DHL Transportkoordination ausgelöst - es ist damit noch nicht automatisch die Abholung am gewünschten Abholtag gebucht. Die DHL Transportkoordination prüft zunächst die Verfügbarkeit einer Abholmöglichkeit und meldet diese per E-Mail an den Kunden zurück (an die EMail-Adresse, die für den Abholstandort im DHL Geschäftskundenportal hinterlegt ist). Gegebenenfalls ist eine weitere bilaterale Abstimmung erforderlich.

Paketabholung Abholung von beliebiger Adresse in Deutschland (kostenpflichtige Einzelabholung)

Erfordert, dass der verwendete Benutzer für mindestens eine Abrechnungsnummer im Post & DHL Geschäftskundenportal berechtigt ist:

• Abholung von bis zu 10 Paketen oder Sperrgütern je Abholort und Ausführungstag
• Beauftragung bis 22:00 Uhr am Vortag der Ausführung möglich
• Ausführung Mo-Sa. möglich
• Abholung wird im Rahmen der Paketzustellung ausgeführt
• Ausführung an beliebiger gültiger und leitcodierbarer Abholadresse in Deutschland
• Kostenpflichtig, auch für nicht erfolgreich ausgeführte Abholungen
• Ausführung der Abholung erfolgt im Rahmen der Paketzustellung
• Abholung von Sperrgut als zusätzlicher Service möglich
• Kostenpflichtiger Etikettendruck bei Abholung als zusätzlicher Service möglich
  • DHL druckt das Versandlabel und bringt es beim Abholversuch mit
  • Sofern die Abholung nicht erfolgreich ausgeführt werden kann, wird das Abholetikett in den Briefkasten des Abholortes geworfen
  • Beauftragung muss unter Verwendung einer Abrechnungsnummer im Verfahren 08 erfolgen
• Verbindliche Beauftragung, Stornierung bis 22:00 Uhr am Vortag der Ausführung möglich
• Annahmescan aller Sendungen bei Abholung

Adressen

• Abholort: Adresse, an der die Sendung abgeholt werden soll
• Zieladresse (nur bei Etikettendruck durch DHL): Adresse, an der die Sendung zugestellt werden soll

Nicht zulässige Abholorte sind:

• Großempfänger Adressen
• Postfilialen
• DHL Packstationen
• DHL Paketshops

Tipp:
Sofern eine Sendung nicht erfolgreich zugestellt werden konnte und in einer Filiale, einem DHL Paketshop oder einer Packstation lagert und die Lagerfrist noch nicht abgelaufen ist, kann über https://www.dhl.de/nochmal-zustellen eine erneute Zustellung dieser Sendung durch den Empfänger online beauftragt werden. 

Datum Ausführung

Für Abholungen, die im Rahmen der Paketzustellung ausgeführt werden (Einzelabholung und Bedarfsabholung), gilt:

• Verbindliche Auftragserteilung bis 22:00 Uhr für den darauffolgenden Werktag möglich
• Für bis zu 30 Tage in die Zukunft beauftragbar
• Montag bis Samstag als Ausführungstage möglich
• Ausführung erfolgt i.d.R. von 8:00 - 19:00 Uhr
• Wunschzeiten zur Ausführung sind nicht möglich
• Ausführungszeit wird am tag der Ausführung online beauskunftet
• Sofern eine E-Mailadresse bei Auftragseretilung übergeben wird, wird am Tag der Ausführung das Zeitfenster des Abholversuchs per E-Mail mitgeteilt

Für Abholungen, die gesondert geplant werden müssen (Einmalige Abholungen), gilt:

• Montag bis Freitag bis 12:00 Uhr für den nächsten Werktag (Ausnahme Samstag) beauftragt werden
• Donnerstag bis 12:00 Uhr für den nächsten Samstag beauftragt werden, sofern in dem PLZ-Gebiet eine Einmalige Abholung dann möglich ist
• Alle Aufträge werden einer Prüfung auf Machbarkeit unterzogen und im Anschluss geprüft oder abgelehnt
• Können bis zu 30 Tage in die Zukunft beauftragt werden
• Wunschzeiten zur Ausführung sind nicht möglich
• Abholung erfolgt i.d.R. vormittags, Öffnungszeiten werden nach Möglichkeit berücksichtigt

Tipp:
Es besteht auch die Möglichkeit, als Abholtag "asap" anzugeben. In diesem Fall wird eine Abholung für den nächst möglichen Tag gebucht. Dieser wird in der API-Response entsprechend zurück geliefert.

 Services

Services können ausschließlich für Abholungen von beliebigen Orten (Einzelabholungen) erbracht werden.

Sperrgut

Die Angabe "Sperrgutkommentar" ist für die Abholung von Sperrgütern an beliebigen Orten ein Pflichtfeld

Hinweis: Die Definition für Sperrgüter ist in den FAQs aufgeführt. Weitere Details zu den Geschäftskundenprodukten und -services von DHL Paket finden Sie unter: www.dhl.de

Etikettendruck

Die Erstellung eines Versandlabels kann per Service Etikettendruck durch DHL beauftragt werden. Dafür ist zusätzlich zur Abholadresse die Angabe einer gültigen Zieladresse in Deutschland erforderlich.

Sendungsnummer

Sofern kein Etikettendruck durch DHL beauftragt wird, muss die Sendung für eine erfolgreiche Abholung an einem beliebigen Ort bereits über ein gültiges Versandlabel verfügen.

Sofern keine Sendungsnummer bei der Erteilung eines Einzelabholauftrages erfasst wird, wird eine Sendungsnummer aus dem zentralen Nummernkreis von DHL verwendet.

Tipp:
Übergeben Sie bei Erteilung von Abholungen immer die Sendungsnummer des Paketes, dies erleichtert die eindeutige Zuordnung der abzuholenden Sendung vor Ort.

Weitere Hinweise und Empfehlungen

• Für ein DHL Produkt können mehrere Abrechnungsnummern bzw. Teilnahmen existieren, um z.B. Standorte, Mandanten oder Aktionen zu unterscheiden. Shopsoftwareanbietern und Marktplätzen empfehlen wir für diese Fälle mehrere Felder für den Eintrag der Abrechnungsnummern bzw. Teilnahmen einzurichten.
• Möchten Sie als Marktplatz oder Shopsoftwareanbieter nicht alle DHL Produkte und Services über die Schnittstelle anbinden, empfehlen wir Ihnen zusätzlich die Integration eines Direktaufruf-Links zum DHL Geschäftskundenportal, über welchen die Funktion "Abholen" aufgerufen werden kann.

Authentifizierung

Bitte übergeben Sie den DHL Geschäftskundenportal Benutzernamen ausschließlich in Kleinbuchstaben.

Für die Nutzung der DHL API Abholen 360° benötigen Sie zunächst die CIG-Authentifizierung, hier finden Sie nähere Details.

Sandbox

Zur Erstellung von Abholaufträgen in der Sandbox, haben sie die Möglichkeit, unsere Testsuite mit den folgenden Benutzerdaten zu nutzen:

• Username: 2222222222_abr_0801
• Password: S8PjmLB!s2vrzWV3o

Aus diesen Zugangsdaten ergibt sich base64-codiert:

• DPDHL-User-Authentication-Token: MjIyMjIyMjIyMl9hYnJfMDgwMTpTOFBqbUxCIXMydnJ6V1Yzbw==

Die "Open API Specification" können Sie hier herunterladen.

Zur Erstellung von Testabholaufträgen können ausschließlich folgende Kundendetails verwendet werden:

• Abrechnungsnummer für Einzelabholaufträge: 22222222220801
• Kundennummer für Bedarfabholaufträge und Einmalige Abholungen: 2222222222

Produktion

Für die Nutzung der API Abholen 360° auf der Produktivebene benötigen Sie zunächst die CIG-Authentifizierung Ihrer Applikation im Produktivmodus.

Nähere Details finden Sie unter https://entwickler.dhl.de/group/ep/authentifizierung

Im Webservice müssen zudem folgende Zugangsdaten angegeben werden:

• User: "Benutzer aus dem DHL Geschäftskundenportal" (Benutzer muss für "Abholen" berechtigt sein!)
• Password: "Passwort des oben genannten Benutzers"

Das DPDHL-User-Authentication-Token setzt sich wie folgt zusammen: base64(<USERNAME>:<PASSWORD>)

Bitte bedenken Sie bei der Verwendung des jeweiligen Benutzers auch die Dauer von Passwortgültigkeiten:

• die Passwortgültigkeit eines "Benutzers" beträgt" 90 Tage
• die Passwortgültigkeit eines "Systembenutzers" beträgt" 365 Tage

Mit einem "Systembenutzer" ist eine Anmeldung am DHL Geschäftskundenportal nicht möglich.

Wichtig:

Die Zugangsdaten für das DHL Geschäftskundenportal erhalten Geschäftskunden vom DHL Paket Vertrieb nach Vertragsabschluss.

Testsuite Abholen 360°

Zur Anbindung der API Abholen 360° in der Sandbox, haben sie die Möglichkeit unsere Testsuite zu nutzen.

Die Testsuite haben wir zum Download unter folgendem Link bereitgestellt:

Bitte klicken Sie hier.

Speichern Sie die Datei in einem beliebigen Ordner ab.

Wir empfehlen für den Import die Software Postman, diese Software können sie unter folgendem Link kostenfrei herunterladen:

https://www.getpostman.com

Starten Sie Postman und importieren Sie die zuvor heruntergeladene Testsuite (*.json) (Import):

Bitte erfassen Sie Ihre Credentials wie folgt:

Hiweis: Unter "Variables" sind die Parameter der DP-DHL Sandbox voreingestellt, für die Produktion müssen die Parameter entsprechend angpasst werden (Details im Menüpunkt "Authentifizierung").

Bitte wählen Sie einen der Requests aus und editieren Sie den "Body" mit Ihren Testdaten:

Das Ergebnis wird Ihnen unterhalb des Requests ausgegeben:

Bitte verwenden Sie für die weiteren Requests die "orderNumber", die sie zuvor erstellt haben:

Beispiel "Delete":

Beispiel "Get order details and status":

Die folgende Tabelle listet die möglichen Statuscodes zur Ausführungsbeauskunftung von Abholungen auf: