DHL Paket DE Retoure (Post & Paket Deutschland)
v 1.0.5
Division: Post & Parcel Germany, Parcel

Am besten geeignet für

  • Erstellung von Rücksendeetiketten zur Verwendung durch Endkunden
  • Absenderländer für Retouren: bgr, dnk, deu, est, fin, fra, grc, gbr, irl, ita, hrv, lva, ltu, lux, mlt, nld, aut, pol, prt, rou, swe, che, svk, svn, esp, cze, hun, cyp
  • Ermittlung der Empfängerkonfiguration für Ihren Benutzer

    

Region: Deutschland
Used for: Versand
Übersicht

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

Umfang

Mit der DHL Paket DE Retoure API können Sie die folgenden Produkte von DHL Paket nutzen:

  • DHL Retoure Online
  • DHL Retoure International

Ausnahmen

Die folgenden DHL Paket Produkte und Services können nicht über die DHL Paket DE Retoure API genutzt werden:

  • DHL Paket mit beiliegendem Rücksendeaufkleber
  • DHL Paket International
  • DHL Paket Europaket
  • DHL Connect

Voraussetzungen

Um Retourenetiketten über die DHL Paket DE Retoure API zu erstellen, müssen folgende Voraussetzungen erfüllt sein:

  • Ein gültiger Geschäftskundenvertrag mit der DHL Paket GmbH für die Produkte DHL Retoure Online und/oder DHL Retoure International
  • Zugang zum Post & DHL Geschäftskundenportal mit der Berechtigung für die Funktion "Retoure"

Benutzung der API

Die DHL Paket DE Retoure API ermöglicht die Bestellung von Retourenetiketten für geplante Rücksendungen von Ihren Kunden.

Sie ermöglicht es damit Geschäftskunden von DHL, den Labelerstellungsprozess für Retourenlabels nahtlos in ihre eigenen Workflows zu implementieren, zum Beispiel integriert in die eigene Website.

Über die DHL Paket DE Retoure API erhalten Sie individuelle Retourenlabel, die Sie Ihren Kunden zur Verfügung stellen 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 Returns 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.

Alternativ können Sie Basic Auth (Username: "2222222222_customer", Password: "uBQbZ62!ZiBiVVbhc") zur Authentifizierung nutzen und zusätzlich den api-key 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 Parcel DE Returns 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 Returns 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/returns/v1/ 

Fragen Sie nun die Retourenempfängeradressen "receiverIds" ab (mit Access Token):

curl -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json"  https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1/locations

Eine genaue Beschreibung der Retoure API finden Sie in der "Open API Specification".
Den Download der "Open API Specification" finden Sie hier.

Bitte verwenden Sie die folgenden Empfängernamen (Retourenempfänger / "receiverId") für Testanfragen:

Absendeland Retourenempfängername (receiverID)
Belgien bel
Bulgarien bgr
Dänemark dnk
Deutschland deu
Estland est
Finnland fin
Frankreich fra
Griechenland grc
Großbritannien und Nordirland gbr
Irland irl
Italien ita
Kroatien hrv
Lettland lva
Litauen ltu
Luxemburg lux
Malta mlt
Niederlande nld
Österreich aut
Polen pol
Portugal prt
Rumänien rou
Schweden swe
Schweiz che
Slowakei svk
Slowenien svn
Spanien esp
Tschechien cze
Ungarn hun
Zypern cyp

Production

Um die "DHL Parcel DE Returns 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.

Um die Retourenempfänger zu ermitteln, verwenden Sie bitte die Funktion /locations des API-Aufrufs. Die Antwort enthält alle "ReveiverIDs", die Sie zur Erstellung eines Retourenlabels verwenden können.

Alternativ: Die jeweiligen Namen der Retourenempfänger (ReceiverID) finden Sie im Post & DHL Geschäftskundenportal  (https://geschaeftskunden.dhl.de/) unter dem Menüpunkt "Retouren" > "Einstellungen" unter dem Eintrag "EmpfängerID".

 

Umgebungen

Die adressierbaren API-Basis-URL/URI-Umgebungen sind:

Umgebung Description Comment
https://api-eu.dhl.com/parcel/de/shipping/returns/v1/ Produktions- umgebung Die produktive Verwendung wird nach erfolgreicher Nutzung der Sandbox durch DHL freigeschaltet.
https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1/ Sandbox- (Test.-) umgebung Die Nutzung der Sandbox ist auch möglich, wenn Sie noch kein DHL Paket Geschäftskunde sind.

Fehlercodes

Fehlercode Beschreibung Fehlersuche/Aktion
400 Falsche Anfrage Bitte überprüfen Sie die Syntax des Aufrufs.
401 Authentifizierung fehlgeschlagen Bitte überprüfen Sie die Zugangsdaten.
403 Autorisierung fehlgeschlagen Bitte überprüfen Sie Ihre Berechtigungen.
500 Interner Fehler Es ist ein unerwarteter interner Fehler aufgetreten.
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

  • Aufträge erhalten
  • Empfänger erhalten

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.

Aufträge erhalten

Einfacher Request eines deutschen Retourenlabels (PDF-Label und QR-Code)

POST /parcel/de/shipping/returns/v1/orders?labelType=BOTH
Host: https://api-sandbox.dhl.com
Content-Type: application/json

{
    "receiverId": "deu",
    "shipper": {
        "name1": "Max Mustermann",
        "addressStreet": "Kurfürstendamm",
        "addressHouse": "1",
        "postalCode": "10719",
        "city": "Berlin"
    }
}

Einfacher Request eines deutschen Retourenlabels (nur PDF-Label)

POST /parcel/de/shipping/returns/v1/orders?labelType=SHIPMENT_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json

{
    "receiverId": "deu",
    "shipper": {
        "name1": "Max Mustermann",
        "addressStreet": "Kurfürstendamm",
        "addressHouse": "1",
        "postalCode": "10719",
        "city": "Berlin"
    }
}

Einfacher Request eines deutschen Retourenlabels (nur QR-Code)

POST /parcel/de/shipping/returns/v1/orders?labelType=QR_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json

{
    "receiverId": "deu",
    "shipper": {
        "name1": "Max Mustermann",
        "addressStreet": "Kurfürstendamm",
        "addressHouse": "1",
        "postalCode": "10719",
        "city": "Berlin"
    }
}

Bitte übermitteln Sie Ihrem Kunden zusätzlich zum QR-Code auch die sog. Retouren-ID in Textform (RET-Nummer). Sie dient der manuellen Eingabe für den Fall, dass ein QR-Code einmal nicht scann- bzw. lesbar sein sollte und muss daher in einem Format bereitgestellt werden, welches ein Kopieren ermöglicht (kein JPEG, PNG etc.). Die Retouren-ID setzt sich aus der Sendungsnummer und dem Präfix „RET“, der der Sendungsnummer unmittelbar vorangestellt wird, zusammen (z. B. RET129900013151).

Ausführlicher Request für ein deutsches Retourenlabel

POST /parcel/de/shipping/returns/v1/orders?labelType=BOTH
Host: https://api-sandbox.dhl.com
Content-Type: application/json

{
    "receiverId": "deu",
    "shipper": {
        "name1": "Max Mustermann",
        "name2": "Zentraler Einkauf",
        "name3": "Beispiel Firma GmbH",
        "addressStreet": "Kurfürstendamm",
        "addressHouse": "1",
        "postalCode": "10719",
        "city": "Berlin",
        "state": "Nordrhein-Westfalen",
        "email": "max.mustermann@mail.com",
        "phone": "+49 170 123456789"
    },
    "customerReference": "Order Nr. 1234/2022",
    "shipmentReference": "Account AB34-88",
    "itemWeight": {
        "uom": "kg",
        "value": 1.5
    },
    "itemValue": {
        "currency": "EUR",
        "value": 99.99
    }
}

Anforderung eines internationalen Retourenlabels ohne Zollerklärung (Absenderland innerhalb der EU)

POST /parcel/de/shipping/returns/v1/orders?labelType=SHIPMENT_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json

{
  "receiverId": "fra",
  "shipper": {
    "name1": "Jean Doe",
    "addressStreet": "Rue de Thorigny",
    "addressHouse": "5",
    "city": "Paris",
    "postalCode": "75003"
  }
}

Anforderung eines internationalen Retourenlabels mit Zollanmeldung (nur erforderlich, wenn das Absenderland außerhalb der EU liegt (z.B. Schweiz))

POST /parcel/de/shipping/returns/v1/orders?labelType=SHIPMENT_LABEL
Host: https://api-sandbox.dhl.com
Content-Type: application/json

{
  "receiverId": "che",
  "shipper": {
    "name1": "Hans Meier",
    "addressStreet": "Heimpl.",
    "addressHouse": "1/5",
    "postalCode": "8001",
    "city": "Zürich"
  },
  "customsDetails": {
    "items": [
      {
        "itemDescription": "T-Shirt (red, size S)",
        "packagedQuantity": 2,
        "itemWeight": {
          "uom": "kg",
          "value": 1
        },
        "itemValue": {
          "currency": "EUR",
          "value": 19.98
        }
      },
      {
        "itemDescription": "T-Shirt (blue, size M)",
        "packagedQuantity": 1,
        "itemWeight": {
          "uom": "kg",
          "value": 0.5
        },
        "itemValue": {
          "currency": "EUR",
          "value": 19.99
        }
      }
    ]
  }
}

Empfänger erhalten

Abrufen aller Retourenempfänger

GET /parcel/de/shipping/returns/v1/locations
Host: https://api-sandbox.dhl.com

Abrufen eines bestimmten Retourenempfängers anhand seiner Empfänger-ID

GET /parcel/de/shipping/returns/v1/locations?receiverId=swe
Host: https://api-sandbox.dhl.com

Abrufen von Retourenempfängern für ein bestimmtes Absenderland

GET /parcel/de/shipping/returns/v1/locations?countryCode=deu
Host: https://api-sandbox.dhl.com

Abrufen von Retourenempfängern für eine bestimmte Rechnungsnummer

GET /parcel/de/shipping/returns/v1/locations?billingNumber=22222222225301
Host: https://api-sandbox.dhl.com

Abrufen von Retourenempfängern für eine bestimmte Postleitzahl

GET /parcel/de/shipping/returns/v1/locations?postalCode=53113&countryCode=deu
Host: https://api-sandbox.dhl.com
FAQ

Allgemeine Informationen

Ich habe die alte Paket Retouren API von dem Entwicklerportal verwendet, was hat sich durch die neue DHL Paket DE Retoure API geändert?

Wenn Sie die bisherige Paket Retouren API eingesetzt haben, beachten Sie bitte die Änderungen unter  Release Notes.

Authentifizierung

Was kann ich tun, wenn ich mein Passwort oder meinen Benutzernamen vergessen habe?

Bitte nutzen Sie die Passwort-Reset-Funktion, um unter https://geschaeftskunden.dhl.de/ ein neues Passwort oder einen neuen Benutzernamen zu vergeben.

Passwort_vergessen_de

Welche Art von Authentifizierung ist für die Nutzung der API Returns erforderlich?

Bitte beachten Sie den Abschnitt "Authentifizierung".

Retouren Auftrag

Wie kann ich das Absenderadressformat für ein bestimmtes Herkunftsland ermitteln?

Auf den Webseiten des Weltpostvereins ("UPU") können Sie die gültigen Adressmodelle einsehen: http://www.upu.int

Was ist der Unterschied zwischen Kundenreferenz und Sendungsreferenz?

Die Kundenreferenz ist sichtbar auf dem Retourenlabel aufgedruckt, die Sendungsreferenz wird nur in der Übersicht der erstellten Retourenlabel im Post & DHL Geschäftskundenportal angezeigt.

Welches Format hat das Retourenlabel?

Das Retourenlabel wird als base64 kodierter String (PDF-Datei) in den Response Body eingebunden (Eigenschaft "label.b64").
Bei Retouren mit einer Absenderadresse in Deutschland ist zusätzlich ein mobiles Retourenlabel möglich, das als QR-Code bereitgestellt wird. Das Label kann in den Annahmestellen von Deutsche Post DHL ausgedruckt werden.Der QR-Code wird als base64-kodierte Zeichenkette (PNG-Datei) im Response Body (Eigenschaft "qrLabel.b64") bereitgestellt, wenn der Query-Parameter "labelType" entweder auf "QR_LABEL" oder "BOTH" gesetzt ist.

Bitte übermitteln Sie Ihrem Kunden zusätzlich zum QR-Code auch die sog. Retouren-ID in Textform (RET-Nummer). Sie dient der manuellen Eingabe für den Fall, dass ein QR-Code einmal nicht scann- bzw. lesbar sein sollte und muss daher in einem Format bereitgestellt werden, welches ein Kopieren ermöglicht (kein JPEG, PNG etc.). Die Retouren-ID setzt sich aus der Sendungsnummer und dem Präfix „RET“, der der Sendungsnummer unmittelbar vorangestellt wird, zusammen (z. B. RET129900013151).

Bitte beachten Sie bei der Veröffentlichung auf Ihrer eigenen Homepage, dass diese Website mit dem Link zur Erstellung von Retourenlabeln nicht über Suchmaschinen auffindbar sein darf.

Mit welchen Parametern kann ich das Webformular für Retourenaufträge für meine Kunden vorausfüllen?

Die folgenden Parameter können über "&[parameter]" und "=[specification]" an die Retouren-URL nach dem HASH-Wert angehängt werden: 

ShipmentReference Shipment reference, wird in der Retourenübersicht angezeigt
CustomerReference Customer reference, wird auf dem Retourenlabel angezeigt
senderName1 Name1 des Absensers
senderName2 Name2 des Absensers
senderStreet Straße des Absensers
senderStreetNumber Hausnummer des Absensers
senderCity Stadt des Absensers
senderZip PLZ des Absensers
ADDR_SEND_EMAIL E-mail Adresse, an die das Rücksendeetikett gesendet werden soll

Beispiel:

https://www.dhl.de/retoure/gw/rpcustomerweb/OrderEntry.action?hash=xxxx

&ShipmentReference=1234&CustomerReference=5678&senderName1=Absender1&senderName2=Absender2&senderStreet=Straße1&senderStreetNumber=HNR1&senderCity=Ort1&senderZip=53113& ADDR_SEND_EMAIL=name@domain.de

Wie kann ich eine bestellte Retoure stornieren?

Eine Stornierung von bestellten Retourenlabeln ist nicht notwendig, da nur Retourenpakete, die vom Versender aufgegeben wurden, berechnet werden. Die Erstellung eines Retourenlabels ist kostenlos.

Retouren-Empfänger

Wie ermittle ich die Namen der Retourenempfänger (Eigenschaft "receiverId")?

Sie können die Liste aller Retourenempfänger mit der Methode GET locations abrufen. Bitte beachten Sie unsere Beispielanfrage
Alternativ können Sie sich auch im Post & DHL Geschäftskundenportal anmelden. Im Bereich "Einstellungen" der Funktion "Retouren" sind alle Retourenempfänger (= "receiverId") aufgelistet. Eine CSV-Liste mit allen Retourenempfängern können Sie unter dem Link "URL & Receiver Ids" herunterladen.

Schritt 1:

Einstellungen_GKP_Retoure_1

Schritt 2:

Einstellungen_GKP_Retoure_2

 

Wie kann ich die Empfangsadresse der Retourenetiketten ändern?

Die Empfangsadresse wird im Retourenempfänger konfiguriert. Für jedes Herkunftsland und jede Empfangsadresse ist ein eigener Retourenempfänger erforderlich.
Die Retourenempfänger können über das Menü "Retouren" im Post & DHL Geschäftskundenportal unter "Einstellungen" bearbeitet werden.

Wie kann ich einen zusätzlichen Retourenempfänger anlegen?

Neue Retourenempfänger können nur durch den DHL Vertrieb angelegt werden. Bitte wenden Sie sich an Ihren Ansprechpartner im Vertrieb von Deutsche Post DHL. Ihren Ansprechpartner im Vertrieb finden Sie nach dem Login unten auf der Startseite unter https://geschaeftskunden.dhl.de/.

Technischer Support des Geschäftskundenportals

0228 - 76367679

(Mo-Fr von 8 - 18 Uhr)

Internationale Retouren

Warum unterscheiden sich die internationalen DHL Retourenlabels von Land zu Land?

Um Endkunden außerhalb Deutschlands das beste Annahme-Netzwerk für ihre Retouren anbieten zu können, arbeitet DHL mit verschiedenen Partnern zusammen.

Nicht alle Herkunftsländer sind für meine Retoure verfügbar. Was kann ich tun?

DHL Retoure International ist nur für Herkunftsländer in Europa verfügbar. Wenn Sie ein europäisches Land vermissen, wenden Sie sich bitte an Ihren Ansprechpartner im Vertrieb von Deutsche Post DHL. Ihren Ansprechpartner im Vertrieb finden Sie nach dem Login unten auf der Startseite unter https://geschaeftskunden.dhl.de/.

Allgemeine Produkt-Informationen

Was kostet die Erstellung eines Retourenlabels?

Es werden nur Retourenpakete berechnet, die tatsächlich vom Versender aufgegeben wurden. Die Erstellung eines Retourenlabels ist kostenlos.

Warum können mit der DHL Paket DE Retoure API keine Versandetiketten erstellt werden?

Mit der DHL Paket DE Retoure API können nur Retourenetiketten erstellt werden. Bitte verwenden Sie die DHL Paket DE Versenden API, um Versandetiketten zu erstellen.

Was kann ich tun, wenn ich Fragen zum Post & DHL Geschäftskundenportal oder zur Funktion "Retouren" habe?

Bitte klicken Sie auf den Bereich "Hilfe & Information" des Post & DHL Geschäftskundenportals unter: https://geschaeftskunden.dhl.de/

Einstellungen_GKP_Retoure_3

 

Wo finde ich weitere Informationen über die DHL Retourenprodukte für Geschäftskunden?

Unter https://www.dhl.de/de/geschaeftskunden.html finden Sie weitere Informationen über die DHL-Retourenprodukte für Geschäftskunden.

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 Retoure API"

Um sich für die Nutzung der DHL Paket DE Retoure 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 bei 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 Retoure 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 Retoure 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 (z.B. Shopsoftware), 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 jeweilgen Absender der Sendungen) auf die geltenden Versandbedingungen hinzuweisen.

Sie dürfen die Services und/oder Daten, die Sie über die DHL Paket DE Retoure API erhalten, nur für die rechtmäßigen vertraglichen Zwecke und nur im Zusammenhang mit Ihren bzw. den DHL-Sendungen der Versandkunden nutzen.

Für die Nutzung und/oder den Zugriff auf die DHL Paket DE Retoure-API gelten die nachfolgenden Voraussetzungen und/oder Einschränkungen. Um die API durch DHL freizugeben, müssen die folgenden Funktionen implementiert werden:

  • receiverID ist editierbar
  • Benutzername (Post & DHL Geschäftskundenportal-Benutzer) ist editierbar
  • Passwort ist editierbar
  • Implementierung von Zolldokumenten (für Nicht-EU-Länder)
  • Der Name des Retourenabsenders ist im Feld „shipper.name1“ im Format „<Vorname> <Nachname>“ anzugeben.
  • Die Retouren-ID (RET-Nummer) muss in der Nähe des QR-Codes in einem gut lesbaren und kopierfähigen Format (kein JPEG, PNG, etc.) angezeigt werden. Die Rücksende-ID setzt sich aus der Sendungsnummer und dem Präfix "RET" zusammen, das der Sendungsnummer unmittelbar vorangeht (z. B. RET129900013151).

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.

1.05
03.May.2024

Einführung der Authentifizierungs Methode OAuth2 parallel zur aktuellen Basic Auth. Spätere API Versionen werden kein Basic Auth mehr unterstützen.

1.04
16.Jan.2024

1. Kundenreferenz 
Im Feld Kundenreferenz sind nun Sonderzeichen zulässig mit Ausnahme von Pipe (|) und Backslash (/). 
Die zulässigen Sonderzeichen im Text werden auch im Barcode kodiert. So wird die Vereinnahmung von Retouren für Sie durch Scan der Kundenreferenz auf dem Label erleichtert.
Die Anzahl der zulässigen Zeichen im Feld Kundenreferenz wurde der "Mobilen Retoure" angepasst und auf 30 Zeichen festgelegt. Sollte ein längerer Wert im Request übergeben werden, so wird dieser entsprechend gekürzt.

2. EORI-Nummer
Für jeden Retourenempfänger mit Absenderland Schweiz oder Vereinigtes Königreich wurde im April 2023 das Feld "Economic Operators Registration and Identification"(EORI) eingeführt. Die Angabe der EORI ist im Importprozess für Retouren immer anzugeben. Das Feld EORI-Nummer wird auf 22 Zeichen erweitert, damit Kunden mit Hauptsitz im Ausland ab sofort auch die deutsche Niederlassungsnummer an der ausländischen EORI Nummer ergänzen können.
Sie können die EORI Nummer für Ihre Retourenempfänger mit Absenderland Schweiz oder Vereinigtes Königreich eintragen, indem Sie im Post & DHL Geschäftskundenportal auf "Retoure -> Einstellungen" navigieren und dort die entsprechenden Retourenempfänger editieren. Klicken Sie dazu auf das "Stift"-Symbol. Für den Zugriff auf die Einstellungen müssen Sie berechtigt sein. Wenden Sie sich ggf. an den Ansprechpartner Ihrer Firma mit Administrationsrechten im Post & DHL Geschäftskundenportal.

1.03
31.Aug.2023

Korrektur der Liste der möglichen Währungen.

1.0.2
22.Feb.2023
  • Erweiterung der Zollinhaltserklärung (Commodity) um die beiden Felder:
    • countryOfOrigin: Land, in dem der zurückgesandte Artikel hergestellt wurde.
    • hsCode: Code aus dem harmonisierten System der Zolltarifnummern.
  • Genaue Definition der Fehlercodes in Responses auf Basis des JSONStatus
  • Erweiterung um weitere Beispiele

 

Hinweis:

Im April diesen Jahres wird es eine Änderung bei der Zollbearbeitung der DHL Retoure International aus dem Vereinigten Königreich geben. Die DHL Retoure International (API Retoure) wird ab dem 01. April 2023 um die Pflichtfelder des CN23 Dokumentes für das Vereinigte Königreich (analog zur Schweiz) erweitert. Somit ist zukünftig die Übermittlung der benötigten Zollinformationen für die Schweiz und für das Vereinigte Königreich verpflichtend.

Für Sie bedeutet dies konkret, dass bei Requests für das Absenderland „Vereinigtes Königreich“ die Informationen für das CN23 Dokument als Pflichtfeld über das Objekt „customsDetails“ mitgegeben werden müssen. Das in diesem Objekt enthaltene Array „items“ muss mindestens eine Warenposition enthalten. Wir weisen an dieser Stelle darauf hin, dass die beiden Felder „countryOfOrigin“ (DE: Ursprungsland) und „hsCode“ (DE: Warenzolltarifnummer) optionale Angaben sind, nach Möglichkeit aber übermittelt werden sollten, um den Import nach Deutschland zu vereinfachen und mögliche Laufzeitverzögerungen zu vermeiden. Diese beiden Felder werden zukünftig auch auf das CN23 Dokument angedruckt.

Bitte beachten Sie, dass aufgrund des Nordirland-Abkommens zwischen dem Vereinigten Königreich und der EU für die DHL Retoure International aus Nordirland keine Zollprozesse bzw. Zollanmeldungen nötig sind. Für nordirische Retouren, stets mit einer Absender-Postleitzahl beginnend mit „BT“, sind somit ab dem 01. April 2023 keine Daten zu übermitteln.

 

1.0.1
07.Sep.2022

Erstes Release der neu designten DHL Paket DE Retoure API mit folgenden Änderungen im Vergleich zur alten API:

Neue Services und Funktionen:

  • Verfügbare Retourenstandorte für Ihr Konto abrufen bei Eingabe /locations
  • Antwort auf internationale Rücksendungen einschließlich internationaler Versandnummer
     

Wesentliche Änderungen im Vergleich zur ursprünglichen Retouren-API auf entwickler.dhl.de:

Aufgrund eines API-Modernisierungs- und Harmonisierungsprogramms werden die DHL Post- und Paket-APIs einander immer ähnlicher. Wenn Sie die bisherige Paket-Retouren-API implementiert haben, beachten Sie bitte die folgenden Änderungen in der neuen Version:

  • Umbenennung der Business Objekte
Vorherige Paket Retoure API Neue DHL Paket Retoure API
senderAddress shipper
postCode postalCode
streetName addressStreet
houseNumber addressHouse
  • Umbenennung der Business Objekte für internationale Sendungen
Vorherige Paket Retoure API Neue DHL Paket Retoure API
positionDescription itemDescription
count packagedQuantity
weightInGrams object: "itemWeight": {"uom": "g","value": 1000}
currency

object: "itemValue": {"currency": "EUR","value": 100}

Please notice, that each item has to have a currency object and all CN23 items should have the same currency

Folgende Parameter sind nicht mehr notwendig:

originalShipmentNumber, originalOperator, acompanyingDocument, originalInvoiceNumber, originalInvoiceDate, comment, originCountry, articleReference, tarifNumber

  • Änderungen am Request

returnDocumentType ist nicht mehr im Request Body, verwenden Sie stattdessen den URL-Parameter:
?labelType=SHIPMENT_LABEL

Vorherige Paket Retoure API Neue DHL Paket Retoure API
Request-Body-Parameter:
"returnDocumentType""BOTH"
URL-Parameter : ?labelType=BOTH
  • Änderungen in Response
Vorherige Paket Retoure API Neue DHL Paket Retoure API
shipmentNumber shipmentNo
  Responses including internationalShipmentNo
  New object for response shipment status "sstatus" . {"title": "Created", "status": 201, ... }
labelData "label":{"b64": "..."}
qrLabelData "qrLabel":{"b64": "..."}