Sendungsverfolgung (Tracking)
Der DHL Parcel DE Connector bietet eine vollautomatische Sendungsverfolgung über die DHL Track & Trace API v2. Sobald ein Versandlabel erstellt wurde, kann der aktuelle Zustellstatus direkt in Business Central verfolgt werden — ohne das DHL-Portal aufrufen zu müssen.
Seite öffnen
Die Tracking-Events einer Sendung werden als Timeline auf der Shipment Label Card angezeigt:
- Öffnen Sie die Versandlabels-Übersicht (über das DHL Dashboard oder die Versand-Seite).
- Klicken Sie auf ein Label mit Tracking-Nummer.
- Im unteren Bereich der Karte sehen Sie die Tracking-Timeline.
Funktionsweise
Automatische Statusabfrage (Job Queue)
Die Sendungsverfolgung arbeitet als wiederkehrende Hintergrundaufgabe:
| Eigenschaft | Beschreibung |
|---|---|
| Job Queue Entry | ALN MCDHL Job Queue Handler mit Parameter TRACKING |
| Intervall | Konfigurierbar (Standard: alle 4 Stunden) |
| Rate Limit | Maximal 250 API-Aufrufe pro Tag (DHL-Vorgabe) |
| Maximales Alter | Sendungen älter als X Tage werden nicht mehr verfolgt (Standard: 30 Tage) |
Automatische Einrichtung
Wenn Sie das Tracking in der DHL-Einrichtung aktivieren, wird der Job Queue Entry automatisch angelegt. Sie können das Abfrageintervall in der Einrichtung anpassen.
Welche Sendungen werden verfolgt?
Nicht alle Sendungen werden abgefragt. Die automatische Verfolgung betrifft nur:
- Sendungen mit dem Provider DHL Parcel DE
- Status: Created oder Manifested (also nicht stornierte oder bereits zugestellte)
- Zustellstatus: nicht bereits "Delivered" oder "Returned"
- Mit Tracking-Nummer (Sendungen ohne Nummer werden übersprungen)
- Jünger als das konfigurierte maximale Alter
Deduplizierung
Bereits bekannte Events werden nicht erneut gespeichert. Bei jedem API-Abruf werden nur neue Events hinzugefügt, sodass die Timeline stets akkurat und duplikatfrei bleibt.
Tracking-Timeline
Die Timeline zeigt alle DHL-Events chronologisch (neueste zuerst) mit farblicher Hervorhebung:
| Farbe | Event-Code | Bedeutung |
|---|---|---|
| 🟢 Grün | delivery |
Sendung zugestellt |
| 🔴 Rot | failure |
Zustellversuch fehlgeschlagen / Problem |
| ⚪ Standard | transit |
Sendung unterwegs |
| ⚪ Standard | pre-transit |
Sendung angekündigt / im System |
| ⚪ Standard | customs |
Zollbehandlung |
| ⚪ Standard | notification |
Benachrichtigung versendet |
| ⚪ Standard | pickup |
Sendung abgeholt |
| ⚪ Standard | other |
Sonstiger Statuswechsel |
Angezeigte Informationen pro Event
| Feld | Beschreibung |
|---|---|
| Datum/Uhrzeit | Zeitpunkt des Events |
| Event-Code | Kategorie (transit, delivery, failure, ...) |
| Status-Text | DHL-Kurzbeschreibung (z. B. "Sendung zugestellt") |
| Beschreibung | Detaillierte Beschreibung des Events |
| Ort | Ort des Events (z. B. "DHL Zustellbasis Frankfurt") |
| Land | Länderkürzel (z. B. "DE") |
| Signiert von | Name des Empfängers bei persönlicher Zustellung |
Status-Mapping
DHL-Events werden automatisch auf den Hub-Zustellstatus gemappt:
| DHL Event-Code | Hub Delivery Status | Beschreibung |
|---|---|---|
delivery |
Delivered | Sendung erfolgreich zugestellt |
pickup |
Picked Up | Sendung abgeholt |
failure |
Exception | Problem bei der Zustellung |
transit |
In Transit | Sendung unterwegs |
pre-transit |
In Transit | Sendung im System angekündigt |
customs |
In Transit | Sendung beim Zoll |
notification |
(unverändert) | Nur Benachrichtigung, kein Statuswechsel |
other |
(unverändert) | Kein automatischer Statuswechsel |
Der Hub-Zustellstatus ist auf der Versandlabel-Liste und der Versandlabel-Karte sichtbar.
Rückschreibung auf die gebuchte Verkaufslieferung
Jedes Tracking-Update schreibt den aktuellen Sendungsstatus zusätzlich direkt auf die gebuchte Verkaufslieferung (Posted Sales Shipment) zurück, zu der das Label gehört. Der Sachbearbeiter sieht den Zustellstatus damit unmittelbar auf der gebuchten Lieferung — ohne das Versandlabel öffnen zu müssen.
Die Informationen erscheinen auf einer neuen Inforegister-Gruppe (FastTab) Sendungsverfolgung auf der Karte "Gebuchte Verkaufslieferung":
| Feld | Beschreibung |
|---|---|
| Zustellstatus | Der gemappte Hub-Zustellstatus (z. B. In Transit, Delivered, Exception) |
| Sendungsnummer | Die Tracking-/Sendungsnummer des Versanddienstleisters |
| Tracking-URL | Direktlink zur Sendungsverfolgung des Dienstleisters |
| Letzte Aktualisierung | Zeitpunkt des letzten Tracking-Abrufs |
| Zustelldatum | Datum der erfolgreichen Zustellung (sobald gemeldet) |
Die Rückschreibung erfolgt automatisch bei jedem Polling-Zyklus.
Plattformweite Funktion
Die Status-Rückschreibung auf die gebuchte Verkaufslieferung ist eine Funktion des merchantCENTRAL Hub und gilt plattformweit für alle Shipment-Connectors (DHL, DHL Express, DPD, GLS, UPS, Hermes, Rhenus) — nicht nur für DHL.
Geschätztes Lieferdatum
Wenn DHL in der API-Antwort ein geschätztes Lieferdatum (estimatedTimeOfDelivery) mitliefert, wird dieses automatisch auf dem Shipment Label gespeichert und angezeigt. Dies hilft bei der Planung und bei Kundenanfragen.
Einrichtung
Tracking aktivieren
- Öffnen Sie die DHL Einrichtung (Setup Card) oder das DHL Dashboard.
- Navigieren Sie zur Gruppe Tracking.
- Aktivieren Sie Tracking Enabled.
- Geben Sie den Tracking API Key ein (über den DrillDown-Dialog).
Separater API-Key
Die DHL Track & Trace API v2 verwendet einen eigenen API-Key, der sich vom Shipping-API-Key unterscheidet. Sie erhalten diesen Key im DHL Developer Portal unter der App "DHL Tracking (Unified)".
Konfigurationsfelder
| Feld | Beschreibung | Standard |
|---|---|---|
| Tracking Enabled | Aktiviert/deaktiviert die automatische Verfolgung | Aus |
| Tracking API Key | API-Key für die Track & Trace API (separater Key!) | — |
| Tracking Poll Interval (Min.) | Abfrageintervall in Minuten | 240 (4 Stunden) |
| Tracking Max Age Days | Sendungen älter als X Tage werden nicht mehr verfolgt | 30 |
Job Queue verwalten
Nach der Aktivierung wird automatisch ein Job Queue Entry erstellt:
- Object: Codeunit
ALN MCDHL Job Queue Handler - Parameter:
TRACKING - Wiederholung: Alle X Minuten (gemäß Konfiguration)
Sie können den Job Queue Entry über die Standard-BC-Seite "Aufgabenwarteschlangenposten" (Job Queue Entries) verwalten — z. B. pausieren, manuell ausführen oder das Intervall anpassen.
Rate Limit und Best Practices
| Aspekt | Empfehlung |
|---|---|
| Rate Limit | 250 Aufrufe/Tag — ein Aufruf pro Sendung pro Polling-Zyklus |
| Empfohlenes Intervall | 4 Stunden (= 6 Zyklen/Tag) — bei 40 aktiven Sendungen = 240 Calls/Tag |
| Hohes Volumen | Bei >200 aktiven Sendungen das Intervall auf 6–8 Stunden erhöhen |
| Max Age | Auf 14 Tage reduzieren, wenn viele Sendungen aktiv sind |
Praxis-Tipp
Für die meisten Unternehmen reicht ein 4-Stunden-Intervall vollkommen aus. DHL-Sendungen innerhalb Deutschlands werden typischerweise in 1–2 Werktagen zugestellt. Ein kürzeres Intervall (z. B. 1 Stunde) bringt selten einen Informationsvorsprung, verbraucht aber das tägliche Rate Limit schneller.
Häufige Fragen
Warum sehe ich keine Tracking-Events?
- Tracking nicht aktiviert: Prüfen Sie "Tracking Enabled" in der DHL-Einrichtung.
- Kein Tracking API Key: Der Tracking-Key ist ein separater Key — nicht identisch mit dem Shipping API Key.
- Sendung zu neu: DHL benötigt typischerweise 30–60 Minuten nach der Label-Erstellung, bis erste Events erscheinen.
- Sendung zu alt: Sendungen älter als "Max Age Days" werden nicht mehr abgefragt.
- Job Queue pausiert: Prüfen Sie den Status des TRACKING-Job-Queue-Eintrags.
Warum steht der Status noch auf "In Transit" obwohl die Sendung zugestellt wurde?
Der Status aktualisiert sich beim nächsten Polling-Zyklus. Wenn Sie den Status sofort sehen möchten, können Sie den Job Queue Entry manuell ausführen (Seite "Aufgabenwarteschlangenposten" → Auswählen → Aktion "Ausführen").
Was passiert bei API-Fehlern?
Wenn die DHL API vorübergehend nicht erreichbar ist, wird die Sendung beim nächsten Polling-Zyklus erneut abgefragt. Dauerhafte Fehler (z. B. ungültiger API Key) werden auf der Setup Card als letzte Fehlermeldung angezeigt.