# 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…

- Seite: <https://www.datafirefly.com/de/documentation/dftracking/>
- Sprache: de
- Aktualisiert am: 2026-08-04
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dftracking/index.md), [en](https://www.datafirefly.com/en/documentation/dftracking/index.md), [es](https://www.datafirefly.com/es/documentation/dftracking/index.md), [it](https://www.datafirefly.com/it/documentation/dftracking/index.md), [pl](https://www.datafirefly.com/pl/documentation/dftracking/index.md), [pt](https://www.datafirefly.com/pt/documentation/dftracking/index.md), [nl](https://www.datafirefly.com/nl/documentation/dftracking/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

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.

Diese Dokumentation behandelt Version **1.0.0** des Moduls, kompatibel mit PrestaShop **8.0.0 bis 9.x** und PHP 7.4 bis 8.3. Keine Klassen-Overrides, keine Composer-Abhängigkeiten.

## 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.

Das Mapping basiert auf der **Carrier-Referenz** (`id_reference`) und nicht auf der technischen ID: Es übersteht damit die Carrier-Duplikate, die PrestaShop bei jeder Tarifänderung anlegt.

## 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":"…"}`.

Das Token ist der einzige Schutz dieses Endpunkts. Veröffentlichen Sie es nicht und erneuern Sie es über die Schaltfläche **Cron-Token erneuern**, wenn Sie ein Leck vermuten — denken Sie dann daran, Ihren geplanten Task mit der neuen URL zu aktualisieren.

## 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.