Skip to main content
StartseiteBlogAnleitungenSo validieren Sie Sendungsnummern vor der Übermittlung an die API: 7 Regeln, die Sie befolgen sollten

So validieren Sie Sendungsnummern vor der Übermittlung an die API: 7 Regeln, die Sie befolgen sollten

17TRACK

Validieren Sie eine Sendungsnummer in mehreren Stufen, bevor Sie sie an eine Tracking-API senden: Normalisieren Sie die Eingabe, prüfen Sie ihre grundlegende Struktur, bestätigen Sie den Speditionskontext, wenden Sie eine Prüfsumme nur an, wenn der Spediteur eine solche dokumentiert, und lehnen Sie Werte ab, die eindeutig unsicher oder unvollständig sind. Verlassen Sie sich nicht auf einen universellen regulären Ausdruck. Die Formate von Sendungsnummern unterscheiden sich je nach Spediteur, Service, Land und Versandart. Ein wirksamer Validator sollte daher fehlerhafte Anfragen verhindern, ohne legitime Nummern mit einem unbekannten Format zu blockieren.

So validieren Sie Sendungsnummern vor der API-Übermittlung: 7 Regeln

Dieser Leitfaden richtet sich an Entwickler- und Betriebsteams, die die Sendungsverfolgung in ein Auftragsverwaltungssystem, einen Lagerprozess, ein Kundenportal oder eine E-Commerce-Anwendung integrieren. Ziel ist es nicht, vor der Übermittlung nachzuweisen, dass ein Paket existiert. Die syntaktische Validierung und die Validierung des Sendungsstatus sind getrennte Schritte.

Was die Validierung bestätigen kann – und was nicht

Ein Validator vor der Übermittlung kann häufige Eingabeprobleme erkennen, etwa einen leeren Wert, versehentliche Leerzeichen, nicht unterstützte Zeichen, eine übermäßige Länge oder eine Sendungsnummer, die im falschen Feld steht. Er kann auch einen wahrscheinlichen Spediteur erkennen, wenn dieser bekannt ist und das Format dokumentiert wurde.

Normalerweise kann er nicht bestätigen, dass eine Nummer zu einer echten Sendung gehört, dass das Paket von einem Spediteur angenommen wurde oder dass die Nummer derzeit verfolgt werden kann. Für diese Fragen ist eine Abfrage beim Spediteur oder bei der Tracking-Plattform erforderlich. Eine Nummer kann eine Formatprüfung bestehen und dennoch unbenutzt, auf subtile Weise falsch eingegeben, abgelaufen oder einem anderen Service zugeordnet sein.

Die sieben Regeln

1. Normalisieren Sie den Wert, ohne seine Bedeutung zu verändern

Benutzer und vorgelagerte Systeme fügen häufig führende oder nachgestellte Leerzeichen, Zeilenumbrüche, geschützte Leerzeichen oder Formatierungszeichen hinzu. Normalisieren Sie diese vor der Validierung sicher. Ein üblicher erster Schritt besteht darin, umgebende Leerzeichen zu entfernen und nicht druckbare Leerzeichen in normale Leerzeichen umzuwandeln. Wenn das dokumentierte Format des Spediteurs interne Leerzeichen oder Bindestriche zulässt, entscheiden Sie, ob diese für die API-Anfrage entfernt oder der ursprüngliche Wert für Anzeige und Prüfung beibehalten werden soll.

Bewahren Sie nach Möglichkeit zwei Werte auf: die ursprüngliche Eingabe und einen kanonischen Wert. Die ursprüngliche Eingabe hilft Supportteams bei der Untersuchung von Problemen mit der Datenqualität; der kanonische Wert wird für Validierung und Übermittlung verwendet. Vermeiden Sie Transformationen, die Identifikatoren verändern können. Wandeln Sie Buchstaben nicht automatisch in Zahlen um, ersetzen Sie keine mehrdeutigen Zeichen und entfernen Sie nicht sämtliche Satzzeichen, es sei denn, die Dokumentation des betreffenden Spediteurs oder der API unterstützt dieses Verhalten ausdrücklich.

Der Umgang mit Unicode verdient besondere Aufmerksamkeit. Ein visuell ähnliches Zeichen aus einem anderen Alphabet wird von einer API möglicherweise nicht akzeptiert, obwohl es wie ein ASCII-Buchstabe oder eine ASCII-Ziffer aussieht. Durch die Beschränkung des kanonischen Werts auf den von der ausgewählten Integration erlaubten Zeichensatz lassen sich verwirrende nachgelagerte Fehler vermeiden.

2. Lehnen Sie Werte ab, die grundlegende Strukturprüfungen nicht bestehen

Prüfen Sie vor der Anwendung spedition­spezifischer Logik, ob der Wert vorhanden und plausibel ist. Nützliche Prüfungen umfassen die minimale und maximale Länge, zulässige Zeichenklassen sowie die Frage, ob der Wert ausschließlich aus Leerzeichen oder einem Platzhalter wie „N/A“, „TBD“ oder „test“ besteht. Die genauen Grenzen sollten aus dem API-Vertrag oder der Dokumentation des Spediteurs stammen. Erfinden Sie keine universelle Höchstlänge, nur weil die meisten Beispiele kurz sind.

Eine Strukturprüfung sollte bewusst konservativ sein. Eine Regel, die nur Ziffern zulässt, würde beispielsweise gültige alphanumerische Identifikatoren ablehnen. Eine Regel, die eine feste Länge verlangt, könnte Servicevarianten oder internationale Formate ablehnen. Verwenden Sie allgemeine Prüfungen, um offensichtliche Fehler abzufangen, und wenden Sie spezifischere Prüfungen nur an, wenn Spediteur und Service bekannt sind.

Validieren Sie außerdem den Datentyp an der Anwendungsgrenze. Eine Sendungsnummer sollte normalerweise als String und nicht als Ganzzahl behandelt werden. Die Umwandlung in eine Zahl kann führende Nullen entfernen und in Systemen mit numerischen Datentypen fester Breite zu Präzisionsproblemen führen. Bewahren Sie den Wert nach der genehmigten Normalisierung exakt als String auf.

3. Verwenden Sie den Speditionskontext, statt allein anhand der Nummer zu raten

Eine Sendungsnummer ohne Spediteur ist eine mehrdeutige Eingabe. Verschiedene Spediteure können sich überschneidende Längen, Präfixe oder Zeichensätze verwenden, und ein für einen Spediteur plausibles Format kann für einen anderen ungültig sein. Wenn die Bestellung, das Versandetikett, das Lagerverwaltungssystem oder das Händlerkonto den Spediteur bereits identifiziert, übermitteln Sie diesen Kontext zusammen mit der Sendungsnummer, sofern die API dies unterstützt.

Der Speditionskontext verbessert sowohl die Validierung als auch das Routing. Ihre Anwendung kann dadurch die relevanten Formatregeln auswählen, Fehlzuordnungen reduzieren und aussagekräftigere Fehlermeldungen erzeugen. Außerdem verhindert er, dass ein Ergebnis der automatischen Erkennung als Tatsache behandelt wird, wenn mehrere Spediteure einen ähnlich aussehenden Wert akzeptieren könnten.

Wenn der Spediteur unbekannt ist, verwenden Sie einen zweistufigen Ansatz. Führen Sie zuerst allgemeine Sicherheitsprüfungen durch. Übermitteln Sie den Wert anschließend nur über einen API-Ablauf, der die Spediteur-Erkennung ausdrücklich unterstützt, oder stellen Sie ihn in eine Prüfwarteschlange, wenn der Geschäftsprozess einen bestätigten Spediteur erfordert. Weisen Sie nicht stillschweigend anhand eines Präfixes einen Spediteur zu, es sei denn, diese Zuordnung wird gepflegt und dokumentiert.

4. Wenden Sie Prüfsummen nur an, wenn die Regel dokumentiert ist

Einige Identifikatorsysteme verwenden Prüfziffern, aber für Sendungsnummern gibt es keinen universellen Prüfsummenstandard. Eine Prüfsumme kann bestimmte Übertragungsfehler erkennen, beweist jedoch nicht, dass eine Sendung existiert. Noch wichtiger ist, dass die Anwendung des falschen Prüfsummenalgorithmus gültige Nummern ablehnen kann.

Implementieren Sie eine Prüfsumme nur, wenn der betreffende Spediteur, Service, die Etikettenspezifikation oder die API-Dokumentation den Algorithmus und den davon abgedeckten Eingabeteil definiert. Dokumentieren Sie die Version der Regel und testen Sie sie anhand offizieller Beispiele. Wenn keine maßgebliche Regel verfügbar ist, überspringen Sie die Prüfsumme, statt aus Mustern zu raten, die in einer kleinen Stichprobe beobachtet wurden.

Betrachten Sie das Ergebnis einer Prüfsumme als ein Signal und nicht als vollständige Validierungsentscheidung. Eine fehlgeschlagene Prüfung kann die Blockierung einer Übermittlung rechtfertigen, wenn die Regel verbindlich ist. Eine bestandene Prüfung sollte den Wert in die nächste Stufe weiterleiten, ihn jedoch nicht als aktive Sendung kennzeichnen.

5. Trennen Sie Formatvalidierung und API-Berechtigung

Ein Wert kann formal korrekt, aber dennoch für den von Ihnen aufgerufenen Endpunkt ungeeignet sein. Prüfen Sie vor der Übermittlung in der API-Dokumentation die erforderlichen Felder, akzeptierten Spediteur-IDs, Authentifizierungsanforderungen, Anfragegrenzen, das Verhalten bei Duplikaten sowie mögliche Einschränkungen für Servicetypen oder Zielorte. Dies sind Integrationsregeln und keine Regeln für Sendungsnummern, sie bestimmen jedoch, ob ein gültiger Identifikator erfolgreich verarbeitet werden kann.

Die Dokumentation der 17TRACK Tracking API zeigt beispielhaft, warum diese Unterscheidung wichtig ist: Entwickler müssen dem Anfragemodell der Plattform und dem unterstützten Integrationsverhalten folgen, statt eine Anfrage allein anhand des Erscheinungsbilds einer Sendungsnummer zu erfinden. Die aktuellen Anforderungen an Endpunkte und die Verarbeitung von Antworten finden Sie unter 17TRACK API-Dokumentation.

Halten Sie Validierungsfehler von Transport- und Authentifizierungsfehlern getrennt. „Ungültiges Format der Sendungsnummer“, „Unbekannter Spediteur“, „Ratenlimit erreicht“ und „Autorisierung fehlgeschlagen“ erfordern unterschiedliche Maßnahmen. Eine einzige allgemeine Meldung wie „Übermittlung fehlgeschlagen“ macht Wiederholungen und die betriebliche Berichterstattung weniger zuverlässig.

6. Schützen Sie die API durch begrenzte Eingaben, Deduplizierung und sichere Wiederholungen

Validierung ist auch eine betriebliche Schutzmaßnahme. Erzwingen Sie vor dem Parsen oder Protokollieren eine begrenzte Eingabelänge. Lehnen Sie Steuerzeichen und unerwartete Payload-Strukturen ab. Wenden Sie an Ihrer eigenen Anwendungsgrenze Ratenbegrenzungen an, damit ein fehlerhafter Import keinen unkontrollierten Anfragestrom erzeugen kann.

Führen Sie vor der Übermittlung eine Deduplizierung durch, wenn der Geschäftsprozess keine wiederholte Registrierung erfordert. Ein geeigneter Deduplizierungsschlüssel kann die kanonische Sendungsnummer, den Spediteur, das Konto und den Sendungskontext umfassen. Der richtige Schlüssel hängt von Ihrem Workflow ab. Derselbe Identifikator kann manchmal für verschiedene Services oder Geschäftsvorgänge wiederverwendet werden. Gehen Sie daher nicht davon aus, dass die Nummer allein immer global eindeutig ist.

Verwenden Sie bei vorübergehenden Fehlern begrenzte Wiederholungen mit Backoff und wiederholen Sie dauerhafte Validierungsfehler nicht. Speichern Sie einen Idempotenz- oder Übermittlungsdatensatz, wenn die API und Ihre Architektur dies unterstützen. Protokollieren Sie genügend Informationen zur Fehlerbehebung, schützen Sie jedoch Zugangsdaten, Kundendaten und vertrauliche Sendungsdetails. Ein Validator sollte wiederholte Fehler reduzieren und nicht durch übermäßige Protokollierung ein zweites Sicherheitsproblem schaffen.

7. Bestätigen Sie das Ergebnis nach der Übermittlung und überwachen Sie Fehlklassifizierungen

Die letzte Regel lautet, die Validierung vor der Übermittlung als Schranke und nicht als endgültiges Urteil zu betrachten. Prüfen Sie nach Annahme der Anfrage die API-Antwort und speichern Sie deren Status, die Anfrage-ID, die Zuordnung zum Spediteur und jeden dokumentierten Fehlercode. Wenn die Plattform die Anfrage annimmt, aber noch keine Bewegungsereignisse zurückgeben kann, kann dies auf eine Verarbeitungsverzögerung und nicht auf eine ungültige Nummer hinweisen.

Definieren Sie eine Folgerichtlinie für Nummern, die weiterhin nicht aufgelöst werden können. Das Zeitfenster sollte Spediteur, Service, Versandursprung und Ihre Kundenservice-Richtlinie berücksichtigen; es gibt keinen universellen Zeitraum, der beweist, dass eine Nummer ungültig ist. Eskalieren Sie Datensätze mit fehlendem Spediteur, wiederholten Anbieterfehlern, widersprüchlichen Spediteur-Ergebnissen oder einem Status, der nicht zum Auftragseintrag passt.

Messen Sie falsche Ablehnungen und falsche Annahmen. Ein strenger regulärer Ausdruck kann fehlerhafte Übermittlungen reduzieren und gleichzeitig legitime Sendungen fälschlicherweise blockieren. Ein großzügiger Validator kann mehr Anfragen akzeptieren, aber nachgelagert mehr Störungen verursachen. Prüfen Sie fehlgeschlagene Beispiele nach Spediteur und Service, aktualisieren Sie dokumentierte Regeln über die Versionsverwaltung und testen Sie Änderungen anhand eines repräsentativen, datenschutzsicheren Testdatensatzes.

Eine praktische Validierungssequenz

Eine wartbare Implementierung kann die folgende Reihenfolge verwenden:

  1. Prüfen Sie, ob die Anfrage einen String-Wert und einen gültigen Geschäftsvorgang enthält.
  2. Speichern Sie die ursprüngliche Eingabe und erstellen Sie anschließend eine dokumentierte kanonische Form.
  3. Lehnen Sie leere Werte, Platzhalter, unsichere Zeichen und Werte außerhalb des dokumentierten Längenbereichs ab.
  4. Ermitteln Sie den Spediteur aus vertrauenswürdigen Bestelldaten oder verwenden Sie einen ausdrücklich unterstützten Erkennungsablauf.
  5. Wenden Sie speditorspezifische Syntax- und Prüfsummenregeln nur an, wenn eine maßgebliche Dokumentation dies unterstützt.
  6. Prüfen Sie Endpunktanforderungen, Duplikatstatus und die Berechtigung für Wiederholungen.
  7. Übermitteln Sie die Anfrage, klassifizieren Sie die Antwort, speichern Sie das Ergebnis und planen Sie eine Nachverfolgung für nicht aufgelöste Datensätze.

Diese Reihenfolge erleichtert das Testen des Validators, da jede Entscheidung einen anderen Grund hat. Außerdem erhalten Betriebsteams umsetzbare Fehlerkategorien statt eines einzigen undurchsichtigen Fehlers.

Implementierungs-Checkliste

  • Speichern Sie Sendungsnummern als Strings, damit führende Nullen erhalten bleiben.
  • Bewahren Sie Original- und kanonische Werte getrennt auf, wenn Nachvollziehbarkeit wichtig ist.
  • Verwalten Sie Spediteurregeln als versionierte Konfiguration und nicht als verstreute fest codierte Bedingungen.
  • Testen Sie Buchstaben, Ziffern, Bindestriche, Leerzeichen, ähnlich aussehende Unicode-Zeichen, Platzhalter und Grenzlängen.
  • Verwenden Sie vertrauenswürdigen Speditionskontext, wann immer er verfügbar ist.
  • Leiten Sie aus einem erfolgreichen Treffer eines regulären Ausdrucks nicht die Existenz einer Sendung ab.
  • Klassifizieren Sie dauerhafte Validierungsfehler getrennt von vorübergehenden API- oder Netzwerkfehlern.
  • Prüfen Sie die Dokumentation des Anbieters, bevor Sie Formatregeln oder die Anfragelogik ändern.

FAQ

Kann ein regulärer Ausdruck eine Sendungsnummer validieren?

Er kann ein begrenztes Muster validieren, wenn das Format von Spediteur und Service bekannt ist. Er kann jedoch nicht beweisen, dass die Nummer existiert, zu einer bestimmten Sendung gehört oder derzeit aktiv ist. Ein universeller Ausdruck führt wahrscheinlich zu falschen Ablehnungen oder Fehlzuordnungen.

Soll eine ungültig aussehende Nummer an die API übermittelt werden?

Eindeutig leere, unsichere oder strukturell unmögliche Werte sollten normalerweise vor der Übermittlung gestoppt werden. Ein unbekanntes, aber ansonsten sicheres Format sollte nicht allein deshalb abgelehnt werden, weil es nicht zu einer internen Vermutung passt. Prüfen Sie zuerst die Dokumentation des Spediteurs oder verwenden Sie einen unterstützten Erkennungsprozess.

Reicht eine Prüfsumme aus, um eine Sendung zu bestätigen?

Nein. Eine Prüfsumme prüft, sofern sie anwendbar ist, lediglich, ob der Wert eine mathematische Regel erfüllt. Sie bestätigt nicht, dass ein Spediteur die Nummer ausgestellt hat oder dass das Paket in das Netzwerk gelangt ist.

Was soll passieren, wenn der Spediteur unbekannt ist?

Führen Sie allgemeine Sicherheitsprüfungen durch und verwenden Sie, sofern verfügbar, einen API-Workflow, der die Spediteur-Erkennung ausdrücklich unterstützt. Bewahren Sie den Datensatz andernfalls zur Anreicherung oder manuellen Prüfung auf, statt stillschweigend einen Spediteur zu erraten.

Wie sollten API-Fehler behandelt werden?

Klassifizieren Sie sie nach Ursache. Korrigieren Sie fehlerhafte Eingaben und nicht unterstützte Spediteurwerte; wiederholen Sie vorübergehende Netzwerk- oder Anbieterfehler begrenzt und mit Backoff; und leiten Sie Authentifizierungs- oder Quotenfehler an den Integrationsverantwortlichen weiter. Speichern Sie die für die Diagnose erforderlichen Antwortdetails, ohne Geheimnisse offenzulegen.

Quellen

  • 17TRACK API-Dokumentation — Anleitungen zu Anfragen und Integrationen für Entwickler von Tracking-APIs.
  • 17TRACK Tracking API — offizielle Produktinformationen und Anwendungsfälle der API.
  • USPS Tracking — offizieller Einstiegspunkt für die Sendungsverfolgung und Kundeninformationen des Spediteurs.
  • UPS Tracking — offizieller Einstiegspunkt für die Sendungsverfolgung des Spediteurs.