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) |
| Abrufe je Lauf | Konfigurierbar über Trackingabrufe je Lauf (Standard: 250) |
| 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: Erstellt oder Manifestiert (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.
Sendungsverfolgung je Karton
Reist eine Sendung in mehreren Kartons, hat jeder Karton bei DHL eine eigene Sendungsnummer und damit einen eigenen Weg. Der Zustellstatus der Sendung als Ganzes sagt in diesem Fall nichts darüber aus, welche Ware bereits beim Empfänger liegt. merchantCENTRAL verfolgt solche Sendungen deshalb Karton für Karton.
Wann greift das?
Automatisch, sobald zu einem Versandlabel mindestens zwei Packstücke mit eigener Sendungsnummer gehören. Eine Sendung in einem einzigen Karton wird wie bisher auf Sendungsebene verfolgt — ein Abruf für ein Paket, kein Umweg.
Was Sie sehen
Je Karton — im Inforegister Packstücke der Versandlabel-Karte und in der zentralen Packstückliste (Suche: Shipment Packages):
| Feld | Beschreibung |
|---|---|
| Zustellstatus | Wie weit dieser einzelne Karton gekommen ist. Zugestellt erscheint grün, ein Problem oder eine Retoure rot |
| Zugestellt am | Wann dieser Karton zugestellt wurde |
| Letzte Trackingaktualisierung | Wann der Status zuletzt bei DHL erfragt wurde (standardmäßig ausgeblendet) |
Auf der Auftrags- und der Lieferscheinzeile:
| Feld | Beschreibung |
|---|---|
| Zugestellte Menge | Wie viele Stück dieser Position beim Empfänger angekommen sind |
| Vollständig zugestellt am | Wann das letzte offene Stück dieser Position angekommen ist. Bleibt leer, solange noch etwas unterwegs ist (standardmäßig ausgeblendet) |
Grundlage ist die Kartonverteilung, die beim Erstellen der Etiketten erfasst wird — siehe Inhalt verteilen. Ein Artikel gilt genau dann als zugestellt, wenn der Karton zugestellt ist, in dem er liegt. Liegen mehrere Positionen im selben Karton, wechseln sie gemeinsam; Kartons, die noch unterwegs sind, lassen ihre Positionen unberührt.
Warum eine Menge und kein Häkchen
Die zugestellte Menge wird bei jedem Abruf neu berechnet, nicht hochgezählt. Geht ein Karton als Retoure zurück, sinkt die Menge entsprechend wieder. Und wird eine Position später einmal auf mehrere Kartons verteilt, bildet dieselbe Anzeige das ohne Anpassung korrekt ab.
Der Lieferschein bewahrt die Historie
Dieselben Werte stehen auf den Zeilen des gebuchten Lieferscheins. Business Central löscht einen Verkaufsauftrag, sobald er vollständig geliefert und fakturiert ist — stünde der Zustellstatus nur am Auftrag, verschwände er mit ihm.
Spalten sind zunächst unsichtbar
Zugestellte Menge erscheint auf den Auftragszeilen erst, sobald es im Mandanten überhaupt ein Versandlabel gibt. Vollständig zugestellt am ist standardmäßig ausgeblendet und lässt sich über Personalisieren einblenden.
Status der Sendung
Der Gesamtstatus des Versandlabels wird aus den Kartons abgeleitet: Zugestellt erst, wenn alle Kartons angekommen sind — solange einer feststeckt, zeigt die Sendung dessen Status. Der Lieferschein bekommt damit denselben, ehrlichen Stand.
Ein Abruf je Karton
Eine Sendung aus drei Kartons kostet drei Abrufe statt einem. Bereits zugestellte Kartons werden nicht mehr abgefragt. Planen Sie das Kontingent entsprechend — siehe Abrufkontingent.
Plattformweite Funktion
Die Verfolgung je Karton ist eine Funktion des merchantCENTRAL Hub und gilt für alle Shipment-Connectors, die Multi-Colli unterstützen — nicht nur für DHL.
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 |
Zugestellt | Sendung erfolgreich zugestellt |
pickup |
Abgeholt | Sendung abgeholt |
failure |
Ausnahme | 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 |
Sichtbar wird der Zustellstatus auf der gebuchten Verkaufslieferung (Inforegister Sendungsverfolgung, siehe unten) und — je Karton — im Inforegister Packstücke der Versandlabel-Karte sowie in der Packstückliste.
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 aktiviert.
Mehr ist im Normalfall nicht zu tun.
Kein zweiter API-Schlüssel nötig
Ein Schlüssel im DHL Developer Portal gilt für alle APIs, die in derselben Anwendung freigeschaltet sind — also auch für die Track & Trace API. Der Connector verwendet daher den Schlüssel der Versand-Zugangsdaten.
Das Feld Tracking API Key (optional) brauchen Sie nur, wenn das Tracking über eine eigene Anwendung laufen soll, etwa um die Abrufkontingente getrennt zu halten.
Keine Sandbox
Die Track & Trace API gibt es nur produktiv (api-eu.dhl.com). Im Sandbox-Modus erzeugte Testsendungen existieren dort nicht und liefern deshalb keine Events.
Konfigurationsfelder
| Feld | Beschreibung | Standard |
|---|---|---|
| Tracking aktiviert | Aktiviert/deaktiviert die automatische Verfolgung | Aus |
| Tracking Poll Interval (Min.) | Abfrageintervall in Minuten | 240 (4 Stunden) |
| Tracking Max Age Days | Sendungen älter als X Tage werden nicht mehr verfolgt | 30 |
| Trackingabrufe je Lauf | Wie viele Abrufe ein einzelner Hintergrundlauf an DHL senden darf | 250 |
| Tracking API-Basis-URL | Basis-URL der Track & Trace API | https://api-eu.dhl.com |
| Tracking API Key (optional) | Eigener Schlüssel für die Track & Trace API. Leer lassen, um den Schlüssel der Versand-Zugangsdaten zu verwenden | — |
| Job Queue Status | Zustand des TRACKING-Auftrags (Aktiv, Angehalten, Fehler, Nicht eingerichtet) | — |
Die Detailfelder erscheinen erst, wenn Tracking aktiviert eingeschaltet ist.
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.
Abrufkontingent und Best Practices
Das Kontingent bei DHL
DHL vergibt das Kontingent pro Anwendung im Developer Portal, nicht pro Connector:
| Startkontingent | 250 Abrufe pro Tag, höchstens ein Abruf alle fünf Sekunden. DHL bezeichnet das ausdrücklich als Entwicklungskontingent |
| Produktivbetrieb | Für den Echtbetrieb sieht DHL eine Anhebung vor, die Sie über Ihre Anwendung im Developer Portal beantragen |
| Faustformel von DHL | Tägliches Sendungsvolumen ÷ 30 × 3 Transporttage × 10 Abfragen je Sendung und Tag |
| Sammelabfrage | Nicht möglich — die DHL-API beantwortet eine Sendungsnummer je Anfrage |
Vor dem Echtbetrieb beantragen
Das Startkontingent reicht für Tests, nicht für den laufenden Versand. Bei 30 Aufträgen täglich mit je drei Kartons liegt der Bedarf bereits in der Größenordnung von 2.500 bis 3.000 Abrufen pro Tag. Beantragen Sie die Anhebung, bevor Sie produktiv gehen.
Die Grenze im Connector
Trackingabrufe je Lauf begrenzt, wie viele Abrufe ein einzelner Hintergrundlauf absetzt. Die Vorgabe 250 entspricht dem Startkontingent von DHL.
- Ist die Grenze erreicht, bricht der Lauf ab; die verbleibenden Sendungen folgen im nächsten Durchlauf. Die ältesten Sendungen kommen zuerst.
- Heben Sie den Wert an, sobald DHL Ihr Kontingent angehoben hat — sonst entscheidet weiterhin diese Einstellung darüber, wie viele Sendungen ein Lauf schafft, und nicht das Kontingent.
- Gezählt werden Abrufe, nicht Sendungen: Eine Sendung aus drei Kartons kostet drei Abrufe.
Intervall und Alter
| Aspekt | Empfehlung |
|---|---|
| Empfohlenes Intervall | 4 Stunden (= 6 Läufe/Tag) |
| Hohes Volumen | Intervall auf 6–8 Stunden erhöhen, statt die Abrufgrenze immer wieder zu erreichen |
| Max Age | Auf 14 Tage reduzieren, wenn viele Sendungen gleichzeitig 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 das Kontingent aber deutlich schneller.
Häufige Fragen
Warum sehe ich keine Tracking-Events?
- Tracking nicht aktiviert: Prüfen Sie Tracking aktiviert in der DHL-Einrichtung.
- Sandbox-Sendung: Für die Track & Trace API gibt es keine Sandbox. Sendungen, die im Sandbox-Modus erzeugt wurden, existieren dort nicht.
- Track & Trace nicht freigeschaltet: Prüfen Sie im DHL Developer Portal, ob Ihre Anwendung neben der Shipping API auch die Shipment Tracking (Unified) API enthält.
- 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").
Warum steht auf einer Auftragsposition keine zugestellte Menge?
- Die Spalte fehlt: Zugestellte Menge erscheint erst, wenn es im Mandanten mindestens ein Versandlabel gibt. Vollständig zugestellt am ist standardmäßig ausgeblendet — über Personalisieren einblenden.
- Kein Kartoninhalt erfasst: Die Menge entsteht aus der Zuordnung Artikel → Karton. Wurde beim Erstellen der Etiketten kein Inhalt verteilt, gibt es nichts, worauf sich ein Zustellstatus beziehen könnte.
- Karton noch unterwegs: Erst wenn der Karton den Status Zugestellt hat, zählt sein Inhalt. Das Inforegister Packstücke auf der Versandlabel-Karte zeigt, welcher Karton noch aussteht.
- Position geht nicht per DHL: Artikel, die über eine Spedition oder einen anderen Weg laufen, liegen in keinem DHL-Karton und bekommen daher keinen Zustellstatus.
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.