Bitte übergeben Sie Ihren Post & DHL Geschäftskundenportal Benutzernamen ausschließlich kleingeschrieben.

Für die Nutzung der DHL API Retoure benötigen Sie zunächst die CIG-Authentifizierung Ihrer Applikation im Testmodus. Nähere Details finden Sie unter https://entwickler.dhl.de/group/ep/authentifizierung

Sandbox

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

• Username: "2222222222_customer"
• Password: "uBQbZ62!ZiBiVVbhc"
   
• aus den oben genannten Zugangsdaten (base64-codiert), ergibt sich das nachfolgende
  DPDHL-User-Authentication-Token:  MjIyMjIyMjIyMl9jdXN0b21lcjp1QlFiWjYyIVppQmlWVmJoYw==

Eine detaillierte Beschreibung der Retoure API finden Sie in der "Open API Specification".
Die "Open API Specification" können Sie auf dieser Seite herunterladen: https://entwickler.dhl.de/group/ep/wsapis/retouren

Zum Testen steht Ihnen zudem das swaggerUI-Projekt unter dem Menüpunkt "Operationen" zur Verfügung: https://entwickler.dhl.de/group/ep/wsapis/retouren/operationen

Dort haben Sie die Möglichkeit, sich einen beispielhaften "Curl-Aufruf" zu generieren, eine Response wird an dieser Stelle jedoch nicht erzeugt.

Zur Erstellung von Retourenlabeln können Sie folgende Retourenempfänger ("receiverId") verwenden:

Produktion

Für die Nutzung der Retoure API 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 Post & DHL Geschäftskundenportal"
  (Benutzer muss für Retoure berechtigt sein!)
• Password:  "Passwort des oben genannten Benutzers"
   
• aus den oben genannten Zugangsdaten (base64-codiert), ergibt sich das
  DPDHL-User-Authentication-Token

Bitte bedenken Sie bei der Auswahl des jeweiligen Benutzers auch Dauer der Gültigkeit von Passwörtern:

• 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 Post & DHL Geschäftskundenportal nicht möglich.

Wichtig: Die Zugangsdaten für den Zugriff auf die Produktion vom Post & DHL Geschäftskundenportal erhalten DHL Vertragskunden über den Vertrieb DHL Paket.

Die jeweiligen Retourenempfängernamen (receiverID), finden Sie aufgelistet im Post & DHL Geschäftskundenportal (https://geschaeftskunden.dhl.de/) unter dem
Menüpunkt "Retoure" > "Einstellungen" unter dem Eintrag "Receiver ID".

Bedenken Sie bitte zudem auch, dass nach einer Migration vom bisherigen Retourenportal der "Admin-Benutzer" dort dauerhaft deaktiviert ist und sämtliche administrativen Einstellungen ausschließlich über das Post & DHL Geschäftskundenportal (https://geschaeftskunden.dhl.de/) vorzunehmen sind (bspw. Retourenempfänger bearbeiten, Benutzer anlegen/löschen etc.).

Testsuite Retouren API

Testsuite

Zur Anbindung der Retouren API 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/

Nach der Installation von Postman sind folgende Schritte erforderlich:

1. Starten Sie Postman
2. Importieren Sie die zuvor heruntergeladene Testsuite (*.json) in das Programm Postman (Import):

Hier können sie die Datei entweder per Drag-and-Drop hinzufügen, oder direkt auswählen:

Die Testsuite befindet sich links unter dem Reiter "Collections".

3. Klicken Sie auf die importierte Testsuite und erweitern Sie die Menüstruktur durch Klicken auf das Symbol
    "view more actions", anschließend wöhlen Sie den Punkt "Edit" aus:

Der Editor öffnet sich:

4. Wählen Sie die Registerkarte "Authorization" aus und hinterlgen Sie unter "Type" die Auswahl "Bascic Auth".
    Unter "Username" und "Password" hinterlegen Sie Ihre "Entwickler-ID" und "Ihr aktuelles Passwort vom Entwicklerportal für Post & Paket Deutschland".

Sämtliche Requests sind nun funktionsfähig.
Im Folgenden wird der Aufbau des Requests erklärt.

5. Unter dem Reiter "Body" sehen Sie den Inhalt des Requests.
    Sollte diese Ansicht nicht automatisiert angezeigt werdern, wählen Sie in den Drop-Down-Menüs "raw" und "JSON" aus.

In diesem Reiter sind sämtliche Objekte des Requests ersichtlich, die befüllt werden können.
Pflichtfelder wurden bereits mit Beispieldaten befüllt.

Mehr Informationen über die einzelnen Objekte finden Sie unter folgendem Link:
https://entwickler.dhl.de/group/ep/wsapis/retouren/operationen

Alternativ können Sie die Spezifikationen auch in der *.yaml-Datei einsehen:

https://entwickler.dhl.de/group/ep/wsapis/retouren

Sie können die einzelnen Objekte mit Ihren Testdaten befüllen.
 

6. Klicken Sie auf "Send", um eine Antwort mit dem base64-codierten Retourenlabel zu erhalten.
    Zusätzlich werden der HTTP-Statuscode, die benötigte Antwortzeit und die Größe der Antwort angezeigt:

7. Der Reiter "Test Results" bei der Antwort auf den Request, zeigt, ob der Request erfolgreich war:

8. Um den gesamten Request inklusive Header in Textform anzusehen, klicken Sie auf "Code":

In dem Fenster sind sämtliche Daten (Header+Body) ersichtlich:

Hinweis:

Bitte achten Sie im weiteren Verlauf darauf, dass Zugangsdaten immer base64-codiert übergeben werden müssen.

Die Testsuite arbeitet in der Sandbox ausschließlich mit den von uns bereitgestellten receiverID's und Zugangsdaten.
Weitere Details hierzu finden sie unter folgendem Link:

https://entwickler.dhl.de/group/ep/wsapis/retouren/authentifizierung

Fehlertabelle:

Zur Freigabe der API durch DHL sind folgende Funktionalitäten verpflichtend umzusetzen:

• receiverID variabel
• Benutzername des Post & DHL Geschäftskundenportal variabel
• Passwort variabel
• Umsetzung der Zoll-begleitenden Unterlagen (bei nicht EU Staaten)

Hinweis:

Bei Shopsoftwareanbietern und Marktplätzen müssen die oben genannten Gegebenheiten für jeden teilnehmenden Versandhändler konfigurierbar sein und es ist eine entsprechende Dokumentation für den Endkunden zu erstellen.