Multi-Carrier-Sendungsverfolgungsseite — Vollständige Anleitung (dftracking)

dftracking ergänzt Ihren PrestaShop-Shop um eine Sendungsverfolgungsseite im eigenen Branding. Das Modul fragt die Carrier-APIs direkt ab (Colissimo, Mondial Relay, Chronopost, DHL), normalisiert deren uneinheitliche Status zu einem gemeinsamen Vokabular und stellt sie auf einer Timeline mit vier Schritten dar — samt detaillierter Ereignishistorie jedes Pakets.

Installation

1. Öffnen Sie im PrestaShop-Back-Office Module > Modul-Manager.
2. Klicken Sie auf Modul hochladen und legen Sie die Datei dftracking.zip ab.
3. Klicken Sie nach Abschluss der Installation auf Konfigurieren.

Bei der Installation legt das Modul die Cache-Tabelle ps_dftracking_shipment an, erzeugt ein zufälliges Cron-Token und registriert vier Hooks: moduleRoutes (sprechende URL /order-tracking), displayOrderDetail (Schaltfläche „Mein Paket verfolgen“ in der Bestelldetailansicht), displayCustomerAccount (Link im Kundenkonto) und actionFrontControllerSetMedia (Stylesheet der Seite).

Carrier-API-Zugangsdaten

Jeder Carrier hat sein eigenes Authentifizierungsverfahren. Tragen Sie nur die tatsächlich genutzten ein: Ein nicht konfigurierter Carrier wird schlicht nicht abgefragt, und das Modul greift auf den öffentlichen Tracking-Link zurück.

Colissimo / La Poste

Der Konnektor nutzt die API Suivi v2 der Okapi-Plattform. Erstellen Sie ein kostenloses Konto auf developer.laposte.fr, abonnieren Sie die API „Suivi“ und fügen Sie den Okapi-Key im Feld Colissimo / La Poste — Okapi-API-Key ein.

Mondial Relay

Der Konnektor nutzt den Dienst WSI2_TracingColisDetaille. Tragen Sie Ihren Enseigne-Code (meist 8 Zeichen, z. B. BDTEST13 in der Testumgebung) und Ihren privaten Schlüssel ein, beide aus Ihrem Mondial-Relay-Vertrag oder aus Connect Hub. Das Modul berechnet die vom Dienst erwartete MD5-Signatur automatisch.

Chronopost

Es sind keine Zugangsdaten erforderlich: Der Konnektor nutzt den öffentlichen Endpunkt TrackingServiceWS, der Sendungsnummern ohne Authentifizierung akzeptiert. Die Felder für Konto und Passwort existieren für Sonderkonfigurationen, bleiben aber optional.

DHL

Der Konnektor nutzt die API Shipment Tracking – Unified. Erstellen Sie ein Konto auf developer.dhl.com, abonnieren Sie diese API und fügen Sie den Key im Feld DHL — API-Key ein. Achten Sie auf die Kontingente des kostenlosen Plans: Cache und Cron des Moduls sind genau darauf ausgelegt, diese zu schonen.

Carrier-Mapping

Der Abschnitt Carrier-Mapping listet alle Carrier Ihres Shops auf und erlaubt die Zuordnung eines Konnektors. Zwei Mechanismen greifen ineinander:

• Explizites Mapping — Sie wählen den Konnektor aus der Auswahlliste. Das ist die empfohlene Methode, insbesondere wenn Ihre Carrier eigene Handelsnamen tragen („24h-Expresslieferung“, „Abholung im Paketshop“ …).
• Automatische Erkennung — bei Carriern, die auf „Nicht verfolgt“ stehen, sucht das Modul Schlüsselwörter im Carrier-Namen (colissimo, la poste, mondial relay, point relais, chronopost, dhl …) und wendet den passenden Konnektor an.

Branding der Tracking-Seite

Der Abschnitt Branding & Anzeige steuert das Erscheinungsbild der Frontend-Seite:

• Primärfarbe — Überschriften, aktueller Timeline-Schritt, Carrier-Links. Standard #2c3e50.
• Akzentfarbe — abgeschlossene Schritte und Status „Zugestellt“. Standard #27ae60.
• Eigene Überschrift — ersetzt den Standardtitel „Verfolgen Sie Ihre Bestellung“ oben auf der Seite.
• Bestellprodukte anzeigen — ergänzt unter der Timeline die Artikelliste mit Vorschaubildern und Mengen.
• Cache-Dauer (Minuten) — siehe nächster Abschnitt.

Die Farben werden als CSS-Variablen in den Seitencontainer injiziert: Das übrige Layout erbt selbstverständlich von Ihrem Theme.

Cache und Aktualisierung

Jedes verfolgte Paket belegt eine Zeile der Tabelle ps_dftracking_shipment, die den normalisierten Status, die Ereignisse im JSON-Format, die Tracking-URL des Carriers und den Zeitstempel der letzten Aktualisierung speichert.

Zwei Mechanismen halten diese Daten aktuell:

1. Der Cron-Job — der Hauptmechanismus. Er wählt nicht abgeschlossene Pakete aus, deren Daten die Cache-Dauer überschritten haben, aktualisiert sie stapelweise und erfasst dabei neue Sendungen aus Bestellungen der letzten 60 Tage.
2. Die Aktualisierung beim Seitenaufruf — das Sicherheitsnetz. Ruft ein Kunde seine Tracking-Seite mit veralteten Daten auf, wird die API sofort abgefragt.

In beiden Fällen wird ein Paket mit dem Status Zugestellt oder Rücksendung an Absender nie wieder abgefragt: Diese Zustände gelten als endgültig.

Cron einrichten

Die Cron-URL inklusive Token wird oben auf der Konfigurationsseite des Moduls angezeigt. Planen Sie sie alle 30 bis 60 Minuten ein:

*/30 * * * * curl -s "https://ihrshop.com/index.php?fc=module&module=dftracking&controller=cron&token=IHR_TOKEN" > /dev/null

Der optionale Parameter &limit=100 begrenzt die Anzahl der API-Aufrufe je Lauf (standardmäßig 50, maximal 200). Der Endpunkt antwortet in JSON: {"ok":true,"refreshed":12,"errors":0,"time":"…"}.

Die Tracking-Seite aus Kundensicht

Die Seite ist unter /order-tracking erreichbar (URL nach der Installation unter Shop-Parameter > Traffic & SEO änderbar).

• Eingeloggter Kunde — die Schaltfläche „Mein Paket verfolgen“ erscheint in jeder Bestelldetailansicht, und im Kundenkonto wird ein Link „Sendungsverfolgung“ ergänzt. Das Modul prüft stets, ob die Bestellung dem eingeloggten Kunden gehört.
• Gast — ein Formular fragt Bestellreferenz und E-Mail-Adresse ab. Beide müssen übereinstimmen, damit die Bestellung angezeigt wird; im Fehlerfall bleibt die Meldung bewusst allgemein und verrät nie, ob die Referenz existiert.

Die globale Timeline spiegelt das am weitesten fortgeschrittene Paket der Bestellung wider. Darunter erhält jede Sendung eine eigene Karte: Carrier-Name, Sendungsnummer, farbige Status-Pille, detaillierte Ereignishistorie (Datum, Beschreibung, Ort) und ein Link zur offiziellen Sendungsverfolgung des Carriers.

Normalisierte Status

Die carrier-spezifischen Bezeichnungen werden in sieben gemeinsame Status überführt, was eine einheitliche Darstellung unabhängig vom Paket ermöglicht:

• Warten auf Abholung — Label erstellt, Paket noch nicht gescannt.
• Unterwegs — das Paket bewegt sich im Netzwerk.
• In Zustellung — letzte Etappe, Tour des Tages.
• Am Abholpunkt verfügbar — Paket wartet im Paketshop oder in der Filiale.
• Zugestellt — Endstatus.
• Zustellstörung — vom Carrier gemeldete Unregelmäßigkeit.
• Rücksendung an Absender — Endstatus.

Bestellungen mit mehreren Paketen

Das Modul liest die Tabelle order_carrier: Jede der Bestellung zugeordnete Sendungsnummer wird als eigenständige Sendung behandelt — mit eigenem Konnektor, Status und Verlauf. Für ältere Shops, in denen die Sendungsnummer nur an der Bestellung selbst hinterlegt ist (shipping_number), sorgt ein Fallback-Mechanismus für Kompatibilität.

Einen Carrier ergänzen

Die Architektur ist bewusst offen. So integrieren Sie einen weiteren Carrier:

1. Legen Sie in src/Adapter/ eine Klasse an, die DftrackingAbstractCarrierAdapter erweitert.
2. Implementieren Sie getCode(), getLabel(), isConfigured(), getPublicUrl(), getNameKeywords() und fetch(). Letztere gibt ein Array aus status / events / tracking_url zurück und nutzt dabei die Helfer httpRequest(), event() und result() der abstrakten Klasse.
3. Ergänzen Sie die Klasse im Array von DftrackingAdapterRegistry::all() sowie das passende require_once in dftracking.php.

Der neue Konnektor erscheint automatisch in den Mapping-Auswahllisten des Back-Office.

Fehlerbehebung

• Die Seite zeigt „Ihre Bestellung wurde noch nicht versandt“ — an der Bestellung ist keine Sendungsnummer hinterlegt. Ergänzen Sie sie in der Bestellansicht des Back-Office, Reiter Versand.
• Der Status aktualisiert sich nicht — prüfen Sie zunächst, ob der Cron-Job läuft, indem Sie seine URL manuell im Browser aufrufen: Die JSON-Antwort nennt die Zahl der aktualisierten Pakete und der Fehler. Sehen Sie anschließend unter Erweiterte Einstellungen > Protokolle nach: Fehlgeschlagene API-Aufrufe werden dort mit der Rückmeldung des Carriers erfasst.
• Fehler „tracking number not found“ — in den Stunden nach der Label-Erstellung normal: Der Carrier hat das Paket noch nicht erfasst. Das Modul versucht es im nächsten Zyklus erneut.
• Ein Carrier wird nicht erkannt — die automatische Erkennung hat kein Schlüsselwort im Namen gefunden. Ordnen Sie ihn im Abschnitt Carrier-Mapping explizit zu.
• Das Gastformular findet die Bestellung nicht — Referenz und E-Mail müssen exakt mit der Bestellung übereinstimmen. Achten Sie auf Bestellungen mit einer anderen E-Mail-Adresse als der des Kundenkontos.
• Die Seite übernimmt meine Farben nicht — leeren Sie nach der Änderung den PrestaShop-Cache (Erweiterte Einstellungen > Leistung), da das Stylesheet vom Theme zwischengespeichert wird.

Deinstallation

Die Deinstallation entfernt die Tabelle ps_dftracking_shipment und sämtliche Konfigurationsschlüssel, einschließlich Ihrer API-Zugangsdaten. Sichern Sie diese, falls Sie das Modul erneut installieren möchten.