# Automatische DHL-tracking & Multi-vervoerder: volledige gids

> De module DataFirefly Tracking bevraagt de DHL-API in realtime om uw DHL eCommerce- en DHL Express-pakketten te volgen, laat de status van uw bestellingen automatisch evolueren bij levering, en biedt…

- Pagina: <https://www.datafirefly.com/nl/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/>
- Taal: nl
- Bijgewerkt op: 2026-09-10
- Andere talen: [fr](https://www.datafirefly.com/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md)
- Index: <https://www.datafirefly.com/nl/documentation/llms.txt>

De module **DataFirefly Tracking** bevraagt de DHL-API in realtime om uw DHL eCommerce- en DHL Express-pakketten te volgen, laat de status van uw bestellingen automatisch evolueren bij levering, en biedt uw klanten een trackingpagina in uw huisstijl die 19 vervoerders dekt. Deze gids behandelt de installatie, het verkrijgen van de DHL-API-sleutel, de configuratie, de cron, de trackingpagina, de statussynchronisatie, het toevoegen van vervoerders en de probleemoplossing.

## Vereisten

- PrestaShop 8.0 tot 9.x.
- PHP 8.1 tot 8.3 met de cURL-extensie actief.
- Voor de DHL-tracking: een sleutel van de DHL-API **"Shipment Tracking — Unified"** (developer.dhl.com).
- Crontoegang (geplande servertaak of crondienst) voor de automatische tracking.

De realtime tracking betreft alleen DHL eCommerce en DHL Express. De 17 andere vervoerders worden getoond met een trackinglink naar hun officiële pagina en vereisen geen enkele API-sleutel.

## Installatie

1. Open in de back-office _Modules > Module Manager_, dan _Een module uploaden_, en sleep het bestand `datafirefly_tracking.zip` erin.
2. Open na de installatie de configuratiepagina via de knop _Configureren_.

Bij de installatie maakt de module haar tabellen aan, registreert ze haar hooks en genereert ze automatisch een crontoken.

## De DHL-API-sleutel verkrijgen

1. Maak een account aan op `developer.dhl.com`.
2. Abonneer u op de API **Shipment Tracking — Unified** en maak een applicatie aan.
3. Kopieer de API-sleutel (veld _API Key_).

Het gaat wel degelijk om de sleutel van de **tracking**-API (Shipment Tracking — Unified), en niet om de DHL eCommerce-_verzendsleutel_ die voor het genereren van etiketten wordt gebruikt. Het zijn twee verschillende sleutels.

## Configuratie

De configuratiepagina bundelt de volgende instellingen:

- **DHL Tracking API Key**: plak hier uw DHL-API-sleutel.
- **Polling inschakelen**: staat automatische updates van de DHL-pakketten toe.
- **E-mails** (Verzonden, Onderweg, Geleverd, Incident): notificatievoorkeuren per statusovergang.
- **PrestaShop-status bijwerken bij levering**: activeert de automatische synchronisatie van de bestelstatus.
- **Logboekbewaring (dagen)**: bewaarduur van de logregels vóór automatische opschoning.

Sla uw instellingen op. Zolang de sleutel niet is ingevuld en de polling niet is ingeschakeld, wordt geen enkel DHL-pakket bevraagd.

## Ondersteunde vervoerders

De module herkent 19 vervoerders, verdeeld in twee categorieën.

### Realtime API-tracking (2)

DHL eCommerce en DHL Express: statussen opgehaald via de DHL-API, genormaliseerd (aangemaakt, onderweg, geleverd, incident) en getoond op een tijdlijn.

### Gebrande trackinglink (17)

Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost en PostNL: de trackingpagina toont een link naar de officiële pagina van de vervoerder, zonder API-aanroep.

De detectie gebeurt eerst via de vervoerdersmodule (`external_module_name`) en daarna via de naam van de vervoerder. Dit dekt ook handmatig geconfigureerde vervoerders zonder externe module.

## Automatisch aanmaken van de tracking

Wanneer een bestelling naar de status "Verzonden" gaat, detecteert de module de vervoerder, bepaalt ze het trackingnummer en maakt ze de trackingfiche aan. Het nummer wordt, in deze volgorde, gezocht in:

1. de vervoerdersregel van de bestelling (`order_carrier`);
2. de DHL Parcel-etiketten (indien van toepassing);
3. het DHL Express AWB-nummer (indien van toepassing).

Voor DHL-pakketten wordt de tracking vervolgens automatisch bevraagd; voor de andere vervoerders wordt eenvoudigweg een trackinglink aan de bestelling gekoppeld.

## Cronconfiguratie

De cron activeert de regelmatige polling van de DHL-pakketten en haalt de zendingen op die de hook zou hebben gemist (nummer ingevuld na de overgang naar "Verzonden", vervoerder zonder module). Plan de volgende URL elke 15 tot 30 minuten:

```
curl "https://uw-winkel.com/module/datafirefly_tracking/cron?token=UW_TOKEN"
```

Het token wordt bij de installatie gegenereerd en in de configuratie getoond. Voeg voor een eenmalige historische inhaalslag van oude bestellingen de parameter `days` toe:

```
curl "https://uw-winkel.com/module/datafirefly_tracking/cron?token=UW_TOKEN&days=60"
```

De backfill is begrensd op 180 dagen: daarbuiten schoont DHL zijn trackinggegevens op en zou het bevragen alleen "niet gevonden"-fouten opleveren.

## Het API-quotum en de rate limiter

De DHL-API is beperkt tot **250 verzoeken per dag**. De module bevat een rate limiter die:

- de aanroepen van de dag telt en de polling netjes stopt bij het plafond, om de volgende dag te hervatten;
- de bevragingen spreidt volgens de status van het pakket (frequenter bij een incident, zeldzamer voor een pakket dat alleen is aangemaakt);
- geleverde pakketten definitief niet meer bevraagt;
- een nummer opgeeft na meerdere "niet gevonden"-fouten (bijvoorbeeld een niet-DHL-nummer ingevoerd bij een DHL-vervoerder).

De dagteller is zichtbaar in de configuratie en op de bestelfiche.

## Trackingpagina aan klantzijde

Een link "Mijn pakket volgen" verschijnt in het besteldetail en het klantaccount. De gebrande trackingpagina toont een tijdlijn in 4 stappen (Verzonden, Onderweg, In bezorging, Geleverd) en het detail van de gebeurtenissen.

Ze is toegankelijk:

- voor **ingelogde klanten**, voor hun eigen bestellingen;
- voor **gasten**, via het trackingnummer samen met de bestelreferentie.

Sommige vervoerders (PostNL) vereisen de postcode van de ontvanger in de tracking-URL: de module vult die automatisch in op basis van het leveringsadres van de bestelling.

## Tracking in de back-office

Op elke bestelfiche toont een trackingtabblad de tijdlijn, de laatste gebeurtenis, de genormaliseerde status en een knop **Vernieuwen** om DHL handmatig te bevragen (binnen het quotum). Ook de link naar de officiële trackingpagina van de vervoerder en naar de front-trackingpagina wordt aangeboden.

## Synchronisatie van de bestelstatussen

Wanneer de optie _PrestaShop-status bijwerken bij levering_ actief is, laat de module de status van de bestelling voor DHL-pakketten evolueren:

- pakket **geleverd** → status "Geleverd";
- leverings**incident** → status "Fout".

De statuswijziging activeert de **native e-mails** van PrestaShop. De module voorkomt elke terugval: een al geleverde bestelling kan niet terugkeren naar "onderweg".

## Een vervoerder toevoegen

Alle vervoerders worden beschreven in een centraal register (klasse `CarrierRegistry`). Een vervoerder toevoegen komt neer op het toevoegen van één enkel item met:

- zijn interne identifier en zijn label;
- de modulenamen (`external_module_name`) en de naampatronen voor de detectie;
- zijn tracking-URL (met de markeringen `{tracking}` en, indien nodig, `{postcode}`);
- de indicator API-tracking of link, en de validatieregel van het nummer.

Geen enkel ander deel van de module hoeft te worden gewijzigd: detectie, URL, label en dashboard volgen er automatisch uit.

## Bijwerken vanaf een oudere versie

De update gebeurt door de modulebestanden te vervangen; PrestaShop past de migratiescripts automatisch toe. Versie 1.1.0 verbreedt de kolom van het vervoerderstype om de nieuwe vervoerders te kunnen opnemen: dit script is idempotent en behoudt de bestaande gegevens.

Na een update is geen herconfiguratie nodig: de API-sleutel, het crontoken en de bestaande trackingfiches blijven behouden.

## Probleemoplossing

- **Geen enkel DHL-pakket wordt gevolgd**: controleer of de API-sleutel is ingevuld, of de polling is ingeschakeld en of de cron draait.
- **Fout "ongeldige API-sleutel"**: controleer of u de sleutel van de API Shipment Tracking — Unified gebruikt, en niet de DHL eCommerce-verzendsleutel.
- **Quotum bereikt**: met 250 verzoeken/dag stopt de polling en hervat ze de volgende dag. Spreid de cron of verminder indien nodig het aantal actieve pakketten.
- **Een pakket blijft onvindbaar**: na meerdere "niet gevonden"-fouten geeft de module het nummer op (vaak een niet-DHL-nummer ingevoerd bij een DHL-vervoerder).
- **De bestelstatus verandert niet**: controleer of de statusupdate-optie actief is en of het pakket daadwerkelijk via de DHL-API wordt gevolgd.
- **Onvolledige PostNL-trackinglink**: de postcode komt uit het leveringsadres; controleer of dat op de bestelling is ingevuld.

## Deïnstallatie

Het deïnstalleren verwijdert de tracking-, logboek- en quotumtabellen van de module en haar configuratie. Voor een eenvoudige update volstaat het vervangen van de bestanden: het schema en de trackingfiches blijven behouden.