Geeignet für:
- Geschäftskunden der Post und Paket Deutschland GmbH
- Erstellung und Verwaltung der Versandscheine von nationalen und internationalen Sendungen
Aktueller Hinweis: Die Zugangsdaten für die Sandbox-Umgebung aller Versenden SOAP und REST API Versionen haben sich geändert. Alle notwendigen Informationen finden Sie hier.
Aktueller Hinweis: Version 2 der SOAP API Geschäftskundenversand wird zum 31.05.2025 abgeschaltet.
Weitere Informationen zur anstehenden Abschaltung finden Sie hier.
Sie befinden sich auf der Dokumentations-Seite der DHL Paket DE Versenden API der Post & Paket Deutschland GmbH. In den folgenden Kapiteln bieten wir Ihnen:
- Einen Überblick der fachlichen Funktionen, die die API abdeckt
- Die technische Dokumentation der API
- Das Anwenderhandbuch enthält Themen zu Verbindungen und Authentifizierung
- 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
Die DHL Paket DE Versenden API ermöglicht die Verwaltung von Sendungen sowie den online Kauf von Versandmarken und richtet sich typischerweise an Versender mit einem Volumen von mehr als 200 Sendungen pro Jahr. Für DHL Geschäftskunden, die nicht über ein DHL Geschäftskundenkonto (EKP) verfügen und ein Versandvolumen von weniger als 200 Sendungen pro Jahr haben, erfolgt die Versandscheinerstellung über die Privatkundenversand API.
Benutzung der API
Die DHL Paket DE Versenden API übernimmt
- die Vorbereitung von Versandscheinen für den nationalen und internationalen Versand von warentragenden Sendungen
- Erstellung von Exportdokumenten
- Abruf von Etiketten (Versandlabel)
Allgemeine Grundlagen
Für die Anbindung der DHL Paket DE Versenden API an Ihre Systeme möchten wir Sie mit einigen grundlegenden Informationen zum Warenversand mit Deutsche Post DHL für Geschäftskunden vertraut machen.
Um Sendungen über die DHL Paket DE Versenden API beauftragen zu können, benötigen Sie bzw. Ihr Auftraggeber einen Geschäftskundenvertrag sowie einen Zugang zum Post & DHL Geschäftskundenportal (GKP). Die DHL Paket DE Versenden API muss genau auf diese vertraglich vereinbarten Produkte und Services eingerichtet werden. Zudem müssen die Benutzer-Zugangsdaten zum GKP, die verwendeten Abrechnungsnummern, Absender- und Retouren-Adressen sowie Bankdaten als konfigurierbar angelegt werden.
Es gibt zwei Arten von Benutzern: Systembenutzer und persönliche Benutzer. Systembenutzer sind ausschließlich zur Verwendung in Systemanbindungen oder Webservices zu verwenden. Eine Anmeldung an der GKP-Oberfläche ist mit diesen nicht möglich. Persönliche Benutzer hingegen sind zur Verwendung der GKP GUI angelegt.
Die Zugangsdaten zum GKP setzen sich aus einem Benutzernamen und einem Passwort zusammen. Der Benutzername kann z. B. aus Vor- und Nachnamen bestehen und darf ausschließlich Kleinbuchstaben enthalten. Das Passwort muss den Richtlinien des Post & DHL Geschäftskundenportals entsprechen, um bestimmte Sicherheitskriterien zu erfüllen: Es muss mindestens 8 Zeichen und maximal 20 Zeichen lang sein, mindestens ein Sonderzeichen (!,$,/,(,),=,#,*,+), mindestens ein Buchstabe und mindestens eine Zahl enthalten. Beachten Sie unbedingt Groß- und Kleinschreibung bei der Übergabe des Passwortes.
Die Passwortgültigkeit liegt bei Systembenutzern bei 365 Tagen und bei persönlichen Benutzern bei 90 Tagen. Rechtzeitig vor Ablauf dieser Frist werden Benutzer per E-Mail informiert und erhalten mit dieser E-Mail einen Link zur Vergabe eines neuen Passworts. Falls der Link in der E-Mail abgelaufen sein sollte oder ein Benutzer keine E-Mail erhalten hat, kann er sich über die "Passwort vergessen"-Funktion auf der Anmeldeseite des GKP (https://geschaeftskunden.dhl.de/) ein neues Passwort vergeben.
EKP: Die EKP ist die "Einheitliche Kunden- und Produktnummer" und damit der Schlüssel zur Nutzung der Produkte von Deutsche Post DHL. Sie ist zehnstellig und wird vom Vertrieb vergeben. Über diese Nummer kann jeder Kunde eindeutig identifiziert werden. Sie wird bei allen Systemanbindungen benötigt und muss immer mit übergeben werden.
Verfahren: Als Verfahren werden die Produkte bezeichnet, die für den Versand verwendet werden. Nähere Informationen zu den Produkten finden Sie hier.
Teilnahme: Die sog. Teilnahme ist eine zweistellige numerisch (00 bis 99) oder alphanumerisch (AA bis ZZ) Zeichenfolge. Sie wird vom Vertrieb vergeben. Zu jedem Produkt der DHL Paket (sog. Verfahren) kann ein Kunde eine oder mehrere Teilnahmen verwenden. Es empfiehlt sich daher, die Anzahl der Teilnahmen bei der Konfiguration der Schnittstelle variabel zu halten. Die Teilnahme ermöglicht die Untergliederung von Abrechnungen zum Beispiel nach Standorten, Saisongeschäft oder unterschiedlichen Konditionen. Zudem werden auch bestimmte Services, wie der umweltfreundliche Versand mit GoGreen, als separate Teilnahme hinterlegt.
Bankdaten: Bankdaten werden nur dann benötigt, wenn der Service Nachnahme angebunden wird. Hinterlegt werden müssen hier Angaben zu IBAN, BIC, Zahlungsempfänger, Bankname und Verwendungszweck.
Abrechnungsnummer: Die Abrechnungsnummer ist eine 14-stellige Zeichenfolge. Sie setzt sich zusammen aus der EKP, dem Verfahren (=Produkt) sowie der Teilnahme. Die korrekte Schreibweise erfolgt ohne Leer- oder Sonderzeichen (alle 14 Zeichen direkt hintereinander).
Beispiel:
| 1234567890 | 53 | 01 |
| EKP | Verfahren | Teilnahme |
Labelformat und -druck
In der DHL Paket DE Versenden API stehen Ihnen grundsätzlich alle Labelformate zur Verfügung, die auch im Post & DHL Geschäftskundenportal verfügbar sind. Wir weisen an dieser Stelle ausdrücklich darauf hin, dass ein Skalieren des Labels nicht zulässig ist, da hierdurch die Lesbarkeit des Labels nicht mehr gewährleistet ist. Sendungen, bei denen eine maschinelle Lesbarkeit nicht möglich ist, werden dem Versender aufgrund der erforderlichen manuellen Nachbearbeitung mit einem Nachentgelt in Rechnung gestellt.
Aktuell sind die nachfolgenden Labelformate verfügbar:
- "A4" Common Label Laserdruck A4 Normalpapier
- "910-300-700" Common Label Laserdruck (Bogen A5) 105x208mm (910-300-700)
- "910-300-700-oz" Common Label Laserdruck (Bogen A5) 105x208mm (910-300-700) ohne Zusatzetiketten
- "910-300-710" Common Label Laserdruck 105x209mm (910-300-710)
- "910-300-600" Common Label Thermodruck (Faltband) 103x199mm (910-300-600)
- "910-300-610" Common Label Thermodruck (Rolle) 103x199mm (910-300-610)
- "910-300-400" Common Label Thermodruck (Faltband) 103x150mm (910-300-400)
- "910-300-410" Common Label Thermodruck (Rolle) 103x150mm (910-300-410)
- "910-300-300" Common Label Laserdruck (Bogen A5) 105x148mm (910-300-300)
- "910-300-300-oz" Common Label Laserdruck (Bogen A5) 105x148mm (910-300-300) ohne Zusatzetiketten
Ausschließlich für die Produkte Warenpost und Warenpost International kann zudem das Labelformat 100 x 70 mm genutzt werden. Hierbei ist zu beachten, dass bei diesem Label aufgrund der geringeren Größe einige Informationen nicht angedruckt werden können. Folgende Regeln gelten deshalb für Adressendaten auf diesem Labelformat:
- Absender: Name 2 und Name 3 werden nicht angedruckt
- Für deutsche Empfängeradressen wird Name 3 nicht angedruckt
- Für internationale Adressen werden 6 Zeilen angedruckt, wobei die letzte Zeile immer das Empfängerland ist.
Der Labeldruck mit einem Thermodrucker entspricht einer Auflösung von 203dpi. Wir bitten Sie, dieses entsprechend zu berücksichtigen, damit ein reibungsloser Produktionslauf möglich ist.
Hinweis zur Rückgabe des Labels als reine Datenstruktur: Eine Rückgabe der Label-Informationen als reine Datenstruktur (z.B. im XML-Format) ohne Rückgabe des eigentlichen Labels ist über die DHL Paket DE Versenden API nicht möglich. Die Webservice Antwort enthält jedoch alle durch DHL generierten Datenattribute, die auf dem Label angedruckt werden (z.B. Sendungsnummer, Routingcode).
Druckereinstellungen im Post & DHL Geschäftskundenportal
Sofern alle Benutzer die gleichen Druckereinstellungen verwenden sollen, können diese im Post & DHL Geschäftskundenportal einheitlich konfiguriert werden über den Bereich "Paket & Waren > Versenden > Einstellungen > allgemeine Einstellungen". Wählen Sie in der Rubrik "Anpassung der Einstellung für Benutzer" den Eintrag "Alle Benutzer" und nehmen in derselben Maske die gewünschten Einstellungen vor.
Werden für einzelne Benutzer unterschiedliche Druckereinstellungen benötigt, können diese in der identischen Maske konfiguriert werden. Wählen Sie in der Rubrik "Anpassung der Einstellung für Benutzer" den Eintrag des gewünschten Benutzers aus und nehmen im Anschluss die gewünschten Einstellungen vor.
Die hinterlegten Druckeinstellungen werden aus dem GKP für die DHL Paket DE Versenden API übernommen. Lediglich bei Requests, bei denen eigene Druckeinstellungen mit übergeben werden, werden die im GKP hinterlegten Einstellungen nur für diese Sendung überschrieben (printFormat, retourePrintFormat, combine).
Sendung manifestieren
Angelegte Sendungen werden zunächst ohne Weitergabe der elektronischen Sendungsdaten (PAN-Daten) gespeichert, bis sie manifestiert werden. Manifestieren bezeichnet die endgültige Übergabe der Sendungsdaten an die Post & DHL Backend-Systeme. Dies geschieht im Rahmen des sogenannten Tagesabschlusses. Bei Sendungen, die per Webservice angelegt wurden, erfolgt der Tagesabschluss entweder automatisch am Tagesende zu einem festgelegten Zeitpunkt oder durch die Methode "doManifest". Alle erstellten Sendungen werden dabei in das jeweilige Post & DHL Produktionssystem übergeben. Sendungen können nur dann bearbeitet werden, wenn sie noch nicht manifestiert sind, also noch nicht im Tagesabschluss enthalten waren.
Sonderfall bei Sendungen mit dem Produkt DHL Paket International:
Für Sendungen mit dem Produkt DHL Paket International ist es zwingend erforderlich, dass die Sendungen vor der physischen Übergabe an die internationalen Postgesellschaften manifestiert wurden. Um sicherzustellen, dass die Daten für diese internationalen Sendungen rechtzeitig an die DHL Systeme übertragen werden, wurde ein zusätzlicher automatischer Tagesabschluss speziell für Sendungen mit DHL Paket International eingerichtet. Dieser findet täglich um 20:45 Uhr statt und enthält alle internationalen Sendungen, die nach dem regulären Tagesabschluss erstellt wurden. Der reguläre Tagesabschluss erfolgt standardmäßig um 17:45 Uhr oder zu der Uhrzeit, die für den Kunden in den Versenden-Einstellungen im Post & DHL Geschäftskundenportal hinterlegt ist.
Editieren einer Sendung
Eine manifestierte Sendung kann nicht mehr bearbeitet werden. Solange eine Sendung noch nicht manifestiert ist, kann sie über den Aufruf „DELETE /orders“ gelöscht werden. Im Anschluss kann eine neue Sendung mit den korrigierten Daten über „POST /orders“ angelegt werden.
Rollen und Rechte
Auch bei der DHL Paket DE Versenden API gilt dasselbe Benutzermodell, wie für den Online-Zugriff der Funktion Versenden im Post & Paket Geschäftskundenportal. Dies bedeutet, dass Benutzer und deren Berechtigungen im Bereich "Benutzer verwalten" des GKP angelegt, gelöscht oder geändert werden können.
Benutzer können dem Profil einer bestimmten Benutzergruppe zugeordnet werden. Das Profil der Benutzergruppe definiert die Abrechnungsnummern, die jeder Benutzer dieser Gruppe verwenden kann. Sowohl Systembenutzer als auch persönliche Benutzer sind einer Benutzergruppe zugeordnet. Wenn Sie sich nicht sicher sind, welches Gruppenprofil Sie nutzen können, kontaktieren Sie bitte Ihren Administrator. Der Administrator kann Profilzuordnungen im Post & DHL Geschäftskundenportal unter "Paket &Waren > Versenden > Einstellungen > Benutzergruppen" ansehen und ändern.
Produkte und Services über die Webservice-Schnittstelle
Produkte
Sendungen können über die API-Funktion POST "/orders". erstellt werden. Die Produkte werden im Webservice-Attribut "product" übergeben und durch das "Verfahren" in der Abrechnungsnummer validiert. Die zu verwendenden Verfahren und Produkt-Kürzel finden Sie in der folgenden Übersicht:
Services
Es können zusätzliche Services gebucht werden, so z.B. IdentCheck. Ob ein bestimmter Service verfügbar ist, hängt von dem Produkt und der Berechtigung des Benutzers ab. D.h. ein Service kann für ein bestimmtes Produkt verfügbar sein, kann aber von dem Benutzer nicht genutzt werden.
Es kann auch vorkommen, dass bestimmte Services nicht miteinander kombiniert werden können. Welche Services bei einem Produkt zur Verfügung stehen, finden Sie im nächsten Abschnitt "Details und Kombinatorik".
Details und Kombinatorik
Voraussetzungen für den Warenversand
Die folgende Tabelle enthält eine Übersicht über die für den Warenversand geltenden Minimal- und Maximalmaße und -gewichte je Produkt. Die Parameter für die Erstellung von Versandscheinen müssen innerhalb dieser Grenzwerte liegen. Bei den aufgeführten Parametern handelt es sich um Standardparameter.
Verfügbare Services zu den Produkten
In der folgenden Tabelle finden Sie die verfügbaren Services je Produkt. Sie sind hier der Übersicht halber in vier Servicegruppen eingeteilt, welche jedoch kein Bestandteil der Webservice-Anfragen sind.
Nachfolgend stellen wir Ihnen eine Übersicht bereit, wie Sie Zugang zu der API erhalten.
- technische Details zu der API finden Sie im Kapitel: "API Spezifikation".
- Weitere Hinweise zur Benutzung der API finden Sie in den Kapiteln "Support" und "FAQ".
Zugang erhalten
Registrieren Sie Ihre DHL Paket DE Versenden API um die API Zugriffsschlüssel (API Key, API Secret) 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.
Alternativ können Sie Basic Auth (Username: "user-valid", Password: "SandboxPasswort2023!") zur Authentifizierung nutzen und zusätzlich den API Key (den Sie Ihrer zuerst erstellen APP entnehmen) als request header Parameter ("dhl-api-key") mitgeben. Bitte beachten Sie aber, dass zukünftige API Major Versionen kein Basic Auth mehr unterstützen werden. Wir empfohlen daher OAuth2 zu nutzen.
Sandbox
Um die "DHL Paket DE Versenden API" zu nutzen, müssen sie zunächst eine 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 Versenden 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=${YOUR_API_KEY}&client_secret=${YOUR_API_SECRET}'
Mit dem validen Access Token können Sie die Versenden 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/v2/
Eine detaillierte Beschreibung der DHL Paket DE Versenden API finden Sie unter "Open API Specification". Diese kann über den folgenden Link Open API Specification heruntergeladen werden. Nutzen Sie die dort enthaltenen Beispiele, um erste Versandlabel mit unserer API zu validieren und zu erstellen:
curl -k -i -X POST -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -d ${YOURREQUEST} https://api-sandbox.dhl.com/parcel/de/shipping/v2/orders?validate=True
Folgende Abrechnungsnummern und Services sind in der Sandbox verfügbar:
Produktion
Um die "DHL Paket DE Versenden 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.
Test- und Produktions-Umgebung
Die API ist über folgende Endpunkte erreichbar:
| Umgebung | Beschreibung | Kommentar |
| https://api-sandbox.dhl.com/parcel/de/shipping/v2/ | Sandbox- Umgebung | Die Nutzung der Sandbox ist auch für nicht Geschäftskunden möglich. |
| https://api-eu.dhl.com/parcel/de/shipping/v2/ | Produktions-Umgebuing | Die produktive Verwendung wird nach erfolgreicher Nutzung der Sandbox durch DHL freigeschaltet. |
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-Key & API-Secret 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 client_id und client_secret durch Ihren persönlichen API-Key und API-Secret
Bitte beachten Sie auch unsere Schritt-für-Schritt Anleitung zur Benutzung der Postman Test Collection.
Die folgende Tabelle gibt Ihnen Transparenz über die kommenden Abschaltungen älterer API Versionen. Die Begrifflichkeiten sind unterhalb der Tabelle genauer erklärt.
| API Version | Status | Deprecation Date | Sunset Date |
|---|---|---|---|
| GKV 1.x (SOAP) | Retired | 01.11.2023 | 31.05.2024 |
| GKV 2.x (SOAP) | Superseded | 01.11.2024 | 31.05.2025 |
| GKV 3.x (SOAP) | Superseded | 01.07.2025 | 31.05.2026 |
| Paket DE Versenden V1 (Pilot) | Retired | 01.01.2024 | 30.09.2024 |
| Paket DE Versenden V2 | Active |
Begriffsklärung:
Status "Active": Es wird empfohlen diese API Version zu nutzen.
Status "Superseded": Die API wurde durch eine neuere API Version ersetzt. Bitte wechseln Sie auf die "Active" API Version.
Status: "Deprecated": Der Service wurde eingestellt (mit oder ohne alternativen Service per API). Der Support der API Version ist limitiert auf nötige Fehlerbehebung und Sicherheitsupdates.
Status: "Retired": Die API steht seit dem Sunset Date nicht mehr zur Verfügung.
"Deprecation Date": Von diesem Datum an wird die API im Status "Deprecated" sein. Weiterentwicklung ist limitiert auf nötige Fehlerbehebung und Sicherheitsupdates.
"Sunset Date": The API wird von diesem Zeipunkt an nicht mehr erreichbar sein.
Bekannte Fehler
Aktuell sind uns folgende Fehlerbilder der Paket DE Versenden API bekannt. Wir bemühen uns, diese in den kommenden Releases zu beheben:
- Kennnummer für Zollzwecke wird nicht auf Zollinhaltserklärung angedruckt
- Kontakt Ansprechpartner des Absenders wird nicht auf dem Versandlabel angedruckt, wenn eine Absenderreferenz verwendet wird
- Empfänger Email-Adresse wird in Sendungsdetails nicht angezeigt
- Bei manchen Attributen wird eine Warnung bezüglich der Feldlänge angegeben, obwohl die Feldlänge innerhalb der vorgegebenen Grenzen liegt, das Attribut korrekt verarbeitet wird und das Versandlabel erfolgreich erstellt wird.
- Bei manchen technischen Fehlern weicht die Struktur der Fehlermeldung von der Struktur ab, die in der YAML beschrieben ist.
- Das Attribut shipmentRefNo wird bei mehreren Sendungen innerhalb eines Requests und der Option validate=true nicht in der Response zurückgegeben
Hinweis
- Enthält die Anfrage ein Array mit mehreren Elementen (z. B. mehrere Sendungen), so entspricht die Reihenfolge der Elemente in der Webservice Antwort der Reihenfolge der Elemente in der Webservice Anfrage. Wenn die Anfrage nur ein Element enthält, enthält die Antwort aus Gründen der Konsistenz ein Array mit einem Element.
- Sie können im DHL Geschäftskundenportal Absenderadressen speichern und mit einer Absenderreferenz versehen. Zudem haben Sie die Möglichkeit, zu einer Absenderadresse ein Logo hochzuladen. Im Webservice Request können Sie dann die Absenderreferenz angeben und müssen die Absenderadressdaten nicht gesondert angeben. Bitte beachten Sie, dass bei Übergabe einer Absenderreferenz immer die zu dieser Referenz gespeicherten Adressdaten auf das Label angedruckt werden. Dies gilt auch, wenn Sie im Request zusätzlich explizite Absenderadressdaten mit übergeben.
Zugang, Authentifizierung und Autorisierung
Wo kann ich die Dokumentation der alten Geschäftskunden-Versand-API (SOAP) finden?
Die Dokumentation der alten Geschäftskundenversand-API (SOAP) ist im Download-Bereich des Group API Developer Portals verfügbar.
Bitte erstellen Sie ein Support-Ticket, um Zugang zu erhalten. Es wird empfohlen, auf die aktuelle DHL Paket DE Versenden API (REST) zu wechseln.
Wie Sie den Download-Bereich im Group API Developer Portal finden: Navigieren Sie über das Personensymbol oben rechts zu Ihren privaten Einstellungen und klicken Sie dann den Reiter "Downloads". Nach der Freigabe sehen Sie dann den Bereich "Dokumente".
Wo finde ich Beispiele zur Authentifizierung?
Bitte beachten Sie das entsprechende Kapitel zur Authentifizierung unter Anwenderhandbuch . Dort ist auch ein curl-Beispiel.
Meine Einstellungen funktionieren für getVersion(), aber ich bekomme einen HTTP 401 für alle anderen Aufrufe.
Bitte prüfen Sie die GKP Zugangsdaten (diese werden über den basic auth header bereitgestellt). getVersion() (GET Aufruf der API URL) benötigt diesen nicht, aber alle anderen Aufrufe schon.
Ich habe den Zugang angefragt, aber nach über 48 Stunden noch nichts bekommen
Bitte versuchen Sie es erneut über den folgenden Kontakt Help Center. Die Genehmigung dauert normalerweise nicht so lange, aber wir arbeiten gerade mit der Early Access oder Beta Version.
Encoding
Welches Encoding sollte ich für API-Aufrufe verwenden?
Für alle API-Aufrufe sollten Sie das UTF-8-Encoding verwenden. Die Verwendung von UTF-8 stellt sicher, dass alle Zeichen korrekt interpretiert und verarbeitet werden, insbesondere wenn Ihre Daten Nicht-ASCII-Zeichen enthalten. Wenn Sie ein anderes Encoding verwenden, kann dies zu Fehlern oder unerwarteten Ergebnissen führen.
Labelformat und -druck
Kann ich die Seitenränder verändern wenn ich ZPL label drucke?
Ein Kunde berichtete von einem Erfolg durch folgendes Vorgehen: Vor Versand der erhaltenen ZPL-Datei zum Drucker: Ich ergänzte spontan das ZPL-Kommando (^LS-30) direkt nach Start des ZPL Data (^XA command).”
Kann ich anstatt des Labels auch nur die relevanten Datenattribute abrufen?
Eine Rückgabe der Label-Informationen als reine Datenstruktur (z.B. im XML-Format) ohne Rückgabe des eigentlichen Labels ist über die DHL Paket DE Versenden API nicht möglich. Die Webservice Antwort enthält jedoch alle durch DHL generierten Datenattribute, die auf dem Label angedruckt werden (z.B. Sendungsnummer, Routingcode).
Anfrage Dokument
Werden Mehrpaket-Sendungen unterstützt?
Nein, Mehrpaket Sendungen werden nicht unterstützt. Um Ihren Kunden auf dem Versandlabel kenntlich zu machen, dass mehrere Pakete zu einer Bestellung gehören, können Sie das Attribut „costCenter“ verwenden und dort z.B. „1/2“, „2/2“ eintragen.
AbsenderRef Attribut - wie wird es benutzt
Sie müssen die Absenderreferenz (Adress-Details) im GKP unter “Paket & Waren -> Versenden -> Adressbuch -> Absender” eintragen und dann über das shipperRef Attribut darauf referenzieren. In diesem Fall sind keine Absender-Details notwendig. Ist beides bereitgestellt, wird die ausführlichere Information verwendet. Eine harte Validierung mit HTTP 400 erscheint, wenn die Absenderreferenz unbekannt ist.
Gewicht
Das Gewicht der Sendung ist wichtig für die Abrechnung. Es ein ein Pflichtfeld. Sie können das Gewicht in der Einheit kg oder g angeben. Bei internationalem Versand und notwendiger Zolldokumentation: Es bestehen die gleichen Regeln für einzelne Paket-Gewichte.
Dimensionen
Die Bereitstellung der Abmessungen (Länge, Breite, Höhe) ist optional. Die Einhaltung der Produkt-Beschränkungen wird von DHL geprüft. Wenn Sie diese Angaben bereitstellen werden alle Angaben benötigt (Maßeinheit, Länge, Breite, Höhe).
Packstations-Adresse
Bitte verwenden Sie das Beispiel aus der API Spezifikation. Eine Packstations-Adresse wird anhand des lockerID Attributs identifiziert.
Adresszusatz 1 und Adresszusatz 2 als Elemente der Empfänger-Adresse
Bitte prüfen Sie die API Spezifikation. Diese Elemente werden auf den meisten Labeln nicht gedruckt. Ausnahmen bestehen bei internationalen Paketlabeln für einzelne Länder
Label Download
Wie lange stehen die Label zum Herunterladen via /labels URL bereit?
Über den Aufruf GET /orders können Label erneut für bis zu drei Tagen nach Manifestierung abgerufen werden. Die spezifische Sendungsnummer muss dem Aufruf hinzugefügt werden.
Services
Ich setze premium=false aber PREMIUM wird dennoch auf das Label gedruckt?
Das ist länderspezifisch. Die meisten EU-Länder bieten keine Economy-Produkte an, daher wird premium=true angewendet. Andere Länder (CH) bieten beides an.
COD (cash on delivery) - die kompletten Bankdaten können nicht eingetragen werden
Abhängig von den GKP Benutzer-Rechten kann es erforderlich sein das Konto im GKP anzulegen und über AccountReference in der API darauf zu referenzieren.
DHL Retoure International
Dies wird von der API nicht unterstützt Bitte prüfen Sie die Parcel DE Returns API. Sie können Retourenlabel für nationale Retouren erzeugen (Beileger-Retoure).
Zollinformation
Wenn Zollinformationen bereitgestellt werden, muss das für jedes zu versendende Paket bereitgestellt werden?
Ja.
Muss ich Zollinformationen bereitstellen?
Dies hängt von Absender- und Empfänger-Adresse ab. Immer bei internationalem Versand, wenn dies nicht anders geregelt ist (z. B. ist es innerhalb der Europäischen Union nicht notwendig).
Nordirland ist Teil der Europäischen Union. Damit benötigen Sendungen nach UK die mit dem Postcode "BT" anfangen keine Zollinformationen.
Manifest
Get / manifest erscheint langsam in der Sandbox
Die Sandbox Daten werden stark genutzt. Alle Kunden mit einem Sandbox Account können Sendungen in dieser Umgebung erstellen. Der Befehl "manifest-all" kann eine große Menge an Sendungen umfassen und dauert daher lange.
Bitte beachten Sie: Das Verhalten auf der Produktion ist anders, da die Manifestierung nur ihre eigenen Sendungen betrifft.
Kann ich für jede Abrechnungsnummer ein Manifest erstellen?
Ja, Sie können für jede Abrechnungsnummer ein Manifest erstellen. Dafür verwenden Sie das Attribut „billingNumber“ in dem „POST /manifest“ Aufruf.
Wann wird manifestiert? Muss ich das selbst machen?
Automatisch zu der zuvor eingestellten Zeit, normalerweise am Ende des Arbeitstags. Danach können Sendungen nicht mehr verändert und Label (es sei denn die im Speicher) nicht mehr heruntergeladen werden. Die Manifestierung kann explizit über die API (POST /manifest) angestoßen werden.
Version
Muss ich das aufrufen?
Das ist ein schneller Verbindungstest und gibt Ihnen die gültige Version zurück. Teil der Antwort ist z.B "version": "v2.0.2" - die Version der API. Aktualisierungen der letzten Komponenten - patch level - werden nicht bekanntgegeben, die Kompatibilität wird garantiert.
Fehler
Allgemeine Fehler
Bitte benutzen Sie den verfügbaren Validierungs Schalter für POST /orders. Dieser sagt Ihnen ob bestimmte Elemente fehlen, Atributnamen oder anderes falsch geschrieben wurde. Bitte benutzen Sie die Postman Kollektion (diese enthält Beispiele für gebräuchliche Aufrufe). Bitte beachten Sie, dass die Swagger (OAS) Beschreibung funktionierende Beispiele für die meisten Produkte enthält (Verfügbar über die Auswahl Box wenn post versucht wird).
Ich bekomme eine Fehlermeldung mit Bezug auf
"property": "customs",
"validationMessage" : "Specifiying this line is not possible."
"validationState": "Error"
Normalerweise bekommen Sie diese Fehlermeldung, wenn sie ein DHL Europaket V54EPAK mit mehr als einer Warenkategorie pro Paket versenden. Dieses Produkt erlaubt nur eine einzige Warenkategorie (definiert durch das Attribut “hsCode”).
Ich bekomme eine Fehlermeldung mit Bezug auf
"property": "customs.exportType",
"validationMessage" : "Please enter the type of shipment."
"validationState": "Error"
Normalerweise bekommen Sie diese Fehlermeldung, wenn sie ein DHL Paket International versenden und erwartete Zolldaten fehlen.
Ich bekomme eine Fehlermeldung mit Bezug auf
"property": "billingNumber",
"validationMessage" : "The selected billing number is invalid."
"validationState": "Error"
Normalerweise bekommen Sie diese Fehlermeldung, wenn sie einen Service anfragen, der entweder nicht bekannt ist (prüfen durch validate=true bitte) oder für den die Kontonummer und Rechnungsnummer-Information nicht freigeschaltet ist (z. B. Retoure). In diesem Fall kontaktieren Sie bitte DHL, um das zu prüfen.
Ich bekommen einen HTTP 500 Fehler beim Downlaod eines Labels von der URL zurückgesendet durch den Post Aufruf
Normalerweise haben Sie versucht ein Label nach Ablauf der Gültigkeit zu laden. Vor der Manifestierung- gibt es eine Alternative, um ein Label zu erhalten durch den Aufruf GET /orders. Dies ermöglicht, das Label direkt in der Response zu erhalten und zusätzlich viele weitere Optionen.
Warnungen
Ich bekomme eine Warnung mit Bezug auf
"property": "consignee",
"validationMessage" : "The street entered could not be found."
"validationState": "Warning"
Diese Adress-Daten konnten nicht validiert werden. Sie können das Label benutzen, aber DHL kann dafür Extra-Kosten geltend machen. (Bitte prüfen Sie das mit ihrer vertrieblichen Ansprechperson). Dies wird auch im Routing-Code auf dem Label angezeigt, wenn dieser mit sechs oder mehr Nullen endet. Um das zu vermeiden, setzen Sie den Abfrage Parameter auf mustEncode=true...
Ich sehe das es auch eine dedizierte Retoure API gibt. Was ist der Unterschied?
Die DHL Paket DE Versenden API erlaubt ihnen als Geschäftskunde ein Retoure Label bereits beim Versand der Original-Sendung bereitzustellen. Die DHL Paket DE Retoure API erstellt Retouren-Label analog der DHL Retoure Online nur bei Bedarf. Möchten Sie Internationale Retouren beauftragen nutzen Sie bitte die DHL Paket DE Retoure API.
Ich sehe deutsche Fehlermeldungen. Sind auch Englische verfügbar?
Ja, englische Fehlermeldungen sind ebenfalls verfügbar. Sie können die Sprache als Parameter in der Kopfzeile des Requests definieren.
Währungen können im Request angegeben werden, welche kann ich benutzen?
Bitte nutzen sie EUR als Währung für cash on delivery (COD). Das Zollformular erlaubt jede andere Währung, die in der ISO-4217 definiert ist.
Go-Live
Ich bin ein Easylog-Kunde und möchte auf REST umstellen. Was muss ich beachten?
Sie sollten Ihre vertriebliche Ansprechperson kontaktieren. Normalerweise benötigen Sie neue Abrechnungsnummern, um Überschneidungen zwischen Easylog und durch die API erzeugte Sendungen zu vermeiden.
Wie lange dauert die Freischaltung um die Produktions-Umgebung zu nutzen?
Sie sollten innerhalb von 1-3 Werktagen die Freischaltung der produktiven API erhalten haben.
Benutze ich den gleichen Schlüssel für Produktion und Sandbox?
Wenn Sie die Anfrage sowohl für Sandbox als auch für Produktion in der gleichen APP gestellt haben, wird der Schlüssel sowohl für Sandbox als auch für Produktion aktiviert. Dies kann gemäß Ihren Wünschen eingestellt werden. Wir können auch einen produktiven Zugang hinzufügen, wenn Sie ursprünglich nur einen Sandbox Zugang angefragt haben.
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:
Geschäftszeiten: Mo - Fr von 8.00 - 16 Uhr
IT Kundensupport & Integration Paket
Spezielle Bedingungen für die Nutzung und/oder den Zugang zur "DHL Paket DE Versenden API"
Um sich für die Nutzung der DHL Paket DE Versenden 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 Versenden API zuzugreifen und/oder diese zu nutzen, bleiben Sie in vollem Umfang haftbar für alle Handlungen oder Unterlassungen dieser Dritten in Verbindung mit dem Zugriff auf die DHL Paket DE Versenden API und/oder deren Nutzung.
Diese rechtlichen Hinweise ersetzen und/oder ändern nicht die geltenden "Allgemeinen Geschäftsbedingungen von DHL Paket für Geschäftskunden", die unter https://www.dhl.de/de/geschaeftskunden/paket/rund-um-den-versand/agb.html abrufbar sind, oder andere Versanddienstleistungsverträge, die für Ihre Paketsendungen gelten.
Falls Sie als Drittsoftwareanbieter, Verkäufer, Marktplatzbetreiber oder anderweitig als Handelsvertreter im Auftrag von DHL und/oder den mit ihr verbundenen Unternehmen handeln, d.h. mit Zustimmung von DHL und/oder den mit ihr verbundenen Unternehmen, sind Sie verpflichtet, den Kunden (d.h. den jeweiligen Absender der Sendung) auf die geltenden Versandbedingungen hinzuweisen.
Sie dürfen die Services und/oder Daten, die Sie über die DHL Paket DE Versenden API erhalten, nur für die rechtmäßigen vertraglichen Zwecke und nur in Verbindung mit Ihren bzw. den DHL-Sendungen der Versandkunden verwenden.
Für die Nutzung und/oder den Zugriff auf die DHL Paket DE Versenden API gelten die folgenden Voraussetzungen und/oder Einschränkungen:
- Die DHL Paket DE Versenden API bietet die Möglichkeit, Versandetiketten zu erstellen und zu drucken sowie Sendungen zu buchen. Bitte beachten Sie, dass durch die Buchung der Sendung in der DHL Paket DE Versenden API kein Beförderungsvertrag zustande kommt. Der Beförderungsvertrag kommt erst mit der Übergabe oder Abholung der Sendung und deren Annahme durch DHL zustande.
- Bitte beachten Sie, dass die DHL Paket DE Versenden API nur Sendungen von Deutschland nach Deutschland und von Deutschland in andere Länder ermöglicht. Die Erstellung von Versanddokumenten aus dem Ausland nach Deutschland und aus dem Ausland ins Ausland ist über die DHL Paket DE Versenden API nicht möglich.
- Bitte beachten Sie, dass die Standardimplementierung der Funktionalität "Label drucken und Dokumente exportieren" (createShipmentOrder) als PDF-Label erfolgt; eine Implementierung nach der "Common Label Spezifikation" bedarf einer gesonderten Genehmigung durch DHL.
- Sie müssen Ihr Post & DHL Geschäftskundenportal (Kundennummer oder "EKP", Verfahren, Produkte, Services etc.) entsprechend den Erfordernissen der DHL Paket DE Versenden API konfigurieren. Wenn Sie als Anbieter einer Drittsoftware (z.B. Shopsoftware) oder Marktplatzbetreiber agieren, müssen diese Konfigurationen für jeden Versandkunden (Händler) einzeln vorgenommen werden.
- Credentials (User/Passwort) für das Post & DHL Geschäftskundenportal müssen im XML-Request mitgeliefert/freigegeben werden.
- Bei der Nutzung des Service "Nachnahme" ("COD") müssen die Bankdaten (inkl. BIC und IBAN für nationale und internationale Überweisungen) im XML-Request übermittelt/freigegeben werden.
- Sie müssen die Funktionalität "Sendung stornieren" (deleteShipmentOrder) in Ihrer Anwendung implementieren.
- Für alle Produkte muss unbedingt ein Wert für das Gewicht geliefert werden. Dieser Wert kann einen vordefinierten Standardwert haben (nur für vertraglich vereinbarte Festpreise im Verfahren 01) oder aus dem spezifischen Gewicht der Sendung bestehen. Dementsprechend muss die Erkennung/Vorgabe in der E-Filiale oder auf dem Marktplatz angezeigt werden.
- Sie müssen die Funktionalität implementieren, fehlerhafte Etiketten zu stornieren und wieder korrekt generieren zu lassen.
- Nicht kodierbare Sendungen führen zu zusätzlichen Gebühren pro Sendung (gemäß Verfahren 01). Dementsprechend ist das Verfahren intern zu klären (Label ohne kodierbare Adresse annehmen oder stornieren und nach Korrektur neu drucken) und ggf. Ihren Kunde/Händler zu informieren.
- Die Einlieferung von Sendungen an eine "Packstation", "Postfiliale Direkt" und oder einen "Parcelshop" muss umgesetzt werden. Für diese Dienste wird eine 6-10-stellige Postnummer ("PostNummer") vergeben. Für den Empfänger sind bestimmte Adresstypen definiert worden: "Packstation", "Postfiliale" und "ParcetShop".
- Wenn Sie als Anbieter einer Drittsoftware oder Marktplatzbetreiber auftreten, ist eine Dokumentation der Schnittstelle zwingend erforderlich.
Bitte beachten Sie die folgenden zusätzlichen Hinweise und Empfehlungen:
- Für ein DHL Produkt können mehrere Abrechnungsnummern oder Teilnahmen existieren, z.B. zur Unterscheidung von Standorten, Kunden oder Aktionen oder zur Verwendung von "GoGreen". Wenn Sie als Anbieter einer Drittsoftware oder Marktplatzbetreiber agieren, empfehlen wir Ihnen, mehrere Felder für die Eingabe von Abrechnungsnummern oder Teilnahmen vorzusehen.
- Wenn Sie als Anbieter einer Drittsoftware oder Marktplatzbetreiber agieren und nicht alle DHL Produkte und Services über die DHL Paket DE Versenden API integrieren möchten, empfehlen wir Ihnen, zusätzlich einen Shortcut-Link zum DHL Geschäftskundenportal zu integrieren. Ihre Kunden/Händler können dann Versanddokumente für nicht integrierte Produkte direkt erstellen oder in Ihrer Anwendung erstellte Versanddokumente bearbeiten.
- Jedes Paket ist genau eine (1) Sendung. Bitte berücksichtigen Sie dies beim Versand mehrerer Artikel in mehreren Paketen an einen (1) Empfänger.
2.1.11 update
Einführung der neuen GoGreen Logos auf den Versandlabeln.
2.1.11
Einführung der Authentifizierungs Methode OAuth2 parallel zur aktuellen Basic Auth. Spätere API Versionen werden kein Basic Auth mehr unterstützen.
2.1.10
- Die Webservice Response wird um das Attribut „status“ erweitert. Es enthält denselben Wert wie das bereits vorhandene Attribut „statusCode“. Mit dieser abwärtskompatiblen Erweiterung wird eine Konformität zu RFC 7807 sichergestellt.
- Die Attribute „name2“ und „name3“ werden bei Beauftragung eines Retourenlabels jetzt auf das Label angedruckt.
- Sofern eine Absender Telefonnummer bei Beauftragung einer zollpflichtigen internationalen Sendung übermittelt wird, so wird diese auf dem CN23 Formular angedruckt.
- Bug Fix für GET /orders Aufruf bei internationalen Sendungen mit dem Service Nachnahme.
- Bei der Nutzung von Packstationen konnte die zu scannende Sendungsnummer häufig auf dem Paketlabel nicht identifiziert werden, weil die Bezeichnung der Barcodes nicht eindeutig war. Deshalb werden die Barcodes nun auch mit "Sendungsnummer" bzw. "Shipment Identifier / numéro de l'envoi" beschriftet, anstatt der alten Bezeichnung "Identcode/License Plate".
- Auf allen innerdeutschen Paketen sowie bei DHL Paket International werden Gewichte über 10kg bzw. über 20kg gesondert gekennzeichnet. Die neuen Gewichtssymbole werden oberhalb des Gewichts auf den Labeln angedruckt.
2.1.9
Der Routing Code der Empfängeradresse wird in der Webservice Response mit ausgegeben.
Bug Fix für Abruf der Label internationaler Sendungen über GET /orders.
Bug Fix für Abruf der Tagesabschlusslisten per URL über GET /manifests.
2.1.8
Die Movement Reference Number (MRN) kann bei Beauftragung einer internationalen Sendung nun als optionaler Parameter im Request übergeben werden.
In der Zollinhaltserklärung können nun bis zu 99 Warenpositionen im Request übergeben werden.
Korrektur der Enum-Werte des Attributes „printFormat“ in den Objekte „Document“ und „GetManifestData“.
2.1.7
Der Service Versandbestätigung wurde aus dem Bereich „Value Added Services“ (VAS) entfernt. Bitte verwenden Sie stattdessen die DHL Paketankündigung.
Die Dokumentation des „BadRequest“ Response Objekts wurde korrigiert
2.1.6
Der Service Versandbestätigung ist veraltet und wird nicht mehr unterstützt. Bitte verwenden Sie stattdessen die DHL Paketankündigung.
2.1.5
In den neuen Feldern „shipperCustomsRef“ und „consigneeCustomsRef“ können jetzt die Kennnummern des Versenders und Empfängers für Zollzwecke übergeben werden.
Die Felder „permitNo“ und „attestionNo“ werden nun korrekt auf den Zolldokumenten angedruckt.
2.1.4
- Korrektur des "Shipper" Modells für erfolgreiche JSON Schema Validierung bei Verwendung einer Absenderreferenz
2.1.3
- Korrektur der Dokumentation für die Schema Objekte: ServiceInformation, POBox, shipDate, dateOfBirth, preferredDay
- Korrektur des Status Codes für den Endpunkt /manifests: Falls keine Sendungen für den Tagesabschluss vorhanden sind, wird Fehlercode 200 zurückgeliefert.
- Korrektur bei Buchung des Services DHL Retoure: Die Sendungsnummer der Retourensendung wird jetzt in der Response im Feld „returnShipmentNo“ ausgegeben.
2.1.2
- Die erfolgreiche Zustellung von DHL Paketen an der Haustür wird i. d. R. durch die Unterschrift unserer DHL Zustellkraft dokumentiert. Wenn Sie darüber hinaus die Unterschrift der Empfangsperson benötigen, können Sie ab dem 01.07.2023 den Service Empfängerunterschrift sendungsindividuell beauftragen. Der Service steht bereits jetzt in der Sandbox zur Verfügung.
2.1.1
- Korrektur der Dokumentation für die Schema Objekte: servers, b64 Property des Document Objekts und Property hsCode minlength
- Beauftragung von Versandlabel über eine Absenderreferenz jetzt wieder möglich
2.1.0
- Ein Tagesabschluss kann jetzt für alle Sendungen einer bestimmten Abrechnungsnummer durchgeführt werden
(Operation POST /manifest). - Bei dem Abruf eines Tagesabschluss werden jetzt die zu den Abrechnungsnummern und Sendungsnummern zugehörigen Blattnummern in der Response zurückgegeben (Operation GET /manifest).
2.0.2
Initiales Release
Ursprung ist die original Geschäftskundenversand API (SOAP) inklusive der folgenden Operationen (SOAP API Aufrufe):
- getVersion: Mit dieser Operation kann die letzte im Web verfügbare Version abgefragt werden.
- validateShipment: Mit dieser Operation können die Daten für eine Sendung validiert werden, bevor ein Sendungsetikett und eine Kontrollnummer erstellt werden.
- createShipmentOrder: Mit dieser Operation werden Sendungen für DHL Paket inklusive der zugehörigen Versanddokumente angelegt.
- updateShipmentOrder: Mit dieser Operation werden die Versanddokumente für zuvor erstellte Sendungen aktualisiert. Die Aktualisierung führt automatisch eine Stornierung und Neuanlage einer Sendung durch.
- deleteShipmentOrder: Diese Operation storniert zuvor angelegte Sendungen.
- getLabel: Diese Operation gibt das Versandetikett für zuvor erstellte Sendungen zurück.
- getExportDoc: Mit dieser Operation werden Exportdokumente für zuvor erstellte Sendungen zurückgegeben.
- doManifest: Mit dieser Operation kann ein Tagesabschluss für bis zu 30 zuvor erstellte Sendungen durchgeführt werden.
- getManifest: Mit dieser Operation sind Tagesabschlussberichte für einen bestimmten Tag oder Zeitraum verfügbar.
Diese API bietet äquivalente REST-Endpunkte und versucht, die ursprüngliche Funktionalität genau zu replizieren.
Benennung der API-Ressourcen
Die API folgt den URL-Namenskonventionen nach folgendem Schema: https://api${environment}.dhl.com/${business_unit}/${domain_name}/${version_id}/${resource}/
Für diese API bedeutet dies:
https://api-eu.dhl.com/parcel/de/shipping/v2/orders/ und
https://api-eu.dhl.com/parcel/de/shipping/v2/manifests/
Endpunkte
Die neuen API-Endpunkte für die oben genannten alten SOAP-API-Aufrufe sind:
//orders/manifests/labels
Bitte sehen Sie sich das Mapping genau an:
| Resource | Operation | Mapping auf | Kommentar |
|---|---|---|---|
| / | GET | getVersion | API version und Prüfung |
| /orders | GET | getLabel and getExportDoc | Dokumente abrufen (Etikett, Rücksendeetikett und Zolldokumente) |
| - | POST | createShipmentOrder | Validierung oder Erstellung von neuen Sendungen. Dies ist die Hauptfunktion der Versand-API. |
| - | DELETE | deleteShipmentOrder | Löschen einer bestehenden Sendung. |
| /manifests | POST | doManifest | Tagesabschluss für ausgewählte Sendungen. |
| - | GET | getManifest | Laden des Manifest Dojuments.. |
| /labels | GET | downloadLabel | Abrufen der PDFEtiketten von einer öffentlichen URL. Die URL ist Teil der Antwort auf den Aufruf von POST /orders. |