Zum Inhalt

DHL Ersteinrichtung

Schritt-für-Schritt-Anleitung zur initialen Einrichtung des DHL Paket DE Connectors.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:

  • [ ] DHL Geschäftskundenportal (GKP) — Aktiver Account unter geschaeftskunden.dhl.de
  • [ ] DHL Developer Portal — Registrierung unter developer.dhl.com mit einer App (API Key + Secret), der die benötigten APIs zugeordnet sind (siehe APIs im Developer Portal)
  • [ ] EKP-Nummer — 10-stellige DHL-Kundennummer aus Ihrem Vertrag
  • [ ] merchantCENTRAL Hub — Installiert und aktiv
  • [ ] Modul-Lizenz — Mindestens Demo-Lizenz für MCDHL

APIs im Developer Portal

Das DHL Developer Portal ist englischsprachig. Die Tabelle nennt die APIs deshalb genau so, wie sie in Ihrer App unter Select APIs in der Auswahlliste stehen. Ein API-Schlüssel gilt für alle APIs seiner App – einen zweiten Schlüssel brauchen Sie nicht.

API im Developer Portal Wofür Umgebungen Freischaltung
Parcel DE Shipping (Post & Parcel Germany) Versandetiketten, Storno, Tagesabschluss Sandbox und Produktion Produktion: manuell durch DHL
Parcel DE Returns (Post & Parcel Germany) Eigenständige Retourenetiketten (Retouren) Sandbox und Produktion Produktion: manuell durch DHL
Shipment Tracking – Unified Sendungsverfolgung (Sendungsverfolgung) nur Produktion sofort, Self-Service

Im Portal heißt die Sandbox Customer (Integration) Testing, die Produktion Production (Europe) bzw. Production (Global). Führen Sie Sandbox und Produktion in getrennten Apps, gehört Shipment Tracking – Unified in die Produktiv-App – eine Sandbox gibt es für diese API nicht.

Verwechslungsgefahr

Die Auswahlliste enthält weitere, ähnlich benannte APIs, die der Connector nicht verwendet – vor allem Parcel DE Tracking (Post & Parcel Germany). Für die Sendungsverfolgung ist ausschließlich Shipment Tracking – Unified gemeint; Sie finden sie alphabetisch unter „S“. Ebenfalls nicht benötigt werden etwa Parcel DE Pickup, Parcel DE Private Shipping oder Post DE Internetmarke. Eine zusätzlich aufgenommene API schadet nicht, bringt dem Connector aber nichts.

Kontingente gelten je API

Das Portal zeigt die Abrufkontingente je API und Umgebung an. Das großzügige Kontingent der Returns-API (Stand Oktober 2026 in der Produktion 500.000 Anfragen pro Tag) gilt nur für Retourenetiketten. Die Tracking-API beginnt mit 250 Abrufen pro Tag – mehr dazu unter Sendungsverfolgung.

Einrichtungsassistent

Der Einrichtungsassistent führt Sie in 6 Schritten durch die Konfiguration:

Schritt 1: Willkommen

Übersicht der Voraussetzungen. Prüfen Sie, ob alle Zugangsdaten bereit liegen.

Schritt 2: Authentifizierung

Wählen Sie die Authentifizierungsart und geben Sie die Zugangsdaten ein.

Einstellung Empfehlung
Auth Type OAuth2 (ROPC) — von DHL empfohlen und zukunftssicher
Sandbox-Modus Für den Ersttest aktivieren, später deaktivieren

OAuth2 (ROPC) — empfohlen:

  1. Klicken Sie auf API-Schlüssel → Eingabedialog → API Key aus developer.dhl.com eintragen
  2. Klicken Sie auf API-Secret → Eingabedialog → Client Secret aus developer.dhl.com eintragen

Basic Authentication (Legacy):

  1. Klicken Sie auf Benutzername (GKP) → GKP-Benutzername eintragen
  2. Klicken Sie auf Kennwort (GKP) → GKP-Passwort eintragen
  3. API-Schlüssel muss trotzdem separat eingetragen werden

OAuth2 vs. Basic Auth

DHL empfiehlt OAuth2 (ROPC) für neue Installationen. OAuth2 verwendet einen Token-basierten Mechanismus — der Token wird automatisch angefordert und bis zu seinem Ablauf gecacht. Basic Auth überträgt bei jedem Request Benutzername/Passwort.

Schritt 3: Verbindungstest

Klicken Sie Verbindung testen. Bei Erfolg erscheint eine grüne Bestätigung mit der API-Version.

Mögliche Fehler:

Fehler Ursache Lösung
HTTP 401 Ungültige Credentials API Key und Secret prüfen
HTTP 403 App nicht freigeschaltet App auf developer.dhl.com aktivieren
Timeout Netzwerkproblem Firewall/Proxy prüfen, api-eu.dhl.com muss erreichbar sein

Schritt 4: Absenderadresse

Die Absenderadresse erscheint auf allen DHL-Labels.

  • Klicken Sie Aus Mandant laden, um die Daten aus der BC-Firmeninformation zu übernehmen
  • Passen Sie die Felder bei Bedarf an (z.B. abweichende Versandadresse)
  • Pflichtfelder: Name, Straße, Hausnummer, PLZ, Ort, Ländercode

Absenderreferenz

Alternativ können Sie eine im DHL GKP hinterlegte Absenderreferenz verwenden. Aktivieren Sie dazu Use Shipper Reference und tragen Sie den Referenzcode ein.

Schritt 5: Standard-Einstellungen

Einstellung Empfehlung Beschreibung
Standardgewicht (g) 1000 Wird verwendet, wenn kein Gewicht am Paket angegeben ist
Label Print Format 910-300-600 DHL-Standard-Etikett (105×205mm)
Doc Format PDF Für Laserdrucker. ZPL2 für Thermodrucker.

Schritt 6: Abschluss

Zusammenfassung aller Einstellungen. Klicken Sie Finish um die Konfiguration abzuschließen und den Connector zu aktivieren.

Nach der Ersteinrichtung

Profile & Vertragspositionen einrichten

Nach dem Assistenten müssen Sie mindestens ein Profil mit Vertragspositionen anlegen:

  1. Öffnen Sie DHL Versandeinrichtung → Klick auf Standardprofil
  2. Erstellen Sie ein neues Profil (z.B. STANDARD_GRUPPENPROFIL)
  3. Fügen Sie Vertragspositionen hinzu:
  4. EKP: Ihre 10-stellige DHL-Kundennummer
  5. Produkt: V01PAK für Inland, V53WPAK für International
  6. Participation: 2-stelliger Code aus Ihrem DHL-Vertrag (üblicherweise 01)
  7. Zone: Domestic / EU / International
  8. Markieren Sie das Profil als Standard

→ Details: Profile & Abrechnung

Versandart in Business Central verknüpfen

Damit merchantCENTRAL den DHL-Connector bei Sendungen automatisch verwendet:

  1. Öffnen Sie Versandarten (Shipping Agents) in BC
  2. Wählen Sie Ihre DHL-Versandart
  3. Stellen Sie sicher, dass der Code mit dem Shipment Provider in merchantCENTRAL übereinstimmt

Testlabel erstellen

  1. Stellen Sie sicher, dass Sandbox-Modus aktiviert ist
  2. Erstellen Sie eine Testlieferung (Verkaufsauftrag → Buchen mit Liefern)
  3. Öffnen Sie die gebuchte Verkaufslieferung → Label erstellen
  4. Prüfen Sie das generierte Label

→ Details: Label erstellen

Nächste Schritte