StartseiteBlogAnleitungenSo verwenden Sie die UPS Tracking API: Schritt-für-Schritt-Einrichtungsanleitung

So verwenden Sie die UPS Tracking API: Schritt-für-Schritt-Einrichtungsanleitung

17TRACK

Um die UPS Tracking API zu verwenden, erstellen Sie ein UPS Developer-Konto, registrieren Sie eine Anwendung, erhalten Sie OAuth-2.0-Zugangsdaten, fordern Sie ein Zugriffstoken an und senden Sie authentifizierte Tracking-Anfragen mit einer gültigen UPS-Trackingnummer. Die genauen Bezeichnungen im Portal, Genehmigungsschritte und API-Anforderungen können sich ändern. Bestätigen Sie daher die aktuellen Anweisungen im offiziellen UPS Developer Portal, bevor Sie eine Produktionsintegration aktivieren.

So verwenden Sie die Ups Tracking Api Schritt für Schritt

Dieser Leitfaden richtet sich an Entwickler und E-Commerce-Teams, die den Sendungsstatus in einem Onlineshop, einem Auftragsverwaltungssystem, einem Lager-Workflow, einem Kundenservice-Tool oder einem internen Dashboard benötigen. Der Schwerpunkt liegt auf der Integrationsabfolge, den Entscheidungen, die sich auf die Zuverlässigkeit auswirken, und den Prüfungen, die häufige Tracking-Fehler verhindern.

Was die UPS Tracking API leistet

Eine API-Integration ermöglicht es Software, Sendungsinformationen von UPS anzufordern, anstatt dass ein Mitarbeiter oder Kunde die Tracking-Seite des Versanddienstleisters manuell öffnen muss. Ihre Anwendung kann die Antwort verwenden, um den zuletzt bekannten Status anzuzeigen, Zustellereignisse zu identifizieren, Untersuchungen durch den Kundenservice zu unterstützen oder einen internen Workflow auszulösen.

Die API ist nicht dasselbe wie eine Tracking-Seite. Eine Tracking-Seite ist dafür konzipiert, von einer Person gelesen zu werden. Eine API-Antwort besteht aus strukturierten Daten, die von Software analysiert, gespeichert und dargestellt werden müssen. Ihr System bleibt für Authentifizierung, Fehlerbehandlung, Abrufe oder Ereigniserfassung, Datenaufbewahrung, Benutzeroberflächendesign und alle auf Zustellereignissen basierenden Geschäftsregeln verantwortlich.

Vorbereitung

Bereiten Sie die folgenden Punkte vor, bevor Sie das Developer Portal öffnen:

  • Ein UPS Developer-Konto oder den Kontotyp, der im aktuellen UPS-Onboarding-Prozess erforderlich ist.
  • Eine registrierte Anwendung und die für diese Anwendung ausgestellten Zugangsdaten.
  • Eine Test-Trackingnummer oder eine andere genehmigte Testmethode. Beginnen Sie nicht mit Live-Kundendaten, wenn die UPS-Dokumentation eine separate Testumgebung oder ein Testverfahren vorsieht.
  • Eine klare Entscheidung darüber, welches System für Sendungsdatensätze, Trackingereignisse und kundenorientierte Statusmeldungen zuständig ist.
  • Einen sicheren Ort zur Speicherung von Client-Zugangsdaten und Zugriffstoken. Platzieren Sie Geheimnisse niemals in Browsercode, öffentlichen Repositories, Screenshots oder mobilen Anwendungen, die von Benutzern eingesehen werden können.

Sie sollten außerdem entscheiden, ob Ihre Anwendung nur Tracking oder eine umfassendere UPS-Integration benötigt. Tracking, Tarifberechnung, Versand, Adressvalidierung und Dokumentdienste können unterschiedliche Produkte, Berechtigungen, Anfrageformate und betriebliche Anforderungen haben.

Schritt 1: Öffnen Sie das UPS Developer Portal

Beginnen Sie beim offiziellen UPS Developer Portal. Prüfen Sie den aktuellen API-Katalog, die Hinweise zur Authentifizierung, Onboarding-Anforderungen, Bedingungen und Informationen zu den Umgebungen. Suchen Sie gezielt nach der Dokumentation zur Tracking API, anstatt anzunehmen, dass die Anweisungen für einen anderen UPS-Dienst auch für Tracking gelten.

Das Portal ist die maßgebliche Quelle für aktuelle Anfragefelder, Autorisierungsbereiche, Antwortdefinitionen, Ratenlimits, Fehlercodes und Umgebungsdetails. Diese Angaben können sich ändern, und ein Codebeispiel eines Drittanbieters kann eine ältere UPS-Schnittstelle oder eine veraltete Authentifizierungsmethode verwenden.

Schritt 2: Registrieren Sie eine Anwendung

Erstellen Sie im Developer Portal eine Anwendung und wählen Sie die UPS-APIs aus, die die Anwendung tatsächlich benötigt. Für ein reines Tracking-Projekt sollten Sie nur die Tracking-Funktion anfordern, sofern Ihr Workflow keine zusätzlichen Dienste benötigt. Die Beschränkung der Berechtigungen reduziert die Konfigurationskomplexität und erleichtert die spätere Fehlerbehebung.

Speichern Sie die Anwendungs-ID und das Geheimnis in einem serverseitigen Secret-Manager oder einem geschützten System für Umgebungsvariablen. Behandeln Sie das Geheimnis wie ein Passwort. Falls es offengelegt wird, rotieren Sie es über den von UPS bereitgestellten Prozess und prüfen Sie die Protokolle auf unbefugte Nutzung.

Falls das Portal nach Konto-, Abrechnungs-, Geschäfts- oder Anwendungsinformationen fragt, geben Sie korrekte Angaben an. Erfinden Sie keinen Produktionsanwendungsfall und verwenden Sie nicht einfach die Kontoinformationen einer anderen Person, nur um einen Test abzuschließen. Der Zugriff auf einen Dienst kann von der Kontokonfiguration und dem aktuellen Genehmigungsprozess von UPS abhängen.

Schritt 3: Implementieren Sie die OAuth-2.0-Authentifizierung

Die aktuelle UPS-Entwicklerdokumentation verwendet für ihre APIs eine OAuth-basierte Authentifizierung. Ihr Server tauscht die Anwendungszugangsdaten normalerweise über den dokumentierten Token-Ablauf aus und erhält ein Zugriffstoken. Anschließend fügt er dieses Token in den Authorization-Header einer API-Anfrage ein.

Halten Sie die Authentifizierung von der Trackinglogik getrennt. Ein praktisches Design umfasst eine Komponente, die ein gültiges Token abruft und zwischenspeichert, sowie eine weitere Komponente, die den Tracking-Endpunkt aufruft. Die Token-Komponente sollte:

  • Zugangsdaten nur an den dokumentierten UPS-Autorisierungsendpunkt senden.
  • Den in der aktuellen UPS-Dokumentation angegebenen Inhaltstyp und die dort festgelegten Grant-Parameter verwenden.
  • Das Token vorübergehend speichern und bis zu seinem Ablauf wiederverwenden, anstatt für jede Trackingnummer ein neues Token anzufordern.
  • Das Token aktualisieren oder erneut abrufen, sobald die dokumentierte Ablaufbedingung eintritt.
  • Zugangsdaten und Token aus Anwendungsprotokollen, Fehlerberichten und Support-Tickets entfernen.

Kopieren Sie kein Token aus einer Browsersitzung in eine dauerhafte Integration. Ein Backend-Dienst ist im Allgemeinen ein sichererer Ort für die Verwaltung von Zugangsdaten, da Geheimnisse so vom öffentlichen Clientcode ferngehalten werden.

Schritt 4: Erstellen Sie die Tracking-Anfrage

Verwenden Sie das im offiziellen Referenzhandbuch der Tracking API gezeigte Anfrageformat. Eine typische Anfrage enthält eine Trackingnummer im Pfad oder in den Anfrageparametern, ein Zugriffstoken im Authorization-Header und die von der UPS API verlangten Header. Gehen Sie nicht davon aus, dass eine Trackingnummer der einzige erforderliche Wert ist: Die aktuelle Referenz kann Versions-, Transaktions-, Inhaltstyp- oder Korrelations-Header vorgeben.

Ein vereinfachtes Anfragebeispiel sieht folgendermaßen aus:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Dies ist ein strukturelles Beispiel und kein Endpunkt zum Kopieren und Einfügen. Verwenden Sie für Ihre Anwendung den in der UPS-Dokumentation veröffentlichten Endpunkt sowie die dort angegebenen Versionen, Header und Parameternamen. Normalisieren Sie die Trackingnummer entsprechend Ihren eigenen Regeln für Auftragsdaten, entfernen Sie jedoch keine Zeichen, sofern die Dokumentation des Versanddienstleisters nicht bestätigt, dass dies sicher ist.

Schritt 5: Überführen Sie Ereignisse in Ihr Datenmodell

Antworten von Versanddienstleistern enthalten oft mehr Informationen als nur eine einzelne Statusbezeichnung. Überführen Sie die Antwort vor der Entwicklung der kundenorientierten Seite in ein internes Modell, das beispielsweise Sendungskennung, Versanddienstleister, aktuellen Status, Ereigniscode, Ereignisbeschreibung, Ereigniszeitpunkt, Ort, Informationen zur voraussichtlichen Zustellung und, falls verfügbar, den Zustellzeitpunkt umfasst.

Bewahren Sie die ursprüngliche Antwort des Versanddienstleisters auf, sofern Ihre Aufbewahrungs- und Datenschutzrichtlinien dies zulassen. Eine Rohantwort kann dabei helfen, einen Zuordnungsfehler zu diagnostizieren oder zu erklären, warum sich Ihr normalisierter Status von der Formulierung des Versanddienstleisters unterscheidet. Vermeiden Sie zugleich, technische Ereigniscodes ohne verständliche Erklärung für Kunden anzuzeigen.

Behandeln Sie nicht jeden Status als endgültiges Zustellergebnis. Ein Ereignis zum Transport, eine Ausnahme, ein Zustellversuch und ein Zustellereignis sollten beispielsweise nicht in dieselbe Kundenmeldung zusammengefasst werden. Erstellen Sie eindeutige Zuordnungen und legen Sie fest, was geschieht, wenn UPS einen Ereigniswert hinzufügt, den Ihr Code nicht erkennt.

Schritt 6: Fügen Sie Wiederholungen, Validierung und Überwachung hinzu

Eine Produktionsintegration benötigt mehr als eine erfolgreiche Anfrage in einer Entwicklungskonsole. Fügen Sie Validierungen und betriebliche Schutzmaßnahmen hinzu:

  • Eingabevalidierung: Lehnen Sie leere, fehlerhafte oder offensichtlich unvollständige Trackingnummern ab, bevor Sie Anfragen senden.
  • Timeouts: Verhindern Sie, dass eine langsame Antwort des Versanddienstleisters einen gesamten Checkout-, Support- oder Lager-Workflow blockiert.
  • Wiederholungsregeln: Wiederholen Sie vorübergehende Netzwerk- oder Dienstausfälle vorsichtig und mit Backoff. Wiederholen Sie Authentifizierungsfehler oder ungültige Trackingnummern nicht ständig.
  • Beachtung der Ratenlimits: Befolgen Sie die Limits und Nutzungsregeln der UPS-Dokumentation. Zwischenspeichern Sie aktuelle Ergebnisse, wenn Ihr Geschäftsprozess dies zulässt.
  • Unbekannte Zustände: Bewahren Sie ein nicht erkanntes Ereignis zur Prüfung auf, anstatt es fälschlicherweise als zugestellt oder verloren zu kennzeichnen.
  • Beobachtbarkeit: Protokollieren Sie Anfragezeiten, Antwortkategorien und Korrelationsinformationen, ohne Geheimnisse oder unnötige personenbezogene Daten zu erfassen.

Ein Trackingsystem sollte außerdem festlegen, wie oft es eine Sendung aktualisiert. Zu häufige Abfragen können vermeidbare Last erzeugen und möglicherweise keine neuen Informationen liefern. Zu seltene Abfragen können dazu führen, dass eine kundenorientierte Seite veraltet erscheint. Wählen Sie ein Intervall anhand des Sendungsvolumens, der betrieblichen Dringlichkeit, der Regeln des Versanddienstleisters und der Aktualität, die Ihre Benutzer tatsächlich benötigen.

Schritt 7: Testen Sie realistische Szenarien

Testen Sie mehr als eine erfolgreich zugestellte Sendung. Berücksichtigen Sie eine unbekannte Trackingnummer, eine Sendung im Transport, eine Ausnahme, eine Sendung mit mehreren Ereignissen, ein abgelaufenes Token, einen Timeout, einen Autorisierungsfehler und eine Antwort mit Feldern, die Ihr Parser nicht erwartet. Falls UPS eine separate Testumgebung oder Testzugangsdaten bereitstellt, befolgen Sie zunächst dieses Verfahren.

Prüfen Sie den vollständigen Weg von der Anfrage bis zur Benutzeroberfläche. Bestätigen Sie, dass die richtige Bestellung die richtige Sendung erhält, Zeitstempel in der vorgesehenen Zeitzone angezeigt werden, doppelte Ereignisse keine doppelten Kundenmeldungen erzeugen und ein Ausfall des Versanddienstleisters einen zuvor gültigen Status nicht durch irreführenden Text überschreibt.

Wann eine Multi-Carrier-Tracking-API besser geeignet ist

Eine direkte UPS-Integration kann geeignet sein, wenn Ihr Unternehmen hauptsächlich mit UPS versendet und eine enge Kontrolle über den Ablauf des Versanddienstleisters benötigt. Sie wird weniger praktisch, wenn Bestellungen über mehrere Versanddienstleister, Marktplätze, Postbetreiber oder regionale Zustellunternehmen abgewickelt werden können. In diesem Fall können separate Zugangsdaten, Antwortformate, Statusvokabulare und Wiederholungsregeln den Wartungsaufwand erhöhen.

Ein Multi-Carrier-Dienst wie die 17TRACK Tracking API kann ein alternatives Integrationsmodell für Anwendungen bieten, die Tracking über mehrere Versanddienstleister benötigen. Die Entwicklerdokumentation sollte direkt auf unterstützte Versanddienstleister, Anfrageformate, Authentifizierung, Nutzungsbedingungen und verfügbare Funktionen geprüft werden. Dadurch ist sie nicht automatisch besser als eine direkte UPS-Verbindung: Die richtige Wahl hängt von der Mischung der Versanddienstleister, den Datenanforderungen, der Kontrolle über die Integration sowie kaufmännischen oder Compliance-Einschränkungen ab.

Für eine verbraucherorientierte Abfrage statt einer Entwicklerintegration kann die Tracking-Seite von 17TRACK geeigneter sein als der Aufbau einer API-Verbindung. Wenn ein Onlineshop markenbezogene Updates nach dem Kauf benötigt, prüfen Sie die entsprechende Plattformintegration separat, anstatt API-Arbeit hinzuzufügen, die der Shop nicht benötigt.

Häufige Implementierungsfehler

  • Verwendung veralteter Beispiele: Ein Codebeispiel kann auf eine eingestellte Version, eine alte Authentifizierungsmethode oder einen anderen UPS-Dienst verweisen.
  • Ablegen von Geheimnissen im Frontend-Code: Alles, was an einen Browser ausgeliefert wird, sollte als einsehbar betrachtet werden.
  • Annahme, ein leeres Ergebnis bedeute, dass keine Sendung existiert: Überprüfen Sie die Trackingnummer, Kontoberechtigungen, Umgebung und Antwortmeldung, bevor Sie eine geschäftliche Schlussfolgerung ziehen.
  • Nur Text zuordnen: Statusbeschreibungen können variieren. Verwenden Sie dokumentierte Codes und bewahren Sie unbekannte Werte zur Prüfung auf.
  • Ignorieren von Konto- und Nutzungsanforderungen: Der technische Code kann korrekt sein, während die Anwendung nicht für den angeforderten Dienst konfiguriert ist.
  • Aktualisierung ohne Geschäftsregel: Unnötige Abfragen können Kosten, Last und betriebliche Unübersichtlichkeit erhöhen, ohne die Kundenerfahrung zu verbessern.

Praktische Checkliste für den Go-Live

  1. Bestätigen Sie, dass die Anwendung die aktuelle UPS-Dokumentation und die genehmigte Umgebung verwendet.
  2. Überprüfen Sie, dass Zugangsdaten serverseitig gespeichert werden und rotiert werden können.
  3. Testen Sie Authentifizierungsfehler, Fehler des Versanddienstleisters, fehlerhafte Eingaben und Timeouts.
  4. Vergleichen Sie normalisierte Statusangaben für repräsentative Sendungen mit der ursprünglichen Antwort.
  5. Legen Sie eine Aktualisierungsrichtlinie fest und überwachen Sie das Anfragevolumen.
  6. Definieren Sie die Zuständigkeit für nicht identifizierte Ereignisse, verzögerte Aktualisierungen und Kundeneskalationen.
  7. Dokumentieren Sie die Integration, damit ein anderer Entwickler Zugangsdaten, Endpunktversionen und Statuszuordnungen sicher aktualisieren kann.

FAQ

Benötige ich ein UPS-Konto, um die Tracking API zu verwenden?

Prüfen Sie die aktuellen UPS-Onboarding- und Zugriffsanforderungen im Developer Portal. Der API-Zugriff kann von der Anwendungsregistrierung, den Zugangsdaten, der Kontokonfiguration und dem konkret angeforderten Dienst abhängen. Gehen Sie nicht davon aus, dass eine Anmeldung auf der öffentlichen Tracking-Seite mit dem Zugriff auf die Developer API austauschbar ist.

Ist die UPS Tracking API kostenlos?

Gehen Sie nicht davon aus, dass der API-Zugriff ohne kaufmännische oder nutzungsbezogene Bedingungen erfolgt. UPS veröffentlicht aktuelle Informationen zu Diensten und Konten über seine offiziellen Kanäle. Einige Anforderungen können vom Produkt, Konto oder Vertrag abhängen. Bestätigen Sie die geltenden Bedingungen direkt, bevor Sie ein Produktionsbudget planen.

Kann ich die UPS API direkt aus JavaScript in einem Browser aufrufen?

Ein browserbasierter Aufruf kann Anwendungszugangsdaten offenlegen und Probleme mit Cross-Origin-Anfragen, Sicherheit und Nutzungskontrolle verursachen. Eine serverseitige Integration ist im Allgemeinen das sicherere Muster für die Speicherung von Geheimnissen, das Abrufen von Token, die Anwendung von Wiederholungsregeln und die Beschränkung des Zugriffs auf Sendungsdaten.

Wie oft sollte meine Anwendung Tracking-Aktualisierungen anfordern?

Verwenden Sie eine Aktualisierungsrichtlinie, die auf den dokumentierten Limits des Versanddienstleisters, dem Sendungsvolumen, der betrieblichen Dringlichkeit und der von Ihren Benutzern benötigten Aktualität basiert. Zwischenspeichern Sie aktuelle Ergebnisse, wo dies sinnvoll ist, verwenden Sie nach vorübergehenden Fehlern einen Backoff und betrachten Sie wiederholte Abfragen nicht als Ersatz für eine dokumentierte Ereignis- oder Benachrichtigungsfunktion.

Sollte ich eine direkte UPS-Integration oder eine Multi-Carrier-API verwenden?

Eine direkte UPS-Integration kann für einen auf UPS ausgerichteten Workflow geeignet sein, der eine versanddienstleisterspezifische Kontrolle benötigt. Eine Multi-Carrier-API kann die Anzahl der Integrationen reduzieren, wenn Ihre Sendungen mehrere Versanddienstleister nutzen. Vergleichen Sie unterstützte Versanddienstleister, Authentifizierung, Datenfelder, Zuverlässigkeitsanforderungen, Nutzungsbedingungen und Implementierungsaufwand, bevor Sie sich entscheiden.

Quellen

Loading