Trackingpagina voor bestellingen bij meerdere vervoerders: volledige gids (dftracking)

dftracking voegt aan uw PrestaShop-winkel een trackingpagina in uw huisstijl toe. De module bevraagt rechtstreeks de API’s van de vervoerders (Colissimo, Mondial Relay, Chronopost, DHL), normaliseert de uiteenlopende statussen naar een gemeenschappelijk vocabulaire en toont ze op een tijdlijn in vier stappen, samen met het detail van de gebeurtenissen per pakket.

Installatie

1. Open in uw PrestaShop back-office Modules > Modulebeheer.
2. Klik op Een module installeren en sleep het bestand dftracking.zip erin.
3. Klik na de installatie op Configureren.

Bij de installatie maakt de module de cachetabel ps_dftracking_shipment aan, genereert ze een willekeurig crontoken en registreert ze zich op vier hooks: moduleRoutes (vriendelijke URL /order-tracking), displayOrderDetail (knop “Mijn pakket volgen” op het besteldetail), displayCustomerAccount (link in de klantzone) en actionFrontControllerSetMedia (stylesheet van de pagina).

API-gegevens van de vervoerders

Elke vervoerder heeft zijn eigen authenticatiewijze. Vul alleen die in die u gebruikt: een niet-geconfigureerde vervoerder wordt simpelweg niet bevraagd, en de module valt terug op de publieke trackinglink.

Colissimo / La Poste

De connector gebruikt de API Suivi v2 van het Okapi-platform. Maak een gratis account aan op developer.laposte.fr, abonneer u op de API “Suivi” en kopieer de Okapi-sleutel in het veld Colissimo / La Poste: Okapi API-sleutel.

Mondial Relay

De connector gebruikt de dienst WSI2_TracingColisDetaille. Vul uw Enseigne-code in (doorgaans 8 tekens, bijvoorbeeld BDTEST13 in testomgeving) en uw private sleutel, beide te vinden in uw Mondial Relay-contract of via Connect Hub. De module berekent automatisch de MD5-handtekening die de dienst verwacht.

Chronopost

Er zijn geen inloggegevens nodig: de connector steunt op het publieke endpoint TrackingServiceWS, dat trackingnummers zonder authenticatie aanvaardt. De velden account en wachtwoord zijn aanwezig voor bijzondere configuraties maar blijven optioneel.

DHL

De connector gebruikt de API Shipment Tracking – Unified. Maak een account aan op developer.dhl.com, abonneer u op deze API en kopieer de sleutel in het veld DHL: API-sleutel. Let op de quota van het gratis plan: de cache en de cron van de module zijn er precies op ontworpen om die te sparen.

Mapping van de vervoerders

De sectie Vervoerdersmapping somt alle vervoerders van uw winkel op en laat u elk aan een connector koppelen. Twee mechanismen werken samen:

• Expliciete mapping: u kiest de connector in de keuzelijst. Dit is de aanbevolen methode, zeker als uw vervoerders commerciële eigen namen dragen (“Expreslevering 24u”, “Afhalen bij een afhaalpunt”…).
• Autodetectie: voor vervoerders die op “Niet gevolgd” blijven staan, zoekt de module trefwoorden in de vervoerdersnaam (colissimo, la poste, mondial relay, point relais, chronopost, dhl…) en past ze de bijbehorende connector toe.

Branding van de trackingpagina

De sectie Branding en weergave stuurt het uiterlijk van de frontpagina:

• Primaire kleur: titels, actieve stap van de tijdlijn, vervoerderslinks. Standaard #2c3e50.
• Accentkleur: afgeronde stappen en status “Geleverd”. Standaard #27ae60.
• Aangepaste titel: vervangt de standaardtitel “Volg uw bestelling” bovenaan de pagina.
• Producten van de bestelling tonen: voegt onder de tijdlijn de artikellijst toe met miniaturen en aantallen.
• Cacheduur (minuten): zie de volgende sectie.

De kleuren worden als CSS-variabelen op de paginacontainer geïnjecteerd: de rest van de lay-out erft vanzelf van uw thema.

Cache en verversing

Elk gevolgd pakket beslaat een regel van de tabel ps_dftracking_shipment, die de genormaliseerde status, de gebeurtenissen in JSON-formaat, de tracking-URL van de vervoerder en de tijdstempel van de laatste update bewaart.

Twee mechanismen houden deze gegevens vers:

1. De crontaak: het hoofdmechanisme. Ze selecteert de niet-afgeronde pakketten waarvan de gegevens de cacheduur hebben overschreden, ververst ze in batches, en registreert meteen de nieuwe zendingen van bestellingen uit de laatste 60 dagen.
2. Verversing bij bezoek: het vangnet. Als een klant zijn trackingpagina raadpleegt terwijl de gegevens verlopen zijn, wordt de API onmiddellijk bevraagd.

In beide gevallen wordt een pakket met status Geleverd of Retour afzender nooit meer bevraagd: die staten gelden als definitief.

De cron instellen

De cron-URL, inclusief token, staat bovenaan de configuratiepagina van de module. Plan ze elke 30 tot 60 minuten:

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

De optionele parameter &limit=100 begrenst het aantal API-aanroepen per uitvoering (standaard 50, maximaal 200). Het endpoint antwoordt in JSON: {"ok":true,"refreshed":12,"errors":0,"time":"…"}.

De trackingpagina aan klantzijde

De pagina is bereikbaar op het adres /order-tracking (URL aanpasbaar in Winkelparameters > Verkeer en SEO na installatie).

• Ingelogde klant: de knop “Mijn pakket volgen” verschijnt op het detail van elke bestelling, en een link “Bestelling volgen” wordt toegevoegd aan de klantzone. De module controleert systematisch of de bestelling wel bij de ingelogde klant hoort.
• Gast: een formulier vraagt de bestelreferentie en het e-mailadres. Beide moeten overeenkomen om de bestelling te tonen; bij mislukking blijft de foutmelding bewust generiek en verraadt ze nooit of de referentie bestaat.

De globale tijdlijn weerspiegelt het verst gevorderde pakket van de bestelling. Daaronder heeft elke zending haar eigen kaart: naam van de vervoerder, trackingnummer, gekleurde statusstip, gedetailleerde gebeurtenisgeschiedenis (datum, omschrijving, plaats) en link naar de officiële tracking van de vervoerder.

Genormaliseerde statussen

De labels van elke vervoerder worden omgezet naar zeven gemeenschappelijke statussen, wat een homogene weergave oplevert ongeacht het pakket:

• Wacht op afhaling: etiket aangemaakt, pakket nog niet gescand.
• Onderweg: het pakket beweegt door het netwerk.
• Wordt bezorgd: laatste etappe, bezorgronde van de dag.
• Beschikbaar in afhaalpunt: pakket wacht in een afhaalpunt of kantoor.
• Geleverd: eindstatus.
• Leveringsincident: afwijking gemeld door de vervoerder.
• Retour afzender: eindstatus.

Bestellingen met meerdere pakketten

De module leest de tabel order_carrier: elk trackingnummer dat aan de bestelling is gekoppeld, wordt behandeld als een onafhankelijke zending, met eigen connector, status en geschiedenis. Voor oudere winkels waar het trackingnummer alleen op de bestelling staat (shipping_number), zorgt een terugvalmechanisme voor compatibiliteit.

Een vervoerder toevoegen

De architectuur is bewust open. Om een extra vervoerder te integreren:

1. Maak een class in src/Adapter/ die DftrackingAbstractCarrierAdapter uitbreidt.
2. Implementeer getCode(), getLabel(), isConfigured(), getPublicUrl(), getNameKeywords() en fetch(). Die laatste geeft een array status / events / tracking_url terug, met hergebruik van de helpers httpRequest(), event() en result() van de abstracte class.
3. Voeg de class toe aan de array van DftrackingAdapterRegistry::all() en de bijbehorende require_once in dftracking.php.

De nieuwe connector verschijnt automatisch in de mappinglijsten van de back-office.

Probleemoplossing

• De pagina toont “Uw bestelling is nog niet verzonden”: er is geen trackingnummer op de bestelling ingevuld. Voeg het toe via de bestelfiche in de back-office, tabblad Transport.
• De status wordt niet bijgewerkt: controleer eerst of de crontaak draait door de URL handmatig in de browser aan te roepen: het JSON-antwoord vermeldt het aantal ververste pakketten en fouten. Raadpleeg vervolgens Geavanceerde instellingen > Logboeken: mislukte API-aanroepen worden daar geregistreerd met de melding van de vervoerder.
• Fout “tracking number not found”: normaal in de uren na het aanmaken van het etiket: de vervoerder heeft het pakket nog niet geregistreerd. De module probeert het bij de volgende cyclus opnieuw.
• Een vervoerder wordt niet herkend: de autodetectie vond geen trefwoord in de naam. Koppel hem expliciet in de sectie Vervoerdersmapping.
• Het gastformulier vindt de bestelling niet: de referentie en het e-mailadres moeten exact overeenkomen met die van de bestelling. Let op bestellingen die met een ander e-mailadres zijn geplaatst dan dat van het klantaccount.
• De pagina neemt mijn kleuren niet over: leeg de PrestaShop-cache (Geavanceerde instellingen > Prestaties) na de wijziging; de stylesheet wordt door het thema gecachet.

Verwijderen

Bij het verwijderen worden de tabel ps_dftracking_shipment en alle configuratiesleutels gewist, inclusief uw API-gegevens. Bewaar die dus vooraf als u de module later opnieuw wilt installeren.