DHL Paket API ins TMS integrieren: 7 Schritte

Die alte SOAP-Schnittstelle GKV v3 für den DHL-Versand ist zum 31. Mai 2026 abgeschaltet worden. Wer bis dahin nicht auf die REST-basierte „DHL Paket DE Versenden V2 API" umgestellt hatte, konnte ab diesem Stichtag keine Sendungen mehr beauftragen. DHL hat angekündigt, die technisch veraltete SOAP-API GKV v3 zum 31. Mai 2026 abzuschalten und durch die moderne DHL Paket DE Versenden V2 REST-API zu ersetzen. Dieser Beitrag zeigt, wie Sie die DHL Paket API ins TMS integrieren, welche Schritte dafür nötig sind und wo die Anbindung in der Praxis am häufigsten scheitert.

Warum nach dem 31. Mai 2026 kein Weg an der REST-API vorbeiführt

Wer noch produktiv auf GKV v3 oder der alten Retouren-Schnittstelle über cig.dhl.de läuft, hat kein funktionierendes System mehr. Die alte Version der Returns API unter cig.dhl.de wird seit dem 31. Mai 2026 nicht mehr unterstützt. Betroffen sind nicht nur Online-Händler mit Shopsystem, sondern auch Verlader mit eigenem TMS oder ERP-Anbindung, die DHL-Sendungen direkt aus SAP oder Dynamics heraus beauftragen. Im JTL-Forum formulierte ein Nutzer die Lage so: bezugnehmend auf die aktuelle Ankündigung von DHL müssen Nutzer bis zum 31.05.2026 zwingend von der alten SOAP-API (GKV v3) sowie der alten Retoure-API auf die neue REST-API umsteigen.

Was Sie vor dem Start brauchen

Ohne diese fünf Dinge beginnen Sie die Integration nicht. Um Sendungen über die DHL Paket DE Versenden API beauftragen zu können, benötigen Sie beziehungsweise Ihr Auftraggeber einen Geschäftskundenvertrag sowie einen Zugang zum Post & DHL Geschäftskundenportal (GKP). Die API ist dabei kein generischer Zugang, sondern wird exakt auf Ihre Vertragsdaten gemappt: Die DHL Paket DE Versenden API muss genau auf die 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.

• Aktiver DHL-Geschäftskundenvertrag mit EKP (Einzelkundennummer) und freigeschalteten Teilnahmen je Produkt.
• Administratorzugang zum Geschäftskundenportal unter geschaeftskunden.dhl.de, um Benutzer und Rechte zu verwalten.
• Ein neu angelegter Systembenutzer statt eines persönlichen Benutzers. Es gibt zwei Arten von Benutzern, Systembenutzer und persönliche Benutzer. Systembenutzer sind ausschließlich zur Verwendung in Systemanbindungen oder Webservices zu verwenden.
• Dem Systembenutzer die Berechtigung „Versenden" zugewiesen, sonst schlägt jeder API-Call fehl. Ohne diese Berechtigung darf der Benutzer keine Labels über die API erzeugen.
• Client-ID und Client-Secret aus dem DHL Developer Portal (developer.dhl.com) – diese sind nicht identisch mit dem GKP-Login und müssen separat für die App „Paket DE Versenden V2" beantragt werden.

Die technische Anbindung in 7 Schritten

Die folgende Reihenfolge hat sich bei der Migration von SOAP auf REST in der Praxis bewährt. Jeder Schritt baut auf dem vorherigen auf, überspringen Sie keinen davon.

1. Sandbox-Zugang im DHL Developer Portal beantragen. Legen Sie eine App für „Parcel DE Shipping V2" an. Client_id und client_secret für die Sandbox-Umgebung werden automatisch genehmigt, sobald Sie sie anfordern. Eine Produktivfreigabe ist dafür noch nicht nötig.
2. Systembenutzer im GKP anlegen und Access-Daten hinterlegen. Gehen Sie im Geschäftskundenportal zu „Benutzer verwalten" und erstellen Sie einen dedizierten Systembenutzer für die Automatisierung, zum Beispiel [email protected], mit dem Recht „Versenden" aktiviert. Ein persönlicher Benutzer eignet sich nicht, da er für die GUI-Anmeldung vorgesehen ist, nicht für Maschine-zu-Maschine-Kommunikation.
3. Access Token über die Authentication API holen. Die Authentifizierung läuft über einen eigenen, gemeinsam genutzten Endpunkt unter dem Pfad /parcel/de/account/auth/ropc/v1/token. Die API bietet eine Implementierung eines OAuth2.0 Resource-Owner-Password-Credentials-Flows. Wichtig für Ihre Integration: Der Access Token läuft nach 30 Minuten ab, danach muss ein neuer Token angefordert werden. Bauen Sie den Token-Refresh serverseitig ein, nicht pro einzelnem Request neu abfragen.
4. Testaufruf gegen /hello oder getVersion zur Basisverifizierung. Die Authentication API bietet eine einzelne Ressource /token und eine Testressource /hello, mit der Sie die Token-bezogene Funktionalität ausprobieren können, bevor Sie sie mit anderen APIs wie der Paket DE Retouren oder MyAccount API verwenden. Dieser Call benötigt keine Zugangsdaten und zeigt Ihnen, ob die Basisverbindung zur richtigen Umgebung steht, bevor Sie überhaupt mit Authentifizierung arbeiten.
5. Shipment-Order gegen die Sandbox erzeugen. Rufen Sie den Endpunkt /parcel/de/shipping/v2/orders auf der Sandbox-Basis-URL api-sandbox.dhl.com auf, optional mit dem Query-Parameter validate=True, um die Anfrage zunächst nur zu prüfen, ohne ein echtes Label zu erzeugen. Prüfen Sie in der Response die Sendungsnummer und das zurückgegebene Label-Objekt.
6. Auf die Produktiv-URL umstellen. Erst nach erfolgreicher Zertifizierung Ihrer Sandbox-Tests durch DHL wechseln Sie auf https://api-eu.dhl.com/parcel/de/shipping/v2/, die Produktionsumgebung, deren Nutzung erst nach erfolgreichem und von DHL zertifiziertem Sandbox-Test freigegeben wird. Planen Sie dafür Vorlauf ein: die Aktivierung der Produktivumgebung erfolgt laut DHL in der Regel innerhalb von 1 bis 3 Werktagen.
7. Tracking-Rückmeldungen ins TMS einbinden. Für Statusupdates nutzen Sie die Shipment-Tracking-API unter api-eu.dhl.com/track/shipments. Beachten Sie dabei das initiale Nutzungslimit: Sie erhalten zunächst eine Service-Stufe mit 250 Calls pro Tag, maximal ein Call alle 5 Sekunden – dieses Limit ist für die initiale Entwicklung gedacht und nicht für den Produktivbetrieb geeignet. Für den Produktivbetrieb mit höherem Sendungsvolumen müssen Sie ein höheres Kontingent beantragen.

Fehlerbild: 401 Unauthorized trotz korrekter Zugangsdaten

Der häufigste Blocker bei dieser Migration ist nicht fehlende Dokumentation, sondern eine Verwechslung von Umgebung oder Benutzertyp. Aus einem gelösten Supportfall im JTL-Forum: Der 401-Fehler ist ein Anmeldefehler, das heißt Name/Passwort sind falsch oder passen nicht zueinander. In der Praxis sind drei Ursachen für diesen Fehler verantwortlich.

• Falscher Benutzertyp hinterlegt: Ein persönlicher Benutzer ohne die Berechtigung „Versenden" kann keinen gültigen Token für Shipment-Calls erzeugen, selbst wenn Benutzername und Passwort korrekt sind.
• Abgelaufener Access Token: Nach 30 Minuten ist der Token ungültig. Wenn Ihr TMS den Token zwischenspeichert statt ihn rechtzeitig zu erneuern, laufen plötzlich alle Calls auf 401.
• Gemischte Umgebungen: Ein Sandbox-Key funktioniert nicht gegen die Produktiv-URL api-eu.dhl.com und umgekehrt. Das klingt banal, passiert aber regelmäßig bei der Umstellung, wenn Entwickler- und Produktivkonfiguration in unterschiedlichen Systemen liegen.

Hinzu kommt ein bekannter Bug im Zusammenhang mit der Migration: Im JTL-Forum wurde von NullReferenceException-Fehlern beim Erstellen von Labels unter der neuen Schnittstelle berichtet. Wenn Ihre Shipment-Order technisch korrekt aussieht, aber dennoch fehlschlägt, prüfen Sie zuerst, ob Ihre Middleware oder Ihr TMS-Connector bereits ein Update für die REST-API V2 erhalten hat, bevor Sie Zeit in die Fehlersuche am eigenen Code investieren.

Beachten Sie außerdem: Zukünftige API-Major-Versionen werden kein Basic Auth mehr unterstützen, DHL empfiehlt daher grundsätzlich OAuth2 zu nutzen. Wer die Migration jetzt mit Basic Auth als Übergangslösung umsetzt, baut sich die nächste Ablösung bereits mit ein.

GoBD-konforme Archivierung der Versanddaten

Versandlabels, Sendungsnummern und Statusmeldungen sind Handelsdaten mit Bezug zum Geschäftsvorfall und damit grundsätzlich aufbewahrungspflichtig. Für die technische Umsetzung bedeutet das: Ihr TMS oder Ihre Middleware muss die JSON-Response der Shipping API inklusive Sendungsnummer, Label-PDF und Zeitstempel unveränderbar und maschinell auswertbar ablegen, nicht nur den reinen Druckbeleg. Da die Produktivumgebung unter api-eu.dhl.com liegt, verarbeiten Sie die Daten innerhalb der EU, was die DSGVO-Bewertung im Vergleich zu Nicht-EU-Endpunkten vereinfacht. Details zur konkreten Archivierungspflicht und Fristen für Versanddaten haben wir in unserem separaten GoBD-Leitfaden auf diesem Blog zusammengefasst.

Eigenbau oder vorkonfigurierter Connector?

Wenn Sie ein Multi-Carrier-Setup betreiben oder DHL nicht Ihr einziger Versanddienstleister ist, lohnt sich die Frage, ob Sie die Schritte 1 bis 4 überhaupt selbst bauen müssen. TMS- und Carrier-Connectivity-Plattformen wie Cargoson, Sendcloud, nShift, Shipmondo, LetMeShip und ShipStation bieten vorkonfigurierte DHL-Anbindungen, bei denen Authentifizierung, Token-Handling und API-Versionswechsel bereits vom Anbieter gepflegt werden.

Checkliste: So wissen Sie, dass die Anbindung läuft

Bevor Sie die alte SOAP-Verbindung endgültig deaktivieren, prüfen Sie diese vier Punkte im Zusammenspiel.

• Ein Produktiv-Label wurde über api-eu.dhl.com erzeugt und enthält eine gültige, im GKP nachvollziehbare Sendungsnummer.
• Ein Tracking-Event für diese Sendung kommt über die Tracking-API im TMS an, nicht nur als manuelle Statusabfrage.
• Der Token-Refresh läuft automatisiert und ohne manuellen Eingriff alle 30 Minuten oder bei Bedarf.
• Die erzeugten Label- und Sendungsdaten erscheinen vollständig in Ihrem GoBD-Export, inklusive Zeitstempel und Referenz zum ursprünglichen Transportauftrag.

Setzen Sie sich für die verbleibende Umstellung eine feste interne Deadline, mindestens zwei Wochen vor einem geplanten Produktivstart, um Pufferzeit für die DHL-Zertifizierung der Produktivumgebung einzuplanen. Wer jetzt noch auf GKV v3 läuft, sollte die Sandbox-Registrierung im Developer Portal heute starten, nicht erst, wenn der nächste Versandtag ansteht.