README

DHL Paket-Tracking Modul fuer OXID eShop 6.x.

Holt automatisch Sendungsstatus, Events und voraussichtliches Zustelldatum ueber die offizielle DHL Shipment Tracking - Unified API und zeigt alle Informationen direkt in der OXID-Bestelluebersicht im Admin an.

Features

Sendungsstatus, voraussichtliches Zustelldatum und alle Events direkt in der Admin-Bestelluebersicht
Automatisches Speichern des Auslieferdatums (tabsldhltracking_deliverydate) sobald die Sendung den Status delivered erreicht
Mehrfach-Trackingnummern (durch , oder ; getrennt) werden unterstuetzt — die erste Nummer wird verwendet
Konfigurierbares Absenderland (Standard: DE) fuer korrekte Cross-Border-Anfragen
Roh-Response der DHL-API wird gespeichert (tabsldhltracking_info) — vollstaendige Sendungsdaten jederzeit einsehbar
Debug-Modus zeigt die aufgerufene API-URL und den vollstaendigen Response im Admin an
Funktioniert mit OXID 6.x (Smarty) — das einzige Template ist ein Admin-Block, der Storefront bleibt vom eigenen Theme unberuehrt
Bulk-Update via Cronjob: Auth-geschuetzter Frontend-Endpoint aktualisiert alle offenen Sendungen (kein Auslieferdatum) automatisch in einem konfigurierbaren Zeitfenster

Installation

composer require tabsl/tabsldhltracking

Anschliessend das Modul im OXID Admin unter Erweiterungen → Module aktivieren. Die benoetigten Datenbank-Felder (tabsldhltracking_deliverydate, tabsldhltracking_info) werden beim Aktivieren automatisch in oxorder angelegt.

DHL API Zugang einrichten

Das Modul nutzt die DHL Shipment Tracking - Unified API des DHL Developer Portals. Der API-Zugang ist fuer Geschaeftskunden mit einer DHL Paket Geschaeftskunden-Vertragsnummer (EKP) kostenfrei.

1. DHL Developer Portal Account

Auf developer.dhl.com registrieren
E-Mail-Adresse bestaetigen und einloggen

2. App anlegen und API freischalten

Im Portal auf My Apps → Apps → Create new App klicken
Beliebigen App-Namen vergeben (z. B. OXID Shop Tracking)
Unter APIs die API Shipment Tracking - Unified zur App hinzufuegen
App speichern

Nach Anlage der App wird ein API Key (Consumer/Customer Key) erzeugt. Dieser Key ist sofort gegen die Sandbox nutzbar.

3. Produktiv-Freischaltung beantragen

Fuer den produktiven Einsatz muss die Shipment-Tracking-API zusaetzlich produktiv freigeschaltet werden:

App oeffnen → API Shipment Tracking - Unified anwaehlen
Get Production Key anklicken
Im Formular die DHL Geschaeftskunden-Nummer (EKP, 10-stellig) angeben und Anwendungsfall beschreiben (z. B. "Statusabfrage versendeter Paketsendungen im OXID Shop Backend")
DHL prueft den Antrag in der Regel innerhalb weniger Werktage

Nach Freigabe steht derselbe API Key auch produktiv zur Verfuegung — es ist kein separater Key noetig.

4. API Key im Modul hinterlegen

Im OXID Admin unter Erweiterungen → Module → tabslDhlTracking → Einstellungen:

tabsldhltracking_api_key — der API Key aus dem DHL Developer Portal (wird als Header DHL-API-Key gesendet). Standard: (leer)
tabsldhltracking_api_url — API-Endpoint. Standard: https://api-eu.dhl.com/track/shipments
tabsldhltracking_senderCountry — ISO-2-Code des Absenderlandes. Standard: DE
tabsldhltracking_debug — API-URL und Response zur Diagnose im Admin anzeigen. Standard: false

5. Rate Limits

Der DHL-API-Zugang hat ein Rate Limit. Aktuelle Werte (Stand DHL Developer Portal):

Sandbox: 5 Requests/Sekunde, 250 Requests/Tag
Production: 5 Requests/Sekunde, deutlich hoeheres Tageskontingent (abhaengig vom Antrag)

Das Modul ruft die API nur on demand auf (Button im Admin), nicht automatisiert in Bulk. Wer ein Cronjob-basiertes Bulk-Update plant, sollte das Rate Limit im Blick behalten.

Verwendung

In der OXID Bestellbearbeitung (Reiter Hauptdaten) erscheint nach Aktivierung des Moduls ein zusaetzlicher Block unterhalb der Versanddaten. Vorausgesetzt im Feld Tracking Code (oxorder.oxtrackcode) ist eine DHL-Sendungsnummer hinterlegt, kann ueber den Button DHL-Status aktualisieren der aktuelle Sendungsstatus abgerufen werden.

Angezeigt werden anschliessend:

Aktueller Status inkl. statusCode, Statustext und estimatedTimeOfDelivery
Alle Events der Sendung mit Zeitstempel, Ort und Beschreibung
Optional: kompletter Roh-Response der API (Debug)

Cronjob (Bulk-Status-Update)

Das Modul bringt einen Frontend-Controller mit, der per Cronjob alle offenen Sendungen automatisch aktualisiert — alle Bestellungen mit Tracking-Code, ohne persistiertes Auslieferdatum, im konfigurierten Zeitfenster (Default 30 Tage).

1. Auth-Key

Im OXID Admin unter Erweiterungen → Module → tabslDhlTracking → Einstellungen → Cronjob:

tabsldhltracking_cron_key — Shared Secret. Wird beim Aktivieren des Moduls automatisch mit einem 32-Zeichen-Hex-Hash (md5(uniqid(rand(), true))) vorbelegt — sofort einsatzbereit, kann jederzeit ueberschrieben werden (z. B. via openssl rand -hex 16). Solange der Key leer gesetzt wird, ist der Cron-Endpoint deaktiviert (HTTP 401).
tabsldhltracking_cron_days — Zeitfenster in Tagen ab heute rueckwaerts (Default 30)
tabsldhltracking_cron_sleep — Pause zwischen den DHL-API-Calls in Sekunden (Default 2, schont das DHL-Rate-Limit von 5 req/s)
tabsldhltracking_deliverysets — Whitelist von Versandarten (oxdeliveryset.oxid, eine ID pro Zeile). Nur Bestellungen mit oxorder.oxdeltype aus dieser Liste werden vom Cron geprueft. Leer = alle Versandarten (Default).
tabsldhltracking_trackcode_prefix — Prefix-Filter fuer oxorder.oxtrackcode (z. B. JJD fuer DHL Express). Nur Tracking-Codes, die mit diesem String beginnen, werden vom Cron geprueft. Leer = alle Codes (Default). Wird LIKE 'prefix%' gegen die DB angewandt.

Beide Filter sind kombinierbar (AND-Verknuepfung) und greifen nur im Cron. Der manuelle "DHL-Status aktualisieren"-Button im Admin laeuft unabhaengig davon — der Admin entscheidet pro Bestellung.

2. URL aufrufen

https://<shop>/index.php?cl=tabsldhltrackingcron&fnc=update&key=<SECRET>

Antwort (Plaintext):

[2025-11-22 03:00:01] tabslDhlTracking cron update (last 30 days)
  100123: updated
  100124: updated
  100125: skipped/failed
summary: 3 eligible, 2 updated, 1 skipped/failed

3. Crontab-Beispiel

# alle 3 Stunden DHL-Status fuer offene Sendungen pruefen
0 */3 * * * curl -s "https://shop.example.com/index.php?cl=tabsldhltrackingcron&fnc=update&key=<SECRET>" >> /var/log/tabsldhltracking.log 2>&1

Alternativ via gehosteten Cron-Diensten (cron-job.org, EasyCron, Hetzner Cloud Function etc.) — dort einfach die URL eintragen.

4. Logfile

Wenn das Shop-Verzeichnis log/ beschreibbar ist, werden die Cron-Outputs zusaetzlich an log/tabsldhltracking.log angehaengt.

5. Hinweise

Der Endpoint laeuft als Frontend-Controller, nicht im Admin-Bereich — kein Admin-Login noetig, ausschliesslich der Key schuetzt den Zugriff
Bei einem leeren Key liefert der Endpoint 401 — kein versehentlich offener Endpoint moeglich
Bei cron_sleep = 0 keine Pause; mit 2 bleibt der Cron deutlich unter DHL's 5 req/s
Pro Aufruf werden nur Sendungen ohne tabsldhltracking_deliverydate angefasst — bereits zugestellte Pakete werden nicht erneut abgefragt

Kompatibilitaet

OXID eShop 6.x (Smarty) — vollstaendig unterstuetzt
PHP 7.4+ / PHP 8.x

Changelog

Siehe CHANGELOG.md.

License

GNU General Public License v3.0 — siehe LICENSE.

Copyright

Tobias Merkl | https://oxid-module.eu

tabsl / tabsldhltracking

Maintainers

Package info

Statistics

Security