Ü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=33333333335301
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

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.

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

Bitte beachten Sie den Abschnitt "Authentifizierung".

Retouren Auftrag

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

Was muss ich beachten, wenn ich meinen Kunden einen Link zur Erstellung von Retourenlabeln zur Verfügung stellen möchte?

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: 

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:

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

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

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

Für welche Absenderländer muss ein Gewicht angegeben werden?

Für die Absenderländer Dänemark, Portugal und Schweden muss im Webservice Request eine Gewichtsangabe pflichtmäßig erfolgen. Für die Länder Großbritannien und Schweiz muss das Gewicht im Abschnitt der Zollinformationen angegeben werden.

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/

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.

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 

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.