Skip to main content
StartseiteBlogAnleitungen6 Prüfungen zur Überprüfung der neuesten über Ihre API synchronisierten Sendungsverfolgungsereignisse des Versanddienstleisters

6 Prüfungen zur Überprüfung der neuesten über Ihre API synchronisierten Sendungsverfolgungsereignisse des Versanddienstleisters

17TRACK

Um zu überprüfen, ob Ihre API die neuesten Sendungsverfolgungsereignisse des Versanddienstleisters synchronisiert hat, prüfen Sie die Sendungsidentität, die Zeitstempel der Ereignisse, die Ereignisdetails, den Zustellweg, die Reihenfolge der Ereignisse und die Aktualität anhand einer unabhängigen Tracking-Ansicht. Eine erfolgreiche API-Antwort oder Webhook-Bestätigung bestätigt nur einen Teil dieser Kette; sie beweist nicht allein, dass Ihre Anwendung über das neueste Ereignis des Versanddienstleisters verfügt.

6 Prüfungen zur Überprüfung der Synchronisierung der neuesten Tracking-Ereignisse des Versanddienstleisters

Dieser Leitfaden richtet sich an Entwickler- und Betriebsteams, die dafür verantwortlich sind, Trackingdaten in ein Auftragsverwaltungssystem, eine kundenorientierte Seite, ein Support-Tool oder einen Benachrichtigungs-Workflow zu übertragen. Ziel ist es, festzustellen, an welcher Stelle ein Ereignis verloren gegangen ist oder geändert wurde, und anschließend zu entscheiden, ob die Verarbeitung wiederholt, eine Zuordnung korrigiert oder auf neue Informationen des Versanddienstleisters gewartet werden soll.

Bevor Sie beginnen: Definieren Sie, was „aktuellste“ bedeutet

Halten Sie drei Zeitpunkte getrennt: wann der Versanddienstleister angibt, dass ein Ereignis stattgefunden hat, wann Ihr Tracking-Anbieter es empfangen oder bereitgestellt hat und wann Ihre Anwendung es gespeichert hat. Diese Zeitpunkte können voneinander abweichen. Ein Versanddienstleister kann einen Scan erst nach dem tatsächlichen Ereignis veröffentlichen, während Ihre Integration ihn noch später verarbeitet. Das neueste Ereignis nach dem Zeitpunkt seines Auftretens ist daher nicht zwangsläufig der zuletzt empfangene Datensatz.

Wählen Sie vor der Untersuchung einen Vergleichspunkt. Verwenden Sie idealerweise die Tracking-Seite des Versanddienstleisters oder einen anderen autorisierten, vom Versanddienstleister bereitgestellten Datensatz für dieselbe Sendung. Falls dies nicht möglich ist, vergleichen Sie Ihre Anwendung mit der aktuellen API-Antwort des Tracking-Anbieters. Dieser eingeschränktere Vergleich kann zeigen, ob Ihre Anwendung mit dem Anbieter übereinstimmt; er kann jedoch nicht belegen, dass der Anbieter bereits jeden Scan des Versanddienstleisters besitzt. Notieren Sie, wann Sie den Vergleich durchgeführt haben, damit ein späteres Update ein früheres Ergebnis nicht widersprüchlich erscheinen lässt.

1. Bestätigen Sie, dass beide Systeme dieselbe Sendung betreffen

Beginnen Sie mit der Sendungsnummer, dem Versanddienstleister und allen Konto- oder Sendungskennungen, die von Ihrer Integration verwendet werden. Sendungsnummern allein reichen für die Fehlerbehebung möglicherweise nicht aus: Eine Nummer kann mit einem Tippfehler eingegeben, dem falschen Versanddienstleister zugeordnet oder nach einer Bearbeitung der Bestellung in einem internen Datensatz wiederverwendet worden sein. Eine Bestellnummer und eine Sendungsnummer erfüllen außerdem unterschiedliche Zwecke. Eine Bestellung kann mehrere Pakete enthalten, sodass die Prüfung des neuesten Bestellstatus ein veraltetes Paket verbergen kann.

  • Ermitteln Sie die genaue Sendungsnummer und den Versanddienstleister, die an die Tracking-API übermittelt wurden.
  • Bestätigen Sie, welcher interne Sendungs- oder Paketdatensatz die Antwort erhalten hat.
  • Prüfen Sie, ob die Sendung nach der Registrierung ersetzt, aufgeteilt, storniert oder erneut zugeordnet wurde.
  • Vergleichen Sie den Versanddienstleister und die Nummer im Quelldatensatz mit den Angaben in Ihrer Anwendung.

Wenn die Kennungen nicht übereinstimmen, behandeln Sie die Abweichung nicht länger als Synchronisierungsverzögerung. Korrigieren Sie zunächst die Zuordnung und wiederholen Sie anschließend den Ereignisvergleich. Speichern Sie genügend Kennungen in Diagnoseprotokollen, um eine Sendung nachverfolgen zu können, ohne vertrauliche Zugangsdaten des Kontos in diesen Protokollen abzulegen.

2. Vergleichen Sie Ereigniszeiten, ohne ihre Bedeutung zu verlieren

Erfassen Sie für jedes mögliche neueste Ereignis den vom Versanddienstleister gemeldeten Zeitpunkt des Auftretens, die angegebene Zeitzone oder den Offset, sofern vorhanden, sowie die Empfangs- und Speicherzeiten Ihrer Anwendung. Konvertieren Sie Zeitstempel für den Vergleich auf eine gemeinsame Zeitbasis, behalten Sie jedoch den ursprünglichen Wert bei. RFC 3339 definiert ein Internet-Zeitstempelformat mit expliziten Offset-Informationen und ist eine nützliche Referenz beim Entwurf eigener Zeitstempelfelder. Es garantiert nicht, dass ein Versanddienstleister oder Anbieter für jedes Ereignis eine Zeitzone bereitstellt.

Eine Anzeige, die nur die Uhrzeit enthält, eine angenommene lokale Zeitzone oder ein Parser, der einen Offset stillschweigend verwirft, kann ein Ereignis auf einen anderen Kalendertag verschieben oder in die falsche Reihenfolge einordnen. Wenn die Quelle eine mehrdeutige lokale Zeit angibt, markieren Sie den Vergleich als unsicher, anstatt einen präzisen UTC-Zeitpunkt zu erfinden. Unterscheiden Sie außerdem zwischen dem Zeitpunkt des Auftretens eines Ereignisses und dem Zeitpunkt der API-Antwort: Eine jetzt abgerufene Antwort kann durchaus ein Ereignis enthalten, das früher stattgefunden hat.

Notieren Sie den Zeitpunkt, zu dem Sie die Ansicht des Versanddienstleisters oder Anbieters geprüft haben. Wenn die Quelle nach Ihrer API-Anfrage einen neuen Scan veröffentlicht hat, beweist eine Abweichung zwischen den beiden Ansichten nicht, dass die frühere Anfrage fehlgeschlagen ist.

3. Prüfen Sie die Ereignisdaten und nicht nur den übergeordneten Status

Vergleichen Sie die Beschreibung, den Ort, den Status oder Code des Versanddienstleisters sowie alle relevanten Zustellfelder des neuesten Ereignisses mit dem übergeordneten Datensatz. Ein normalisierter Status wie „unterwegs“ kann mehrere unterschiedliche Scans zusammenfassen. Wenn Ihre Anwendung nur die Zusammenfassung speichert, kann sie unverändert erscheinen, obwohl ein neues Ereignis eingegangen ist.

Überprüfen Sie die unbearbeitete API-Antwort oder den gespeicherten Webhook-Inhalt, sofern dies Ihre Regeln zur Datenverarbeitung erlauben. Verfolgen Sie das Ereignis anschließend durch Parsing, Feldzuordnung, Speicherung und Darstellung. Achten Sie darauf, ob Nullfelder durch Standardwerte überschrieben werden, unerwartete Statuscodes in eine allgemeine Kategorie fallen, Texte gekürzt werden oder eine Benutzeroberfläche nur ausgewählte Ereignistypen anzeigt. Eine Abweichung bei der Statusbezeichnung unterscheidet sich von einem fehlenden Ereignis: Sie weist eher auf eine Transformations- oder Darstellungslogik als auf ein Übermittlungsproblem hin.

Schließen Sie nicht allein aufgrund eines endgültig klingenden Orts oder Status auf eine Zustellung. Bestätigen Sie das konkrete Ereignis und die Felder, auf die sich Ihr Workflow stützt. Umgekehrt ist ein unveränderter übergeordneter Status kein Beweis dafür, dass die Synchronisierung beendet wurde; ein neu empfangener Scan kann derselben Kategorie zugeordnet werden. Ihr Diagnoseeintrag sollte sowohl das Ereignis aus der Quelle als auch den den Benutzern angezeigten Wert bewahren.

4. Verfolgen Sie, wie das Ereignis Ihre Anwendung erreicht hat

Wenn Sie Webhooks verwenden, prüfen Sie das Empfangsprotokoll für die betreffende Sendung und das betreffende Ereignis. Vergewissern Sie sich, dass Ihr Endpunkt die Anfrage akzeptiert hat, die Nachricht die Validierung bestanden hat und die nachgelagerte Verarbeitung abgeschlossen wurde. Eine erfolgreiche HTTP-Antwort Ihres Endpunkts beweist nicht, dass ein späterer Warteschlangen-Worker das Ereignis gespeichert hat. Bei asynchroner Verarbeitung sollten Sie sowohl die eingehende Anfrage als auch das Ergebnis des Jobs prüfen.

Wenn Sie eine API abfragen, prüfen Sie die letzte abgeschlossene Anfrage, die Sendungskennung in dieser Anfrage, ihre Antwort sowie jede von Ihrer Integration verwendete Seitenaufteilung oder Abruflogik. Auf eine erfolgreiche Anfrage kann dennoch ein fehlgeschriebener Datenbankschreibvorgang oder das Lesen eines veralteten Caches folgen. Verwenden Sie die einschlägige Dokumentation des Anbieters, um die tatsächlichen Antwortfelder, Authentifizierungsanforderungen und das Übermittlungsverhalten Ihrer Integration zu überprüfen, anstatt anzunehmen, dass jede Tracking-API denselben Vertrag erfüllt. Für eine 17TRACK-Integration sind die relevanten Ausgangspunkte die Tracking-API-Seite und die API-Dokumentation; bestätigen Sie das dokumentierte Verhalten für den von Ihnen verwendeten Endpunkt und die verwendete Methode.

Gestalten Sie die Ereignisverarbeitung wiederholbar. Ein erneuter Versuch sollte keine doppelten Scans erstellen, dieselbe Kundenbenachrichtigung wiederholt senden oder einen neueren gespeicherten Zustand durch eine ältere Nutzlast ersetzen. Der geeignete Schlüssel für Duplikate hängt von den Feldern ab, die Ihr Anbieter tatsächlich bereitstellt. Testen Sie den gewählten Schlüssel mit unterschiedlichen Ereignissen, die zufällig denselben Status oder Zeitstempel haben; diese Ereignisse sollten nicht allein deshalb zusammengefasst werden, weil sie ähnlich aussehen.

5. Überprüfen Sie Reihenfolge und Regeln für Zustandsübergänge

Sortieren Sie die aufgezeichneten Ereignisse nach einer klar definierten Regel und prüfen Sie anschließend das Ergebnis. Viele Anwendungen müssen zwischen dem „zuletzt eingetretenen Ereignis“ und dem „zuletzt empfangenen Ereignis“ unterscheiden. Ein verspäteter früherer Scan kann nach einem neueren Scan eintreffen. Wenn Ihre Datenbank einfach die zuletzt verarbeitete Nachricht zum aktuellen Sendungsstatus macht, kann dieser verspätete Scan den angezeigten Status zurücksetzen.

Vergleichen Sie Ihren gespeicherten Verlauf mit dem Verlauf aus der Quelle und nicht nur das einzelne Statusfeld. Fragen Sie, ob ein neu empfangener Datensatz angehängt, als Duplikat verworfen oder zur Aktualisierung des aktuellen Zustands zugelassen wurde. Prüfen Sie jede Regel, die bestimmten Ereignissen Vorrang vor anderen gibt. Eine solche Regel kann beabsichtigt sein, sollte jedoch das zugrunde liegende Ereignis nicht verbergen oder den Eindruck erwecken, dass der Versanddienstleister einen Meilenstein rückgängig gemacht hat, wenn die Anwendung lediglich einen älteren Scan verspätet empfangen hat.

Für einen praktischen Test können Sie in einer Nicht-Produktionsumgebung eine Sendung mit mehr als einem Ereignis auswählen und ihre Nachrichten in einer anderen Eingangsreihenfolge erneut abspielen. Stellen Sie sicher, dass der Ereignisverlauf vollständig bleibt und der kundenorientierte Status Ihrer dokumentierten Regel folgt. Dadurch werden Fehler bei der Reihenfolge sichtbar, die ein normaler Test in der richtigen Reihenfolge nicht aufdecken kann.

6. Messen Sie die Aktualität und gleichen Sie Ausnahmen ab

Vergleichen Sie abschließend, was jede Ebene zum selben Beobachtungszeitpunkt wusste: Ansicht des Versanddienstleisters, Antwort des Tracking-Anbieters, eingehender Webhook oder Abfrageergebnis, Datenbankdatensatz und kundenorientierte Ausgabe. Markieren Sie die erste Ebene, auf der das erwartete Ereignis verschwindet. Diese Grenze ist nützlicher als ein allgemeiner Bericht, dass „das Tracking verzögert ist“.

Messen Sie sowohl das Alter des neuesten vom Versanddienstleister gemeldeten Ereignisses als auch die Zeit seit der letzten erfolgreichen Prüfung oder dem letzten erfolgreichen Empfang von Daten durch Ihre Integration. Diese Werte beantworten unterschiedliche Fragen. Ein Paket kann keinen neuen Scan des Versanddienstleisters haben, obwohl Ihre Integration ordnungsgemäß funktioniert; alternativ kann der Versanddienstleister einen neuen Scan anzeigen, während Ihre letzte erfolgreiche Anfrage veraltet ist. Verwenden Sie Warnschwellen, die Ihren eigenen betrieblichen Anforderungen und dem beobachteten Verhalten entsprechen. Versprechen Sie Kunden kein festes Aktualisierungsintervall, sofern Ihre Vereinbarungen mit Versanddienstleistern und Anbietern dies nicht unterstützen.

Erstellen Sie eine kleine Abgleichswarteschlange für Sendungen, deren Datensätze von der gewählten Vergleichsquelle abweichen. Fügen Sie Kennungen, das fehlende oder abweichende Ereignis, relevante Zeitstempel, die erste fehlerhafte Ebene und die nächste Maßnahme hinzu. Ein Ereignis, das in der Anbieterantwort vorhanden ist, aber in Ihrer Datenbank fehlt, erfordert beispielsweise eine Untersuchung der Integration. Ein Ereignis, das in Ihrer Datenbank vorhanden ist, aber auf der Tracking-Seite fehlt, erfordert eine Prüfung der Darstellung oder des Cachings. Wenn der Versanddienstleister selbst keinen neuen Scan anzeigt, kann eine weitere API-Anfrage keinen erzeugen.

Der operative Test ist einfach: Können Sie dieselbe Sendung identifizieren, ihr zuletzt bekanntes Ereignis aus der Quelle lokalisieren und dieses Ereignis ohne Bedeutungsänderung bis zur benutzerorientierten Ansicht verfolgen? Falls nicht, grenzen die sechs Prüfungen das Problem auf eine bestimmte Grenze ein und geben Ihrem Team einen begründbaren nächsten Schritt.

FAQ

Bedeutet eine erfolgreiche Webhook-Antwort, dass das neueste Ereignis synchronisiert wurde?

Nein. Sie zeigt, dass Ihr Endpunkt eine erfolgreiche Antwort auf eine Anfrage zurückgegeben hat. Bestätigen Sie zusätzlich, dass Validierung, Warteschlangenverarbeitung, Datenbankspeicherung und Darstellung erfolgreich waren. Prüfen Sie die Nutzlast, um festzustellen, welches Ereignis die Anfrage enthielt.

Warum zeigt die Seite des Versanddienstleisters einen neueren Scan als meine API-Antwort?

Bestätigen Sie zunächst, dass Sie dasselbe Paket anzeigen und beide Beobachtungen zu vergleichbaren Zeitpunkten gemacht wurden. Die Veröffentlichung durch den Versanddienstleister und der Empfang oder die Bereitstellung eines Ereignisses durch den Tracking-Anbieter können zu unterschiedlichen Zeitpunkten erfolgen. Wenn die Abweichung bestehen bleibt, untersuchen Sie die konkrete Sendung mithilfe der Dokumentation und des Supportprozesses des Anbieters, anstatt eine Aktualisierungsgarantie anzunehmen.

Soll ich den Zeitstempel des Ereignisses oder den Zeitpunkt des Empfangs durch mein System verwenden, um den neuesten Status auszuwählen?

Verwenden Sie eine dokumentierte, für Ihren Workflow geeignete Regel und behalten Sie beide Werte bei. Der Zeitstempel des Ereignisses beschreibt, wann die gemeldete Aktivität stattgefunden hat; die Empfangszeit beschreibt, wann Ihr System davon erfahren hat. Keines der beiden Felder löst jeden Fall allein, insbesondere wenn die Quellzeiten mehrdeutig sind oder frühere Scans verspätet eintreffen.

Was ist, wenn der API-Status unverändert ist, die Ereignisliste aber einen neuen Eintrag enthält?

Das kann erwartungsgemäß sein, wenn mehrere Ereignisse des Versanddienstleisters einem normalisierten Status zugeordnet werden. Vergleichen Sie die Ereignisdetails und prüfen Sie, ob Ihre Anwendung den neuen Eintrag gespeichert und, wo angebracht, angezeigt hat. Behandeln Sie ein fehlendes Ereignis und eine unveränderte zusammenfassende Statusbezeichnung als unterschiedliche Probleme.

Quellen