Skip to main content
StartseiteBlogAnleitungenIhre erste Tracking-API-Anfrage: Eine Anleitung für REST-Clients mit Postman und Curl

Ihre erste Tracking-API-Anfrage: Eine Anleitung für REST-Clients mit Postman und Curl

17TRACK

Um Ihre erste Tracking-API-Anfrage zu stellen, konfigurieren Sie den Endpunkt, den Authentifizierungsheader und den JSON-Body in einem REST-Client, senden Sie die Anfrage und prüfen Sie sowohl den HTTP-Status als auch den Antwort-Body. Dieser Leitfaden verwendet die Tracking API von 17TRACK, um denselben Ablauf in Postman und curl zu demonstrieren: Eine Sendung registrieren, ihre Trackinginformationen anfordern und prüfen, ob das Ergebnis für Ihre Anwendung bereitsteht.

Ihre erste Tracking-API-Anfrage: Leitfaden für einen REST-Client

Das Ziel ist ein kleiner, reproduzierbarer Integrationstest – keine Bereitstellung in der Produktion. Sie benötigen ein API-Zugriffsrecht und eine Trackingnummer, deren Verarbeitung Sie autorisiert sind. Die folgenden Befehle verwenden das Endpunktmuster v2.2. Bestätigen Sie vor der Ausführung die Endpunktversion und kontospezifischen Anforderungen in der 17TRACK API-Dokumentation.

Verstehen, was Ihre erste Anfrage leisten sollte

Eine Sendungsverfolgungsintegration umfasst zwei getrennte Aufgaben: dem Dienst mitzuteilen, welche Sendung verfolgt werden soll, und die mit dieser Sendung verbundenen Trackinginformationen abzurufen. Im hier gezeigten Ablauf handelt es sich um separate Anfragen. Die Registrierung bedeutet nicht, dass sich das Paket bereits bewegt hat, und eine erfolgreiche Registrierung garantiert nicht, dass Ereignisse des Transportdienstleisters sofort verfügbar sind.

Verwenden Sie für Ihren ersten Test eine einzelne Sendung statt einer Gruppe. Dadurch lassen sich Authentifizierungsfehler, ungültige Trackingnummern und die Interpretation der Antwort leichter isolieren. Der erste nützliche Meilenstein ist nicht einfach „Ich habe HTTP 200 erhalten“, sondern: „Die API hat meine beabsichtigte Operation akzeptiert, und ich kann das Ergebnis auf Sendungsebene erklären.“

Postman bietet eine visuelle Oberfläche zum Bearbeiten von Anfragen und Prüfen von Antworten. curl macht denselben HTTP-Austausch von einem Terminal aus reproduzierbar. Keines der beiden Tools ändert die Authentifizierungsregeln, die Sendungsdaten oder das Verarbeitungsverhalten der API. Verwenden Sie das Tool, mit dem Sie die Anfrage klarer untersuchen können, und reproduzieren Sie die funktionierende Konfiguration anschließend im anderen Tool.

Ihre Zugangsdaten, Sendung und Anfragedetails vorbereiten

Stellen Sie vor dem Öffnen eines der beiden Clients Folgendes zusammen:

  • Ein autorisiertes API-Zugriffsrecht: Erhalten Sie es über die Einrichtung Ihres 17TRACK-API-Kontos. Eine Verbrauchersitzung zur Sendungsverfolgung ist kein Ersatz für ein API-Zugriffsrecht.
  • Eine echte Trackingnummer: Verwenden Sie eine Sendung, die Ihnen gehört oder auf die Sie zugreifen dürfen. Eine kürzlich aktive Sendung ist beim Testen echter Trackingdaten im Allgemeinen nützlicher als eine erfundene Nummer.
  • Den Transportdienstleister, falls bekannt: Halten Sie den Namen des Transportdienstleisters zur Diagnose bereit. Wenn für Ihren Fall eine Kennung erforderlich ist, verwenden Sie den in der API-Dokumentation definierten Wert und das dort definierte Feld, statt zu raten.
  • Den aktuellen Anfragevertrag: Bestätigen Sie API-Version, Authentifizierungsheader, Anfrage-Schema und etwaige Kontobeschränkungen.
  • Einen sicheren Arbeitsbereich: Vermeiden Sie es, Zugangsdaten, Kundendaten oder vollständige Trackingantworten in öffentlichen Repositories, Screenshots oder gemeinsam genutzten Supportnachrichten abzulegen.

Die minimalen Anfragebeispiele verwenden folgende Einstellungen:

EinstellungBeispielkonfiguration
Basis-URLhttps://api.17track.net/track/v2.2
RegistrierungsvorgangPOST /register
Vorgang zum Abrufen von TrackinginformationenPOST /gettrackinfo
Authentifizierungsheader17token: YOUR_API_TOKEN
Body-FormatContent-Type: application/json mit einem JSON-Array aus Sendungsobjekten

Behandeln Sie Trackingnummern als Zeichenfolgen. Die Umwandlung in einen numerischen Typ kann führende Nullen entfernen oder den Wert anderweitig verändern. Der Platzhalter YOUR_TRACKING_NUMBER unten muss durch Ihre tatsächliche Testsendung ersetzt werden; er ist keine funktionierende Beispielnummer.

Die Registrierungsanfrage in Postman stellen

1. Eine kleine Testumgebung erstellen

Erstellen Sie in Postman eine Umgebung mit drei Variablen: base_url, tracking_token und tracking_number. Setzen Sie base_url auf die oben angegebene Basis-URL und tragen Sie Ihre Zugangsdaten sowie die Sendungsnummer in die anderen Variablen ein. Wählen Sie diese Umgebung vor dem Senden der Anfrage aus.

Verwenden Sie die verfügbaren Funktionen von Postman zur Verwaltung von Geheimnissen für das Token und prüfen Sie, welche Inhalte Ihr Arbeitsbereich freigibt oder synchronisiert. Das Ausblenden eines Werts in der Oberfläche ersetzt keine Kontrolle darüber, wer darauf zugreifen kann. Exportieren Sie keine ausgefüllten Zugangsdaten mit einer für Kollegen oder öffentliche Dokumentation bestimmten Sammlung.

2. Methode, URL und Header konfigurieren

Erstellen Sie eine HTTP-Anfrage, wählen Sie POST und geben Sie {{base_url}}/register als URL ein. Fügen Sie im Tab „Headers“ Folgendes hinzu:

17token: {{tracking_token}}
Content-Type: application/json

In diesem Beispiel gehört das Zugriffsrecht in den benutzerdefinierten Header 17token. Ersetzen Sie ihn nicht durch eine Bearer-Token-Konfiguration, nur weil eine andere API dieses Muster verwendet hat. Prüfen Sie außerdem, ob geerbte Sammlungseinstellungen einen unbeabsichtigten Authorization-Header hinzufügen.

3. Den JSON-Body hinzufügen

Öffnen Sie „Body“, wählen Sie „raw“ und anschließend „JSON“. Geben Sie Folgendes ein:

[
  {
    "number": "{{tracking_number}}"
  }
]

Die äußeren eckigen Klammern sind wichtig: Diese Anfrage verwendet ein Array, auch wenn es nur eine Sendung enthält. Verwenden Sie doppelte Anführungszeichen, entfernen Sie abschließende Kommas und lassen Sie Kommentare aus dem JSON heraus. Wenn die Dokumentation für Ihren Transportdienstleister oder Ihre Sendung zusätzliche Informationen verlangt, fügen Sie die dokumentierten Felder vor dem Senden hinzu.

4. Senden und Ergebnis prüfen

Klicken Sie auf „Send“. Prüfen Sie zuerst, ob Sie überhaupt eine HTTP-Antwort erhalten haben. Ein DNS-Fehler, TLS-Fehler, Proxyproblem oder Timeout unterscheidet sich von einer Antwort, die erklärt, dass die Anfrage ungültig war. Untersuchen Sie anschließend den Antwort-Body auf das Ergebnis der Operation sowie auf Annahme- oder Ablehnungsinformationen auf Sendungsebene.

Speichern Sie die Anfrage unter „Register test shipment“. Notieren Sie den HTTP-Status, das API-Ergebnis und jede Fehlermeldung, ohne das Token zu kopieren. Wenn die Registrierung fehlschlägt, beheben Sie diesen Fehler, bevor Sie fortfahren. Wiederholtes Senden einer unveränderten Anfrage erschwert die Diagnose und kann Kontingente oder Ressourcen verbrauchen.

Die Anfrage mit curl reproduzieren

Die folgenden Befehle verwenden eine POSIX-Shell wie Bash oder Zsh. PowerShell und die Windows-Eingabeaufforderung haben andere Regeln für Anführungszeichen und Variablen. Verwenden Sie in PowerShell bei Bedarf curl.exe, um die ausführbare curl-Datei statt eines shellspezifischen Befehlsalias aufzurufen.

Setzen Sie die Basis-URL und laden Sie Ihre Zugangsdaten über Ihren normalen Workflow zur Geheimnisverwaltung in eine Umgebungsvariable:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Eine Umgebungsvariable hält die Zugangsdaten aus dem wiederverwendbaren Beispiel heraus, ist jedoch kein vollständiges System zur Geheimnisverwaltung. Vermeiden Sie beim lokalen Testen, ein echtes Token in einen Befehl einzugeben, den Ihre Shell-Historie speichert. Verwenden Sie für Automatisierungen den Geheimnisspeicher Ihrer Plattform und beschränken Sie die Protokollausgabe.

Erstellen Sie eine Datei namens shipment.json und ersetzen Sie den Platzhalter durch Ihre Test-Trackingnummer:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Senden Sie die Registrierungsanfrage:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Dadurch wird der Antwort-Body in register-response.json gespeichert und der HTTP-Status separat ausgegeben. Die Verbindungs- und Gesamt-Timeouts sind Einstellungen für lokale Tests und keine Garantien des 17TRACK-Dienstes. Öffnen Sie die gespeicherte Datei, um das API-Ergebnis zu prüfen; die Statuszeile allein reicht nicht aus.

curl kann eine Übertragung erfolgreich abschließen, auch wenn der Server eine HTTP-Fehlerantwort zurückgibt. Umgekehrt kann ein Transportfehler verhindern, dass eine verwertbare API-Antwort eintrifft. Behandeln Sie beim Skripten den Exit-Status von curl, den HTTP-Status und das Ergebnis auf Anwendungsebene als getrennte Signale.

Die Trackinginformationen der Sendung anfordern

Nachdem Sie die Registrierung bestätigt haben, duplizieren Sie die Postman-Anfrage und ändern Sie die URL in {{base_url}}/gettrackinfo. Behalten Sie POST-Methode, Authentifizierungsheader, Inhaltstyp und Sendungs-Body bei. Speichern Sie die Anfrage separat, damit Sie die Sendung nicht versehentlich erneut registrieren, wenn Sie Daten abrufen möchten.

Die entsprechende curl-Anfrage lautet:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Gehen Sie nicht davon aus, dass eine neu registrierte Sendung sofort eine vollständige Ereignishistorie zurückgibt. Die Datenverfügbarkeit hängt von der Sendung und der Verarbeitung durch den Dienst ab. Wenn Informationen noch nicht verfügbar sind, befolgen Sie die dokumentierten Hinweise zum Abruf und zur Aktualisierung, statt dieselbe Nummer wiederholt zu registrieren oder in kurzen Abständen abzufragen.

Die Antwort in drei Ebenen lesen

  1. Transport: Hat der Client eine Verbindung hergestellt und eine HTTP-Antwort erhalten?
  2. Operation: Hat die API die Anfrage akzeptiert, und war die einzelne Sendung erfolgreich?
  3. Sendungsinformationen: Identifizieren die zurückgegebenen Daten das gewünschte Paket, und was belegen sein Status oder seine Ereignishistorie tatsächlich?

Verwenden Sie das offizielle Antwortschema, um Status-, Transportdienstleister- und Ereignisfelder zu finden. Bewahren Sie die Unterscheidung zwischen einem normalisierten Sendungsstatus und der ursprünglichen Ereignisbeschreibung des Transportdienstleisters. Eine erfolgreiche Abfrage ist kein Beweis für eine Zustellung, und fehlende Ereignisse sind kein Beweis dafür, dass ein Paket verloren gegangen ist.

Bewahren Sie beim Speichern von Zeitstempeln die mitgelieferten Zeitzonen- oder Offsetinformationen. Vermeiden Sie es, Datumszeichenfolgen aus unterschiedlichen Formaten zu sortieren und dabei anzunehmen, dass sie eine korrekte chronologische Reihenfolge darstellen. Unterscheiden Sie außerdem zwischen dem Zeitpunkt, zu dem Ihre Anwendung einen Datensatz abgerufen hat, und dem Zeitpunkt, zu dem das Sendungsereignis eingetreten ist.

Fehler beheben, ohne alles gleichzeitig zu ändern

  • Keine Antwort: Prüfen Sie Hostname, Netzwerkzugriff, Proxyeinstellungen, TLS-Konfiguration und lokales Timeout. Deaktivieren Sie die Zertifikatsprüfung nicht als routinemäßige Lösung.
  • Authentifizierungsfehler: Bestätigen Sie, dass das Token aktiv ist, der Header 17token vorhanden ist und die ausgewählte Postman-Umgebung die Variable korrekt auflöst. Achten Sie auf versehentliche Leerzeichen.
  • Ungültige Anfrage: Überprüfen Sie API-Version, Operationspfad, POST-Methode, Inhaltstyp und JSON-Array-Struktur anhand der Dokumentation.
  • Sendung abgelehnt: Lesen Sie den sendungsspezifischen Fehler. Prüfen Sie die Nummer und erforderliche Informationen zum Transportdienstleister, statt jede Ablehnung als Authentifizierungsproblem zu behandeln.
  • Keine Trackingereignisse: Bestätigen Sie die Registrierung und die Identität der gewünschten Sendung. Prüfen Sie, ob Informationen zum Transportdienstleister erforderlich sind und ob Aktualisierungen verfügbar sind, bevor Sie es erneut versuchen.
  • Postman funktioniert, curl jedoch nicht: Vergleichen Sie die aufgelöste URL, die tatsächlichen Header und die Body-Bytes. Shell-Anführungszeichen und nicht gesetzte Umgebungsvariablen sind häufige Ursachen für Abweichungen.

Ändern Sie pro Test nur eine Variable und führen Sie eine kurze Ergebnisaufzeichnung. Wenn Sie die Postman-Konsole prüfen oder die ausführliche Ausgabe von curl verwenden, behandeln Sie die Ausgabe als vertraulich: Anfrageheader können Zugangsdaten offenlegen. Schwärzen Sie Geheimnisse und Kundendaten, bevor Sie Diagnosedaten weitergeben.

Wissen, wann der Leitfaden abgeschlossen ist

Sie haben einen aussagekräftigen ersten Integrationstest abgeschlossen, wenn beide Clients die beabsichtigte Anfrage senden, die Registrierung verstanden ist, der Abruf ein interpretierbares Ergebnis liefert und Sie einen API-Fehler von einer Sendung ohne neue Informationen unterscheiden können. Übereinstimmende HTTP-Statuscodes allein belegen nicht, dass sich beide Clients identisch verhalten haben.

Bevor Sie den Ablauf in eine Anwendung übernehmen, bewahren Sie Zugangsdaten auf dem Server auf, validieren Sie Eingaben und verwenden Sie eine strukturierte Fehlerbehandlung. Beachten Sie die dokumentierten Ratenlimits, Batch-Limits, Hinweise zu Wiederholungen und Optionen zur Zustellung von Aktualisierungen für Ihr Konto. Gehen Sie nach einem Timeout nicht davon aus, dass eine Registrierung bedenkenlos wiederholt werden kann: Der Server kann die Anfrage verarbeitet haben, obwohl Ihr Client keine Antwort erhalten hat.

Fügen Sie Tests für ungültige Zugangsdaten, fehlerhaftes JSON, eine ungültige Sendungsnummer, eine bereits registrierte Sendung, nicht verfügbare Trackingdaten und ein Netzwerk-Timeout hinzu. Jeder Fall sollte zu einem beabsichtigten Ergebnis der Anwendung führen, nicht zu einer unbehandelten Ausnahme oder einem irreführenden kundenorientierten Status.

FAQ

Kann ich ohne echte Trackingnummer testen?

Sie können mit einem ungültigen Wert bestimmte Validierungsverhalten der Anfrage testen, aber dadurch wird die Sendungsverfolgung nicht überprüft. Verwenden Sie zum Testen echter Ereignisse eine autorisierte Sendung oder eine dokumentierte Testvorrichtung, falls der Dienst eine solche bereitstellt. Gehen Sie nicht davon aus, dass beliebige Beispielnummern zu einer Sandbox gehören.

Warum enthält eine HTTP-200-Antwort trotzdem einen Fehler?

HTTP-Status und Anwendungsergebnisse beschreiben unterschiedliche Ebenen. Ein Server kann eine Anfrage erfolgreich empfangen und verarbeiten und gleichzeitig melden, dass eine einzelne Sendung abgelehnt wurde. Lesen Sie den Antwort-Body und das dokumentierte Ergebnis auf Sendungsebene, nicht nur den HTTP-Status.

Warum wird POST zum Abrufen von Trackinginformationen verwendet?

Verwenden Sie die in der Endpunktdefinition angegebene Methode. Dieses Abrufbeispiel akzeptiert Sendungskennungen in einem JSON-Anfrage-Body über POST. Wenn Sie die Methode in GET ändern, weil der Vorgang Daten liest, entspricht die Anfrage nicht mehr der Dokumentation.

Soll ich das API-Token in Browser-JavaScript einfügen?

Betten Sie keine privaten API-Zugangsdaten in öffentlich ausgelieferten Frontend-Code ein. Leiten Sie Anfragen über ein autorisiertes Backend, das die Zugangsdaten schützt, Eingaben validiert und kontrolliert, auf welche Sendungsinformationen die einzelnen Benutzer zugreifen können.

Benötige ich für die Produktion sowohl Postman als auch curl?

Nein. Beide sind nützliche Test- und Diagnosetools. Ihre Produktionsanwendung kann einen geeigneten HTTP-Client verwenden. Bewahren Sie eine bereinigte Postman-Anfrage oder einen curl-Befehl als reproduzierbare Referenz auf, ohne ein aktives Token oder unnötige Kundendaten.

Quellen