Automatisches DHL- & Multi-Carrier-Tracking — Vollständiger Leitfaden

Das Modul DataFirefly Tracking fragt die DHL-API in Echtzeit ab, um Ihre DHL-eCommerce- und DHL-Express-Pakete zu verfolgen, lässt Ihre Bestellstatus bei Zustellung automatisch weiterlaufen und bietet Ihren Kunden eine gebrandete Tracking-Seite für 19 Carrier. Dieser Leitfaden behandelt Installation, Beschaffung des DHL-API-Schlüssels, Konfiguration, Cron, Tracking-Seite, Status-Synchronisierung, Hinzufügen von Carriern und Fehlerbehebung.

Voraussetzungen

• PrestaShop 8.0 bis 9.x.
• PHP 8.1 bis 8.3 mit aktivierter cURL-Erweiterung.
• Für das DHL-Tracking: ein Schlüssel der DHL-API „Shipment Tracking — Unified“ (developer.dhl.com).
• Cron-Zugang (geplante Serveraufgabe oder Cron-Dienst) für das automatische Tracking.

Installation

1. Öffnen Sie im Back-Office Module > Modul-Manager, dann Modul hochladen und legen Sie die Datei datafirefly_tracking.zip ab.
2. Öffnen Sie nach der Installation die Konfigurationsseite über die Schaltfläche Konfigurieren.

Bei der Installation erstellt das Modul seine Tabellen, registriert seine Hooks und generiert automatisch ein Cron-Token.

Den DHL-API-Schlüssel beschaffen

1. Erstellen Sie ein Konto auf developer.dhl.com.
2. Abonnieren Sie die API Shipment Tracking — Unified und erstellen Sie eine Anwendung.
3. Kopieren Sie den API-Schlüssel (Feld API Key).

Konfiguration

Die Konfigurationsseite fasst die folgenden Einstellungen zusammen:

• DHL Tracking API Key: Fügen Sie hier Ihren DHL-API-Schlüssel ein.
• Polling aktivieren: erlaubt automatische Aktualisierungen für DHL-Pakete.
• E-Mails (Versendet, Im Transit, Zugestellt, Vorfall): Benachrichtigungspräferenzen je Statuswechsel.
• PrestaShop-Status bei Zustellung aktualisieren: aktiviert die automatische Bestellstatus-Synchronisierung.
• Protokoll-Aufbewahrung (Tage): wie lange Protokollzeilen vor der automatischen Bereinigung aufbewahrt werden.

Speichern Sie Ihre Einstellungen. Solange der Schlüssel nicht eingetragen und das Polling nicht aktiviert ist, wird kein DHL-Paket abgefragt.

Unterstützte Carrier

Das Modul erkennt 19 Carrier, aufgeteilt in zwei Kategorien.

Echtzeit-API-Tracking (2)

DHL eCommerce und DHL Express: Die Status werden über die DHL-API abgerufen, normalisiert (erstellt, im Transit, zugestellt, Vorfall) und auf einer Timeline angezeigt.

Gebrandeter Tracking-Link (17)

Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost und PostNL: Die Tracking-Seite zeigt einen Link zur offiziellen Seite des Carriers, ohne API-Aufruf.

Automatische Tracking-Erstellung

Wenn eine Bestellung auf den Status „Versendet“ wechselt, erkennt das Modul den Carrier, löst die Sendungsnummer auf und erstellt den Tracking-Datensatz. Die Nummer wird der Reihe nach gesucht in:

1. der Carrier-Zeile der Bestellung (order_carrier);
2. den DHL-Parcel-Labels (sofern vorhanden);
3. der DHL-Express-AWB-Nummer (sofern vorhanden).

Für DHL-Pakete wird das Tracking anschließend automatisch abgefragt; für die anderen Carrier wird der Bestellung lediglich ein Tracking-Link zugeordnet.

Cron-Einrichtung

Der Cron treibt das regelmäßige Polling der DHL-Pakete an und holt Sendungen nach, die der Hook verpasst haben könnte (Nummer nach dem Wechsel auf „Versendet“ gesetzt, Carrier ohne Modul). Planen Sie die folgende URL alle 15 bis 30 Minuten:

curl "https://ihr-shop.com/module/datafirefly_tracking/cron?token=IHR_TOKEN"

Das Token wird bei der Installation generiert und in der Konfiguration angezeigt. Für ein einmaliges historisches Nachholen älterer Bestellungen fügen Sie den Parameter days hinzu:

curl "https://ihr-shop.com/module/datafirefly_tracking/cron?token=IHR_TOKEN&days=60"

Das API-Kontingent und der Rate-Limiter

Die DHL-API ist auf 250 Anfragen pro Tag begrenzt. Das Modul bringt einen Rate-Limiter mit, der:

• die Aufrufe des Tages zählt und das Polling beim Limit sauber stoppt, dann am nächsten Tag fortsetzt;
• die Abfragen nach Paketstatus staffelt (häufiger bei einem Vorfall, seltener für ein nur erstelltes Paket);
• zugestellte Pakete endgültig nicht mehr abfragt;
• eine Nummer nach mehreren „nicht gefunden“-Fehlern aufgibt (z. B. eine Nicht-DHL-Nummer, die bei einem DHL-Carrier eingegeben wurde).

Der Tageszähler ist in der Konfiguration und auf der Bestellseite sichtbar.

Tracking-Seite für Kunden

Ein Link „Mein Paket verfolgen“ erscheint im Bestelldetail und im Kundenkonto. Die gebrandete Tracking-Seite zeigt eine 4-Schritt-Timeline (Versendet, Im Transit, In Zustellung, Zugestellt) und die Ereignisdetails.

Sie ist zugänglich:

• für angemeldete Kunden, für ihre eigenen Bestellungen;
• für Gäste, über die Sendungsnummer zusammen mit der Bestellreferenz.

Tracking im Back-Office

Auf jeder Bestellseite zeigt ein Tracking-Tab die Timeline, das letzte Ereignis, den normalisierten Status und eine Schaltfläche Aktualisieren, um DHL manuell abzufragen (innerhalb des Kontingents). Der Link zur offiziellen Tracking-Seite des Carriers und zur Front-Tracking-Seite wird ebenfalls bereitgestellt.

Bestellstatus-Synchronisierung

Wenn die Option PrestaShop-Status bei Zustellung aktualisieren aktiviert ist, lässt das Modul den Bestellstatus für DHL-Pakete weiterlaufen:

• Paket zugestellt → Status „Zugestellt“;
• Zustell-Vorfall → Status „Fehler“.

Der Statuswechsel löst die nativen E-Mails von PrestaShop aus. Das Modul verhindert jede Herabstufung: Eine bereits zugestellte Bestellung kann nicht auf „im Transit“ zurückgehen.

Einen Carrier hinzufügen

Alle Carrier sind in einem zentralen Register beschrieben (Klasse CarrierRegistry). Einen Carrier hinzuzufügen bedeutet, einen einzigen Eintrag hinzuzufügen, der Folgendes enthält:

• seine interne Kennung und sein Label;
• die Modulnamen (external_module_name) und die Namensmuster für die Erkennung;
• seine Tracking-URL (mit den Markern {tracking} und, falls nötig, {postcode});
• das API-Tracking- oder Link-Kennzeichen und die Regel zur Nummernvalidierung.

Kein anderer Teil des Moduls muss geändert werden: Erkennung, URL, Label und Dashboard ergeben sich automatisch.

Aktualisierung von einer früheren Version

Die Aktualisierung erfolgt durch Ersetzen der Moduldateien; PrestaShop wendet die Migrationsskripte automatisch an. Version 1.1.0 erweitert die Carrier-Typ-Spalte, um die neuen Carrier aufzunehmen: Dieses Skript ist idempotent und erhält die vorhandenen Daten.

Fehlerbehebung

• Kein DHL-Paket wird verfolgt: Prüfen Sie, dass der API-Schlüssel eingetragen ist, das Polling aktiviert ist und der Cron läuft.
• Fehler „Ungültiger API-Schlüssel“: Stellen Sie sicher, dass Sie den Shipment-Tracking-—-Unified-API-Schlüssel verwenden, nicht den DHL-eCommerce-Versandschlüssel.
• Kontingent erreicht: Bei 250 Anfragen/Tag stoppt das Polling und wird am nächsten Tag fortgesetzt. Staffeln Sie den Cron oder reduzieren Sie bei Bedarf die Zahl der aktiven Pakete.
• Ein Paket bleibt nicht gefunden: Nach mehreren „nicht gefunden“-Fehlern gibt das Modul die Nummer auf (oft eine Nicht-DHL-Nummer, die bei einem DHL-Carrier eingegeben wurde).
• Der Bestellstatus ändert sich nicht: Prüfen Sie, dass die Status-Update-Option aktiviert ist und das Paket tatsächlich von der DHL-API verfolgt wird.
• Unvollständiger PostNL-Tracking-Link: Die PLZ stammt aus der Lieferadresse; prüfen Sie, dass sie in der Bestellung eingetragen ist.

Deinstallation

Die Deinstallation entfernt die Tracking-, Protokoll- und Kontingenttabellen des Moduls sowie seine Konfiguration. Für eine einfache Aktualisierung genügt das Ersetzen der Dateien: Das Schema und die Tracking-Datensätze bleiben erhalten.