So erhalten Sie den neuesten Sendungsstatus über die API, ohne auf einen Webhook zu warten
Um den neuesten verfügbaren Versandstatus zu erhalten, ohne auf einen Webhook zu warten, senden Sie eine authentifizierte Anfrage an die Versandabfrage-API Ihres Tracking-Anbieters. Verwenden Sie die Antwort, um Ihre Anwendung sofort zu aktualisieren, und lassen Sie Webhooks anschließend für weitere Änderungen aktiviert. Der wichtige Unterschied besteht darin, dass eine Abfrage normalerweise die zuletzt gespeicherten Tracking-Informationen des Anbieters abruft; sie löst nicht zwangsläufig eine neue Abfrage beim Versanddienstleister aus.

Dieser Ansatz ist nützlich, wenn ein Kunde eine Bestellseite öffnet, ein Supportmitarbeiter eine Aktualisierung benötigt oder Ihr System sich von einer verpassten Benachrichtigung erholen muss. Eine zuverlässige Implementierung kombiniert bedarfsgesteuerte Abfragen, eindeutige Aktualitätsanzeigen und Schutzmechanismen gegen doppelte oder ungeordnet eintreffende Aktualisierungen.
Definieren Sie, was „neuester Versandstatus“ bedeutet
Bevor Sie einen Endpunkt auswählen, unterscheiden Sie zwischen drei Vorgängen, die ähnlich klingen können, aber unterschiedliche Ergebnisse liefern.
| Vorgang | Was er tut | Was er nicht feststellt |
|---|---|---|
| Eigene Datenbank auslesen | Gibt Tracking-Informationen zurück, die Ihre Anwendung bereits gespeichert hat. | Ob der Anbieter eine neuere Aktualisierung erhalten hat. |
| Tracking-API abfragen | Ruft Informationen ab, die über die Abfragefunktion des Anbieters verfügbar sind. | Ob während dieser Anfrage eine neue Abfrage beim Versanddienstleister stattgefunden hat. |
| Tracking-Aktualisierung anfordern | Fordert eine weitere vorgelagerte Prüfung an, sofern der Anbieter diese Funktion anbietet. | Dass der Versanddienstleister einen neuen Scan vorgenommen hat oder dass die Aktualisierung synchron abgeschlossen wird. |
Verwenden Sie eine Abfrage, wenn Sie jetzt eine Antwort benötigen. Prüfen Sie eine Aktualisierungsfunktion nur dann, wenn der Anbieter eine weitere vorgelagerte Prüfung durchführen soll. Gehen Sie nicht davon aus, dass das Hinzufügen eines Cache-Busting-Parameters, das Wiederholen einer Anfrage oder das Senden eines HTTP-Cache-Control-Headers den Versanddienstleister dazu zwingt, neue Informationen bereitzustellen.
Die Transparenz des Versandstatus umfasst mehrere Stufen: Der Versanddienstleister erfasst ein Ereignis, der Tracking-Anbieter erhält es und Ihre Anwendung empfängt oder ruft es ab. Eine direkte API-Anfrage kann die Wartezeit auf die Zustellung einer Benachrichtigung umgehen, aber Verzögerungen in früheren Stufen dieser Kette nicht beseitigen.
Prüfen Sie den Abfragevertrag, bevor Sie Code schreiben
Der Entwickler, der den Tracking-Dienst integriert, ist für diesen Ablauf verantwortlich. Beginnen Sie mit der aktuellen Dokumentation des Anbieters und nicht mit einem Endpunkt, der aus einem alten Integrationsbeispiel kopiert wurde. Bestätigen Sie folgende Details:
- Identität der Sendung: Akzeptiert die Abfrage eine Trackingnummer, eine interne Sendungs-ID oder eine Trackingnummer zusammen mit einer Versanddienstleisterkennung?
- Registrierungsanforderungen: Muss die Sendung registriert werden, bevor sie abgefragt werden kann?
- Authentifizierung: Welcher Header oder Authentifizierungsmechanismus ist erforderlich?
- Bedeutung der Antwort: Gibt der Vorgang gespeicherte Informationen zurück, startet er eine Datenerfassung oder gibt er einen Auftrag zurück, der später geprüft werden muss?
- Ergebnisverarbeitung: Kann eine erfolgreiche HTTP-Antwort einen Fehler auf Sendungsebene oder ein ausstehendes Ergebnis enthalten?
- Nutzungsbeschränkungen: Welche Ratenlimits, Batch-Limits und kontospezifischen Einschränkungen gelten?
- Felder zur Aktualität: Welche Zeitstempel stehen für Ereignisse des Versanddienstleisters, Aktualisierungen des Anbieters und die Erstellung der Antwort?
Für eine 17TRACK-Integration ist die Tracking API das relevante Produkt und nicht eine Verbraucherseite zur Sendungsverfolgung oder eine Tracking-Oberfläche eines Shops. Verwenden Sie die offizielle API-Dokumentation, um den Vorgang zur Abfrage von Tracking-Informationen, die Authentifizierung, Anfragefelder und Antwortstruktur für Ihre Integration zu bestätigen. Behandeln Sie Abfragen und die Verarbeitung von Webhooks als getrennte Anwendungspfade, die denselben Sendungsdatensatz aktualisieren.
Vermeiden Sie fest codierte Annahmen über das Aktualisierungsverhalten oder die Abfragehäufigkeit. Diese Details müssen dem tatsächlich verwendeten Vorgang und den geltenden Servicebedingungen entsprechen.
Implementieren Sie eine bedarfsgesteuerte Abfrage über Ihr Backend
Ein praktischer Aufbau besteht darin, in Ihrer eigenen Anwendung einen authentifizierten Endpunkt bereitzustellen. Der Browser fordert über diesen Endpunkt eine Aktualisierung der Sendung an; Ihr Server prüft die Berechtigung, entscheidet, ob eine Anbieterabfrage erforderlich ist, und gibt ein normalisiertes Ergebnis zurück.
Die folgende Route ist ein Beispiel für einen Endpunkt, den Sie in Ihrer Anwendung erstellen könnten. Sie ist kein 17TRACK-Endpunkt und keine Spezifikation für eine Anbieteranfrage.
GET /api/orders/{order_id}/shipment-statusVerwenden Sie die Bestellkennung, um die Sendung auf dem Server zu ermitteln. Ermöglichen Sie es einem Aufrufer nicht, allein durch das Ersetzen einer Trackingnummer in einer Anfrage die Tracking-Historie eines anderen Kunden abzurufen. Bewahren Sie die API-Zugangsdaten des Anbieters in Ihrem Backend auf und nicht in Browser-JavaScript oder einem mobilen Anwendungspaket.
Ein implementierbarer Anfrageablauf
- Zugriff autorisieren. Bestätigen Sie, dass der Kunde oder Mitarbeiter die Bestellung anzeigen darf.
- Sendung ermitteln. Lesen Sie die gespeicherte Trackingkennung und gegebenenfalls die Informationen zum Versanddienstleister aus.
- Lokale Aktualität prüfen. Wenn bereits eine erfolgreiche aktuelle Abfrage vorliegt, verwenden Sie sie gemäß der Aktualitätsrichtlinie Ihrer Anwendung erneut.
- Anbieter bei Bedarf abfragen. Verwenden Sie den dokumentierten Vorgang und ein begrenztes Anfrage-Timeout.
- Ergebnis validieren. Prüfen Sie sowohl das HTTP-Ergebnis als auch das Ergebnis auf Sendungsebene.
- Informationen zusammenführen. Wenden Sie dieselben Normalisierungs- und Abgleichregeln an, die für Webhook-Ereignisse verwendet werden.
- Status und Aktualität zurückgeben. Fügen Sie, sofern verfügbar, die Zeit des neuesten Ereignisses und den Zeitpunkt der letzten erfolgreichen Anbieterprüfung hinzu.
Die lokale Aktualitätsrichtlinie ist eine technische Entscheidung und keine Aussage über die Häufigkeit von Aktualisierungen durch den Versanddienstleister. Legen Sie sie anhand Ihrer Anforderungen an die Benutzeroberfläche, der Anbieterlimits, des Sendungsvolumens und des beobachteten Nutzens von Abfragen fest. Wiederholtes Klicken eines Kunden auf eine Aktualisierungsschaltfläche darf keinen unbeschränkten Strom vorgelagerter Anfragen erzeugen.
Antwort normalisieren, ohne Aktualität zu erfinden
Ihre Anwendung kann ein stabiles internes Format zurückgeben, selbst wenn sich die Antwortstrukturen der Anbieter unterscheiden. Dieses beispielhafte Objekt ist Ihr eigener Anwendungvertrag und keine tatsächliche Anbieter-Payload:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}Füllen Sie jeden Zeitstempel nur dann aus, wenn seine Bedeutung bekannt ist. Der Zeitpunkt, zu dem Ihr Server eine Antwort erhalten hat, gehört in die Metadaten Ihrer Abfrage und darf nicht als Zeitpunkt dargestellt werden, zu dem sich das Paket bewegt hat. Wenn der Anbieter keinen Zeitstempel für seine Aktualisierung bereitstellt, lassen Sie dieses Feld weg oder auf null gesetzt, anstatt einen anderen Zeitstempel einzusetzen.
Trennen Sie in der Kundenoberfläche die Meldungen: „Letztes Ereignis des Versanddienstleisters“ beschreibt die Aktivität der Sendung, während „Tracking geprüft“ die Abrufaktivität Ihrer Anwendung beschreibt. Diese Unterscheidung verhindert, dass ein unveränderter Scan als neu erfasst erscheint.
Verhindern Sie, dass API-Abfragen und Webhooks sich gegenseitig überschreiben
Sobald beide Mechanismen aktiv sind, kann dasselbe Ereignis über eine Abfrage und einen Webhook eintreffen. Sie können außerdem in einer anderen Reihenfolge abgeschlossen werden als gestartet. Eine zuerst gestartete Abfrage kann abgeschlossen werden, nachdem ein Webhook bereits neuere Informationen geliefert hat.
Verwenden Sie keine Logik nach dem Muster „letzte Antwort gewinnt“. Die zuletzt empfangene Payload stellt nicht zwangsläufig den neuesten Sendungsstatus dar.
- Eine gemeinsame Aktualisierungspipeline verwenden. Führen Sie Abfrageergebnisse und Webhook-Payloads durch dieselben Validierungs-, Normalisierungs- und Persistenzfunktionen.
- Ereignisse deduplizieren. Bevorzugen Sie eine dokumentierte Ereigniskennung. Falls keine vorhanden ist, erstellen Sie aus verfügbaren Feldern wie Ereigniszeit, Status, Ort und Beschreibung einen sorgfältig definierten Fingerabdruck.
- Sortierungsfelder mit bekannter Bedeutung verwenden. Eine dokumentierte Revision oder Sequenz ist hilfreicher, als anzunehmen, dass die Empfangszeit die Reihenfolge der Ereignisse darstellt.
- Historie bewahren. Ein neu empfangenes Ereignis kann eine historische Lücke schließen, ohne die aktuelle Zusammenfassung der Sendung zu ändern.
- Korrekturen zulassen. Statuswerte bilden keine universelle lineare Abfolge. Befolgen Sie das dokumentierte Korrekturverhalten, anstatt jede scheinbare Rückwärtsänderung dauerhaft abzulehnen.
Wenn die Reihenfolge der Ereignisse unklar ist, bewahren Sie die ursprüngliche Payload und ihre Herkunft zur Untersuchung auf. Lösen Sie Mehrdeutigkeiten nicht, indem Sie einen Ereigniszeitstempel erfinden oder annehmen, dass alle Zeitstempel des Versanddienstleisters dieselbe Zeitzone verwenden.
Behandeln Sie fehlende Daten und fehlgeschlagene Anfragen unterschiedlich
Ein leeres Ergebnis, ein unverändertes Ergebnis und eine fehlgeschlagene Anfrage dürfen nicht dieselbe Kundenmeldung erzeugen.
Die Abfrage ist erfolgreich, aber der Status hat sich nicht geändert
Behalten Sie den bestehenden Sendungsstatus bei und aktualisieren Sie den Zeitpunkt der letzten erfolgreichen Abfrage. Erzeugen Sie kein neues Sendungsereignis, nur weil eine weitere Abfrage abgeschlossen wurde. Wenn der Kunde mehr Details benötigt, zeigen Sie die vorhandene Ereignishistorie und erklären Sie, dass kein neueres Tracking-Ereignis zurückgegeben wurde.
Für die Sendung liegen noch keine Tracking-Informationen vor
Prüfen Sie, ob eine Registrierung erforderlich ist, ob Kennung und Versanddienstleister korrekt sind und wie der Anbieter eine ausstehende Erfassung darstellt. Das Fehlen von Ereignissen beweist allein nicht, dass die Trackingnummer ungültig ist oder das Paket verloren ging. Bewahren Sie die Unterscheidung des Anbieters zwischen einer unbekannten Kennung, einer registrierten Sendung, die auf Informationen wartet, und einer Anfrage, die nicht verarbeitet werden konnte.
Die Anbieteranfrage läuft ab oder schlägt fehl
Wenn ein zuvor gültiger Status vorhanden ist, geben Sie ihn mit einem ausdrücklichen Hinweis zurück, dass die letzte Prüfung nicht erfolgreich war. Behalten Sie den Zeitpunkt der früheren erfolgreichen Abfrage unverändert bei. Ein Netzwerkfehler ist keine Zustellausnahme und darf den geschäftlichen Status des Pakets nicht ändern.
Verwenden Sie für geeignete vorübergehende Fehler begrenzte Wiederholungsversuche mit Backoff und Jitter. Wiederholen Sie ungültige Zugangsdaten oder fehlerhafte Anfragen nicht wiederholt. Wenn eine Antwort Retry-After enthält, interpretieren Sie diesen Wert gemäß dem Vertrag des Anbieters und den HTTP-Semantiken. Die HTTP-Spezifikation erlaubt, diesen Wert als Verzögerung in Sekunden oder als HTTP-Datum auszudrücken.
Mehrere Anfragen für dieselbe Sendung treffen ein
Fassen Sie gleichzeitige Abfragen zusammen, damit sie eine gemeinsame vorgelagerte Anfrage nutzen können. Wenden Sie Limits pro Konto und Sendung an und verhindern Sie, dass sich ein automatischer Wiederholungsversuch über mehrere Anwendungsebenen vervielfacht. Wenn Stapelverarbeitung unterstützt wird, prüfen Sie das Ergebnis jeder Sendung einzeln, anstatt den gesamten Batch als erfolgreich zu behandeln, nur weil die HTTP-Anfrage abgeschlossen wurde.
Polling als kontrollierte Ausweichlösung verwenden
Ohne Webhooks kann geplantes Polling Ihre Datenbank aktuell halten, erfordert jedoch eine ausdrücklich festgelegte Betriebsrichtlinie. Entscheiden Sie, welche Sendungen weiterhin berücksichtigt werden, wie sich Fehler auf den Zeitplan auswirken und wann das reguläre Polling endet.
Für die meisten Integrationen ist ein hybrider Aufbau ein sinnvoller Ausgangspunkt: Webhooks verarbeiten Hintergrundänderungen, bedarfsgesteuerte Abfragen bedienen interaktive Anfragen und Abgleichaufträge prüfen Datensätze, die Aufmerksamkeit benötigen. Dies ist eine Architektur Empfehlung und keine Garantie dafür, dass die Kosten für jedes Konto minimiert werden.
- Priorisieren Sie aktive Sendungen und Datensätze mit ungelösten Abruffehlern.
- Vermeiden Sie es, bei jedem geplanten Lauf jede historische Sendung abzufragen.
- Definieren Sie, wie abgeschlossene Sendungen behandelt werden, einschließlich eines von Ihrem Unternehmen benötigten Korrekturzeitraums.
- Verfolgen Sie, wie oft Abfragen tatsächlich neue Informationen finden.
- Untersuchen Sie Probleme bei der Webhook-Zustellung, anstatt sie durch immer häufigeres Polling zu verschleiern.
Überwachen Sie die Latenz von Anbieteranfragen, erfolglose Abfragen, Antworten auf Ratenlimits sowie Unterschiede zwischen abgefragten Daten und über Webhooks gespeisten Datensätzen. Überwachen Sie außerdem separat das Alter des letzten Ereignisses des Versanddienstleisters. Erfolgreiche API-Antworten können mit unveränderten Tracking-Informationen einhergehen.
Testen Sie den Ablauf vor der Veröffentlichung
Eine erfolgreiche Anfrage ist nur der erste Test. Überprüfen Sie Situationen, die andernfalls irreführende Statusaktualisierungen erzeugen können:
- Ein Webhook trifft ein, während eine bedarfsgesteuerte Abfrage noch läuft.
- Zwei Kunden- oder Mitarbeitersitzungen fordern gleichzeitig dieselbe Sendung an.
- Der Anbieter gibt HTTP-Erfolg zurück, meldet jedoch einen Fehler auf Sendungsebene.
- Eine Anfrage schlägt fehl, nachdem Ihre Anwendung bereits gültige Tracking-Informationen gespeichert hat.
- Ein Ereignis enthält keine Zeitzone oder einen unbekannten Statuscode.
- Eine Korrektur des Versanddienstleisters ändert ein zuvor angezeigtes Ergebnis.
- Ein Benutzer versucht, auf eine Sendung eines anderen Kontos zuzugreifen.
Ihr Freigabekriterium sollte sein, dass die Anwendung die bestmöglichen bekannten Versandinformationen zurückgibt, deren Aktualität korrekt erklärt und diese Informationen nicht beschädigt, wenn Anfragen fehlschlagen oder in falscher Reihenfolge eintreffen.
FAQ
Erzwingt eine API-Abfrage, dass der Versanddienstleister ein Paket scannt oder aktualisiert?
Nein. Das Abrufen von Tracking-Informationen kann keinen physischen Scan auslösen. Ob eine Anfrage eine vorgelagerte Abfrage auslöst, hängt vom dokumentierten Vorgang ab. Selbst eine unterstützte Aktualisierung kann unveränderte Informationen zurückgeben, wenn kein neueres Ereignis beim Versanddienstleister vorliegt.
Kann ich API-Abfragen verwenden, ohne Webhooks zu konfigurieren?
Wenn der Anbieter den erforderlichen Abfrageablauf unterstützt, können Sie eine Integration auf Basis bedarfsgesteuerter Anfragen oder von Polling erstellen. Bestätigen Sie zuerst die Registrierungs- und Abfrageanforderungen. Danach ist Ihre Anwendung dafür verantwortlich, zu entscheiden, wann geprüft wird, das Anfragevolumen zu kontrollieren und Änderungen zu erkennen.
Wie oft sollte ich den Versandstatus abfragen?
Es gibt kein universelles Intervall. Wählen Sie einen Zeitplan, der zu den Limits Ihres Anbieters, Ihrem Sendungsvolumen und dem geschäftlichen Nutzen schnellerer Aktualisierungen passt. Messen Sie, wie oft das Polling neue Ereignisse zurückgibt, und passen Sie den Zeitplan entsprechend an, anstatt anzunehmen, dass häufige Anfragen aktuellere Daten des Versanddienstleisters liefern.
Warum gibt die API Informationen zurück, die ich bereits über einen Webhook erhalten habe?
Beide Pfade können denselben zugrunde liegenden Sendungsdatensatz offenlegen. Ein Webhook liefert eine Benachrichtigung, während eine Abfrage Informationen bei Bedarf abruft. Dasselbe Ereignis über beide Wege zu erhalten, ist nicht zwangsläufig ein Fehler; Ihre Anwendung sollte es deduplizieren.
Sollte die Aktualisierungsschaltfläche „Tracking aktualisieren“ heißen?
Nur wenn diese Bezeichnung den Vorgang korrekt beschreibt. Wenn die Schaltfläche gespeicherte Daten des Anbieters abruft, ist „Auf Aktualisierungen prüfen“ eindeutiger. Zeigen Sie das letzte Ereignis des Versanddienstleisters getrennt vom Zeitpunkt an, zu dem Ihre Anwendung zuletzt eine erfolgreiche Prüfung abgeschlossen hat.
Quellen
- 17TRACK Tracking API — offizielle Produktreferenz für die in diesem Leitfaden besprochene Tracking-API-Integration.
- 17TRACK API-Dokumentation — Referenz für anbieterspezifische Vorgänge, Authentifizierung, Anfragefelder und Antwortverarbeitung.
- RFC 9110, Abschnitt 10.2.3: Retry-After — definiert die Formen des HTTP-Headers als Verzögerung in Sekunden und als HTTP-Datum.


