DHL Parcel Poland Integration

Das DHL-Modul verbindet WooCommerce mit der REST-API von DHL Parcel Poland für die Sendungsverfolgung. Sie tragen die Sendungsnummer an der Bestellung ein, und das Modul holt den aktuellen Status samt Ereignisverlauf von DHL.

Konfiguration

Die DHL-Einstellungen gehören zur Versandgruppe der PRO-Einstellungen (Option polski_pro_shipping). Gelesen und geschrieben werden sie über die REST-Route der PRO-Einstellungen, /wp-json/polski-pro/v1/settings, die die Berechtigung manage_woocommerce voraussetzt. Ein eigener Bildschirm für die Versandeinstellungen ist geplant, aber noch nicht ausgeliefert.

API-Authentifizierung

Einstellung	Schlüssel	Beschreibung
DHL aktiviert	`dhl_enabled`	Schaltet den DHL-Anbieter ein
DHL-API-Schlüssel	`dhl_api_key`	Bearer-Token aus dem DHL WebAPI-Portal
DHL-Kontonummer	`dhl_account_number`	Kundenkontonummer bei DHL Parcel Poland

Den API-Schlüssel erhalten Sie, indem Sie sich unter developer.dhl.com registrieren und eine Anwendung mit Zugriff auf die DHL Parcel Poland API erstellen.

Modul aktivieren

Senden Sie dhl_enabled als true in der Gruppe shipping per PUT an /wp-json/polski-pro/v1/settings
Senden Sie dhl_api_key und dhl_account_number in derselben Anfrage, denn der gespeicherte Payload ersetzt die gesamte Option
Der Tracking-Bereich an der Bestellung gehört zum Modul Fulfillment, dieses Modul muss daher unter Polski > Module aktiviert sein

DHL wird nur abgefragt, wenn dhl_enabled aktiv ist und beide Felder ausgefüllt sind. Fehlt eines dieser drei Elemente, behält die Bestellung weiterhin Sendungsnummer und Tracking-Link, ein Live-Status wird jedoch nicht abgerufen.

Sendungsnummer erfassen

Etiketten erstellen Sie in Ihren eigenen DHL-Werkzeugen. Sobald Ihnen die Nummer vorliegt, hinterlegen Sie sie an der Bestellung:

Öffnen Sie eine Bestellung unter WooCommerce > Bestellungen
Wählen Sie im Abschnitt Shipment Tracking den Versanddienstleister DHL
Fügen Sie die Nummer in das Feld Sendungsnummer ein
Lassen Sie Tracking-URL leer, damit der Link erzeugt wird, oder tragen Sie einen eigenen Link ein
Aktualisieren Sie die Bestellung

Der DHL-Tracking-Link wird im folgenden Format erzeugt:

https://www.dhl.com/pl-pl/home/sledzenie-przesylek.html?tracking-id={number}

Live-Status aktualisieren

Sobald eine Bestellung eine Sendungsnummer hat, zeigt der Abschnitt Shipment Tracking eine Live-Vorschau mit der Schaltfläche Live-Tracking aktualisieren. Sie ruft die DHL-Tracking-API mit Ihrem Bearer-Token auf und zeigt den aktuellen Status sowie die Ereignisliste (Beschreibung, Datum, Ort).

Eine Abfrage wird 10 Minuten zwischengespeichert. Die Schaltfläche leert den Cache für diese Sendung und holt die Daten erneut, nutzen Sie sie also, wenn Sie einen frischen Scan erwarten.

Wo das Tracking erscheint

Spalte Tracking in der Bestellliste: Dienstleister, Nummer, Live-Status und ein Tracking-Link
Bestelldetails im Kundenkonto sowie die Aktion Sendung verfolgen neben der Bestellung
WooCommerce-Bestell-E-Mails, in denen der Tracking-Block unter der Bestelltabelle ergänzt wird
Statusmeldungen zu Verpackt, Versendet und Zugestellt mit Dienstleister, Sendungsnummer und Tracking-Link

Die drei Status stehen in der Bestellliste auch als Massenaktionen zur Verfügung: Status ändern auf Verpackt, Versendet und Zugestellt.

Etiketten und ServicePoint-Suche

Etikettenerstellung und ServicePoint-Suche sind programmiert, aber nicht angebunden. DHLProvider enthält einen Etikettenaufruf und eine Abfrage der Abholpunkte, doch nichts im Backend oder an der Kasse ruft sie auf. Es gibt daher keine Schaltfläche zum Erstellen von Etiketten, kein PDF-Etikett und keine Suche nach Abholpunkten auf dem Bildschirm, Sendungen legen Sie vorerst in den eigenen Werkzeugen von DHL an.

Fehlerbehebung

Symptom	Ursache	Lösung
Live-Vorschau zeigt keinen Status	Modul aus oder API-Schlüssel / Kontonummer leer	`dhl_enabled`, API-Schlüssel und Kontonummer über die Einstellungsroute speichern
Aktualisierung liefert nichts	Ungültiger Bearer-Token (HTTP 401) oder unbekannte Sendungsnummer	Token in den Einstellungen und Nummer an der Bestellung prüfen
Status wirkt veraltet	Der Abfrage-Cache von 10 Minuten	Auf Live-Tracking aktualisieren klicken
Wiederholt leere Antworten	Anfragelimit von DHL (HTTP 429)	Einen Moment warten und erneut aktualisieren

Filter und Aktionen

Das DHL-Modul bietet noch keine öffentlichen Filter. Die Tracking-Daten liegen in den Bestell-Metadaten, Sie können sie also aus eigenem Code setzen:

// DHL-Sendungsnummer an einer Bestellung speichern.
$order = wc_get_order($orderId);
$order->update_meta_data('_polski_shipping_carrier', 'dhl');
$order->update_meta_data('_polski_tracking_number', '6230000123456789');
$order->save();

Wenn Sie _polski_tracking_url nicht setzen, wird der DHL-Link bei der Anzeige aus der Nummer abgeleitet.