DHL Paket DE Abholen (Post & Paket Deutschland)
v 3.0.0
Division: Post & Parcel Germany, Parcel

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 
Region: Deutschland
Used for: Abholen
Übersicht

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

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 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

    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.

     

    Anwenderhandbuch

    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.).

    Voraussetzung Prod_23_0

     

    Voraussetzung Prod_23_1

     

    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.

    Voraussetzung Prod_23_2

     

    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.

     

    Postman Collection

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

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

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

    Einrichten der Postman Test Collection

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

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

     

    Anwendungsfälle

    Übersicht 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"
                    }
                ]
            }
        }
    ]
    FAQs
    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

    Support

    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 

    Gesetzliche Bestimmungen
    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
    21.Aug.2024
    • 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