So registrieren Sie eine Sendungsnummer über die API: Anfragefelder, Versanddienstleister-Codes und Antworten
Um eine Sendungsnummer über eine API zu registrieren, senden Sie eine authentifizierte Registrierungsanfrage, die die Sendungsnummer der Sendung und, falls erforderlich, eine Spediteurkennung enthält. Prüfen Sie anschließend die Antwort für jede übermittelte Sendung – nicht nur den HTTP-Status – und speichern Sie, ob die Registrierung erfolgreich war, fehlgeschlagen ist oder weiterhin ungewiss bleibt. Die Registrierung startet den Sendungsverfolgungsprozess. Sie beweist jedoch nicht, dass der Spediteur das Paket gescannt hat oder dass bereits Sendungsereignisse verfügbar sind.
Dieser Leitfaden richtet sich an Entwickler, die ein Auftragsverwaltungssystem, eine Lageranwendung oder eine E-Commerce-Plattform mit einer Tracking-API verbinden. Er verwendet 17TRACK als konkretes Integrationsbeispiel und erläutert, welche Details anhand der Dokumentation für die von Ihnen ausgewählte API-Version überprüft werden müssen.
Was die Registrierung bewirkt – und was nicht
Eine Registrierungsanfrage teilt einem Trackingdienst mit, welche Sendung er verfolgen soll. Sie unterscheidet sich vom Kauf eines Versandetiketts, der Buchung einer Abholung oder der Aufforderung an einen Spediteur, eine Sendung zu erstellen. In einer typischen Integration erzeugt der Versandprozess zunächst eine Sendungsnummer, woraufhin Ihre Anwendung diese Nummer registriert.
Halten Sie diese drei Ereignisse in Ihrer Anwendung getrennt:
- Sendung erstellt: Ihr Versandsystem hat eine Sendungsnummer vergeben.
- Registrierung akzeptiert: Der Trackingdienst hat die Sendung zur Verfolgung angenommen.
- Trackinginformationen empfangen: Spediteurereignisse sind über den Trackingdienst verfügbar geworden.
Setzen Sie einen Auftrag nicht einfach deshalb auf „unterwegs“, weil die Registrierung erfolgreich war. Ein neu erstelltes Etikett wurde möglicherweise noch nicht physisch vom Spediteur angenommen und gescannt. Der kundenorientierte Sendungsstatus sollte aus Trackingereignissen stammen, die anhand Ihrer Regeln zur Statuszuordnung interpretiert werden, nicht aus der Registrierungsantwort.
Beginnen Sie bei 17TRACK-Integrationen mit der Übersicht der Tracking-API und verwenden Sie die offizielle API-Dokumentation als maßgebliche Quelle für Endpunkte, Felddefinitionen, Authentifizierung und Antwortcodes. Die folgenden Beispiele konzentrieren sich auf die Registrierung und nicht auf die separaten Aufgaben des Abrufens von Ergebnissen oder des Empfangens von Aktualisierungen.
Anfragefelder vorbereiten, bevor Sie den API-Aufruf schreiben
Die nützlichste Vorbereitung ist ein kleiner Feldvertrag zwischen Ihrem Versandsystem und Ihrer Tracking-Integration. Legen Sie fest, woher jeder Wert stammt, ob er fehlen darf und wie er validiert wird.
| Feld oder Wert | Zweck | Implementierungsregel |
|---|---|---|
| Sendungsnummer | Identifiziert die zu verfolgende Sendung. | Als Zeichenfolge speichern und übertragen; führende Nullen beibehalten. |
| Spediteurkennung | Identifiziert den Spediteur im System des Trackinganbieters. | Die dokumentierte Kennung des Anbieters verwenden, nicht einen internen Lagercode. |
| Interne Referenz | Verknüpft die Registrierung mit Ihrem Sendungsdatensatz. | Ein unterstütztes Referenzfeld verwenden, sofern verfügbar; die eigene Datenbankzuordnung unabhängig davon beibehalten. |
| Zusätzliche Identifikationsdaten | Können bei der Identifizierung einer Sendung helfen, wenn ein Spediteur mehr als seine Sendungsnummer verlangt. | Nur für diese Integration und diesen Spediteur dokumentierte Felder übermitteln. |
| API-Zugangsdaten | Authentifizieren das aufrufende Konto. | Auf dem Server aufbewahren und aus Anwendungsprotokollen ausschließen. |
Die Sendungsnummer als Kennung behandeln
Wandeln Sie eine Sendungsnummer niemals in eine Ganzzahl um. Durch die numerische Konvertierung können führende Nullen entfernt werden, und große Werte können in manchen Programmierumgebungen an Genauigkeit verlieren. Entfernen Sie versehentliche Leerzeichen am Anfang und Ende, aber entfernen Sie keine Satzzeichen und ändern Sie nicht die Groß- und Kleinschreibung, sofern die betreffende Dokumentation oder das Spediteurformat eine solche Normalisierung nicht unterstützt.
Validieren Sie offensichtliche Eingabefehler vor dem API-Aufruf: leere Zeichenfolgen, unerwartete Zeilenumbrüche und eine in das Feld für die Sendungsnummer kopierte Bestellnummer. Vermeiden Sie eine einheitliche Längen- oder Zeichenregel für alle Spediteure. Eine Validierungsregel, die für einen Spediteur geeignet ist, kann gültige Nummern eines anderen zurückweisen.
Bestellreferenzen und Sendungsidentitäten getrennt halten
Eine Bestellung kann mehrere Pakete enthalten, und eine Ersatzsendung kann eine weitere Sendungsnummer erhalten. Modellieren Sie die Registrierung auf Ebene der Sendung oder des Pakets, anstatt eine Sendungsnummer pro Bestellung vorauszusetzen.
Wenn Sie ein vom Anbieter unterstütztes Tag- oder Referenzfeld verwenden, bevorzugen Sie eine undurchsichtige Sendungsreferenz statt der E-Mail-Adresse oder Straßenadresse eines Kunden. Ihre eigene Datenbank sollte die maßgebliche Verbindung zwischen Bestellungen, Sendungen, Sendungsnummern und Spediteurzuordnungen bleiben.
Den richtigen Spediteurcode auswählen
Ein Spediteurcode ist nicht zwangsläufig eine universelle Branchenkennung. Der von einer Trackingplattform erkannte Wert kann sich vom in Ihrer Versandsoftware gespeicherten Spediteurnamen unterscheiden. Selbst zwei Systeme, die numerische Codes verwenden, können demselben Spediteur unterschiedliche Nummern zuweisen.
Pflegen Sie eine ausdrückliche Zuordnung von Ihrem Versanddienst zur Spediteurkennung des Trackinganbieters. Unterscheiden Sie bei Bedarf den regionalen Betrieb oder Dienst eines Spediteurs von seiner übergeordneten Marke. Eine Zuordnung, die nur auf einem Anzeigenamen basiert, kann mehrdeutig werden, wenn Versandsysteme Aliasnamen verwenden.
- Wenn der Spediteur bekannt ist: Verwenden Sie, sofern unterstützt, die dokumentierte Spediteurkennung, insbesondere wenn sich die Formate der Sendungsnummern überschneiden.
- Wenn der Spediteur unbekannt ist: Verwenden Sie die automatische Erkennung nur über den dokumentierten Mechanismus. Gehen Sie nicht davon aus, dass das Weglassen, eine leere Zeichenfolge, Null und null dasselbe bedeuten.
- Wenn das Ergebnis falsch aussieht: Überprüfen Sie das ursprüngliche Etikett, den Versanddienst und die Zuordnung, bevor Sie dieselbe Nummer wiederholt registrieren.
Die automatische Erkennung ist nützlich, aber kein Beweis dafür, dass ein bestimmter Spediteur die Sendung physisch besitzt. Ebenso garantiert ein gültiger Spediteurcode nicht, dass die angegebene Sendungsnummer zu diesem Spediteur gehört.
Halten Sie Spediteurzuordnungen konfigurierbar, anstatt sie über den Anwendungscode zu verteilen. Erfassen Sie, wann eine Zuordnung zuletzt überprüft wurde, und nehmen Sie bei jeder Änderung eine bekannte Sendung in Regressionstests auf.
Beispiel: Eine 17TRACK-Registrierungsanfrage senden
Das folgende Beispiel veranschaulicht den 17TRACK-Registrierungsendpunkt v2.2, den Authentifizierungsheader 17token und ein Array mit einem Sendungsnummernobjekt. Vergewissern Sie sich vor der Bereitstellung, dass diese Version und ihre Anfrageanforderungen mit Ihrem Konto und der offiziellen Dokumentation übereinstimmen. Die Sendungsnummer ist ein Platzhalter und muss durch eine echte Sendungskennung ersetzt werden.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Dieses Minimalbeispiel zeigt weder die Auswahl eines Spediteurs noch spediteurspezifische Zusatzfelder. Lesen Sie die Registrierungsdokumentation, um festzustellen, wie die Spediteurerkennung funktioniert, wenn das Spediteurfeld fehlt, und ob Ihre Sendung zusätzliche Informationen benötigt. Wenn Sie einen Spediteur angeben, verwenden Sie das dokumentierte Feld carrier und die von dieser API-Version erwartete Kennung.
Führen Sie diese Anfrage in einer serverseitigen Umgebung aus. Binden Sie das Token nicht in einen öffentlichen Online-Shop, ein Browserskript oder eine an Kunden verteilte mobile Anwendung ein. Eine Umgebungsvariable ist für ein lokales Beispiel praktisch; Produktionsbereitstellungen sollten die Geheimnisverwaltungskontrollen Ihrer Organisation verwenden.
Testen Sie vor einer Erhöhung des Volumens eine bekannte Sendung und prüfen Sie die vollständige Antwort. Testen Sie anschließend eine ungültige Eingabe sowie einen Stapel, der sowohl gültige als auch ungültige Elemente enthält. Diese Prüfungen zeigen, ob Ihre Integration tatsächlich Ergebnisse auf Elementebene verarbeitet, anstatt lediglich eine erfolgreiche HTTP-Antwort zu erkennen.
Die Antwort auf drei Ebenen lesen
Ein zuverlässiger Antwort-Handler beantwortet drei separate Fragen: Hat die Anfrage den Dienst erreicht, hat der Dienst den Vorgang angenommen, und was ist mit jeder Sendung geschehen?
1. HTTP- und Transportergebnis
Ein Verbindungs-Timeout, ein TLS-Fehler oder eine unterbrochene Antwort teilt Ihnen nicht unbedingt mit, ob der Server die Anfrage verarbeitet hat. Markieren Sie dieses Ergebnis als ungewiss, bis Sie es abgleichen können. Ein erfolgreicher HTTP-Status bestätigt einen erfolgreichen HTTP-Austausch; dennoch müssen Sie die Anwendungsantwort prüfen.
2. Ergebnis auf Anfrageebene
Prüfen Sie das dokumentierte Ergebnis und die Fehlerfelder auf oberster Ebene der API. Authentifizierungsfehler, fehlerhaftes JSON und Kontoeinschränkungen erfordern unterschiedliche Maßnahmen. Speichern Sie den ursprünglichen Fehlercode und die ursprüngliche Fehlermeldung des Anbieters, anstatt jeden Fehler auf „Tracking nicht verfügbar“ zu reduzieren.
Gehen Sie nicht davon aus, dass ein numerischer Anwendungscode dieselbe Bedeutung wie ein HTTP-Statuscode hat. Ihre Bedeutungen stammen aus unterschiedlichen Ebenen und müssen getrennt interpretiert werden.
3. Ergebnis auf Sendungsebene
Berücksichtigen Sie bei Stapelregistrierungen jedes übermittelte Element. Eine Antwort kann angenommene und abgelehnte Sendungen unterscheiden; Ihr Parser sollte dem exakten Schema folgen, das für die ausgewählte Version dokumentiert ist. Markieren Sie nicht den gesamten Stapel als registriert, nur weil ein Element erfolgreich war.
Normalisieren Sie Anbieterantworten in Ihre eigenen stabilen Anwendungsstatus. Ihre Datenbank könnte beispielsweise accepted, rejected und uncertain verwenden. Dies sind vorgeschlagene interne Status und keine wörtlichen 17TRACK-Antwortwerte. Bewahren Sie die ursprüngliche Anbieterantwort gemäß einer geeigneten Aufbewahrungs- und Zugriffsrichtlinie auf, damit Entwickler Abweichungen untersuchen können.
Ein nützlicher Registrierungseintrag enthält die interne Sendungs-ID, die übermittelte Nummer, die Spediteurauswahl, den Zeitpunkt des Versuchs, die API-Version, das Ergebnis und die Fehlerdetails des Anbieters. Halten Sie den Registrierungsstatus vom Zustellstatus getrennt.
Wiederholungen handhaben, ohne eine Endlosschleife zu erzeugen
Die Wiederholungsrichtlinie sollte vom Fehler abhängen und nicht einfach davon, ob eine Ausnahme aufgetreten ist.
- Ungültige Eingabe: Korrigieren Sie das Feld vor der Wiederholung. Das erneute Senden einer unveränderten fehlerhaften Anfrage hilft wahrscheinlich nicht.
- Authentifizierungsfehler: Überprüfen Sie Zugangsdaten und Kontokonfiguration. Vermeiden Sie, denselben fehlerhaften Stapel wiederholt zu übermitteln.
- Ratenbegrenzung: Befolgen Sie dokumentierte Grenzen und gegebenenfalls geltende Wiederholungsanweisungen. Verwenden Sie ein begrenztes Backoff statt sofortiger paralleler Wiederholungen.
- Vorübergehender Dienstausfall: Wiederholen Sie den Vorgang innerhalb eines festgelegten Versuchs- und Zeitbudgets.
- Timeout nach der Übermittlung: Gleichen Sie den Registrierungsstatus der Sendung anhand des dokumentierten API-Verhaltens ab, bevor Sie davon ausgehen, dass der erste Versuch fehlgeschlagen ist.
- Antwort im Zusammenhang mit einem Duplikat: Prüfen Sie, ob die Sendung bereits registriert und korrekt Ihrem Anwendungsdatensatz zugeordnet ist.
Gehen Sie nicht davon aus, dass die Registrierung idempotent ist, sofern die Dokumentation dieses Verhalten nicht festlegt. Eine Deduplizierung auf Anwendungsebene verringert versehentliche wiederholte Übermittlungen, legt aber keine Richtlinie des Anbieters für den Umgang mit Duplikaten fest.
Verwenden Sie eine interne Eindeutigkeitsregel, die zu Ihrem Sendungsmodell passt. Die Sendungsnummer allein ist möglicherweise über Spediteure und lange Aufbewahrungszeiträume hinweg kein ausreichender dauerhafter Schlüssel. Bewahren Sie den Spediteurkontext und Ihre eigene Sendungskennung auf und dokumentieren Sie, wie Ersatzsendungen und korrigierte Nummern behandelt werden.
Registrierung getrennt von Tracking-Aktualisierungen überwachen
Die API-Überwachung sollte einen Integrationsfehler von einer Sendung unterscheiden, für die lediglich kein neues Spediteurereignis vorliegt. Diese Bedingungen erfordern unterschiedliche Verantwortliche und unterschiedliche Lösungen.
Überwachen Sie bei der Registrierung die Anzahl der Annahmen und Ablehnungen, Fehlerkategorien, ungewisse Ergebnisse, den Rückstand bei Wiederholungen und die Antwortlatenz. Überwachen Sie bei der anschließenden Sendungsverfolgung den Empfang von Aktualisierungen oder Abruffehler separat. Legen Sie keine numerischen Warnschwellen fest, bevor Sie den normalen Datenverkehr und die dokumentierten Betriebsgrenzen des Anbieters verstanden haben.
Eine praktische Produktionsprüfung sollte folgende Fragen beantworten:
- Hat jede Sendung, die auf eine Verfolgung wartet, einen Registrierungseintrag?
- Lässt sich jede angenommene Registrierung bis zum richtigen Paket zurückverfolgen?
- Werden abgelehnte Elemente an jemanden weitergeleitet, der die zugrunde liegenden Daten korrigieren kann?
- Werden ungewisse Anfragen abgeglichen, statt aufgegeben oder unbegrenzt wiederholt zu werden?
- Werden kundenorientierte Status aus Sendungsereignissen und nicht aus der Registrierungsannahme abgeleitet?
- Werden Zugangsdaten und unnötige personenbezogene Daten aus Protokollen ausgeschlossen?
Für E-Commerce-Abläufe ist die operative Übergabe ebenso wichtig wie der API-Aufruf. Entwickler sollten für Transport- und Parsingfehler zuständig sein; Versand- oder Fulfillment-Teams sollten fehlerhafte Etiketten, Spediteurzuordnungen und fehlende Sendungsinformationen untersuchen können.
FAQ
Kann ich eine Sendungsnummer vor dem ersten Spediteurscan registrieren?
Registrierung und Spediteurscans sind getrennte Ereignisse. Ein Dienst kann eine Nummer vorbehaltlich seiner Validierungsregeln akzeptieren, bevor Trackingereignisse verfügbar sind. Interpretieren Sie die Annahme nicht als Beweis dafür, dass der Spediteur das Paket erhalten hat.
Muss ich immer einen Spediteurcode angeben?
Das hängt vom dokumentierten Erkennungsverhalten der API und von der betreffenden Sendung ab. Wenn der Spediteur bekannt ist, kann eine ausdrückliche, korrekt zugeordnete Kennung Mehrdeutigkeiten verringern. Wenn er unbekannt ist, verwenden Sie die dokumentierte Methode zur automatischen Erkennung, anstatt einen Spediteurwert zu erfinden.
Warum hat die API HTTP-Erfolg zurückgegeben, während eine Sendung fehlgeschlagen ist?
Die HTTP-Anfrage kann erfolgreich sein, während die Anwendung ein einzelnes Element ablehnt. Lesen Sie das Anwendungsergebnis auf oberster Ebene und die Ergebnisse auf Sendungsebene. Diese Unterscheidung ist besonders bei Stapelanfragen wichtig.
Was soll ich tun, wenn eine Registrierungsanfrage einen Timeout verursacht?
Behandeln Sie das Ergebnis als ungewiss. Der Server könnte die Anfrage verarbeitet haben, bevor die Verbindung fehlgeschlagen ist. Prüfen Sie das dokumentierte Duplikatverhalten des Anbieters und verfügbare Methoden zur Registrierungssuche oder Sendungsverfolgung und gleichen Sie das Ergebnis anschließend im Rahmen einer begrenzten Richtlinie ab oder wiederholen Sie den Vorgang.
Konfiguriert die Registrierung automatisch Trackingbenachrichtigungen?
Gehen Sie nicht davon aus. Registrierung, Abruf der Sendungsverfolgung und Webhook-Konfiguration sind getrennte Integrationsaspekte. Überprüfen Sie die relevante Dokumentation und testen Sie den vollständigen Aktualisierungspfad, bevor Sie sich für Kundenbenachrichtigungen darauf verlassen.
Quellen
- 17TRACK API-Dokumentation – Referenz für Registrierungsendpunkte, Authentifizierung, Anfragefelder, Spediteurkennungen, Antwortschemas und Fehlerbehandlung. Stimmen Sie Implementierungsdetails auf die bereitgestellte API-Version ab.
- Übersicht der 17TRACK Tracking-API – offizieller Ausgangspunkt für das Tracking-API-Produkt und Ressourcen zur Entwicklerintegration.


