REST API - Sendungen und Statusdaten
1 Allgemein
1.1 Einführung
Nachfolgend wird die Schnittstelle beschrieben, die der Shiptrack.com Service anbietet. Die Schnittstelle ist in mehrere URL-Endpunkte nach dem REST Paradigma aufgeteilt. Mithilfe jedes URL-Endpunktes kann eine spezifische Ressource bearbeitet oder abgefragt werden. Sämtliche Abfragen erfolgen per HTTPS. Dabei müssen die in der folgenden Tabelle angegebenen HTTP-Header mit den aufgeführten Werten gesetzt werden. Die Authentifizierung des Aufrufers, erfolgt an der Schnittstelle mithilfe eines zuvor definierten Benutzernamens und Passworts über die HTTP-Basic Authentifizierungsmethode (siehe RFC2617).
Unter 4 Downloads steht eine Postman-Collection mit allen verfügbaren Anfragen der REST-API zur Verfügung.
HTTP-Header | Wert |
---|---|
Content-Type | application/json |
1.2 Fehlerbehandlung
Damit bei einem auftretenden Fehler in der Schnittstelle der Aufrufer eine aussagekräftige Fehlermeldung bekommt, sendet die Schnittstelle eine Antwort mit einem HTTP-Statuscode, der den Fehler repräsentiert. Außerdem wird eine Nachricht zurück geliefert, die Detailinformationen zum Fehler enthält. Für den Fehler, dass ein Kunde als Parameter angegeben wird, der nicht existiert, wird zum Beispiel der HTTP-Statuscode 404 zurückgesendet. Die dazugehörige Detail-Fehlermeldung sieht wie folgt aus:
{
"Message": "Requested client does not exists"
"ErrorCode": "404.1"
}
Der Standardfehlercode für undefinierte Fehler ist der HTTP-Statuscode 505. Nachfolgend ist eine Tabelle mit allen bekannten Shiptrack.com spezifischen Fehlercodes aufgelistet:
Fehlercode | HTTP-Status | Beschreibung |
---|---|---|
404.1 | 404 | Die angegebene Client-Id existiert nicht in der Datenbank |
400.1 | 400 | Das angegebene Datumsformat im since-Parameter entspricht nicht den Richtlinien |
500.1 | 500 | Es ist kein Statusbaum konfiguriert um die Status auszuwerten |
Inhalt:
|
2 Sendungsverfolgungsdaten
Zum Abruf der Sendungsverfolgungsdaten existieren zwei unterschiedliche Methoden. Die erste Methode ist die Sammelabfrage. Mit dieser können große Datenmenge zwischen zwei Systemen übertragen werden, dabei existiert ein Mechanismus um nur aktualisierte Daten seit dem letzten Abruf zu übertragen. Des Weiteren ist es möglich über diese Methode neue Sendungen oder zusätzliche Informationen für Sendungen an Shiptrack.com zu senden. Als zweite Methode steht die Einzelabfrage zur Verfügung mit der einzelne Sendungen abgefragt werden können. Nachfolgend werden die beiden Methode genauer Erläutert.
2.1 Sammelabfrage
Die Endpunkt-URL der Sammelabfrage hat folgende Struktur:
Der Parameter <Client-Id> muss mit der mitgeteilten Kunden-Id gefüllt werden.
2.1.1 GET
Mit der http-Methode GET werden alle Sendungen, die den Kunden mit der in der URL angegebenen Client-Id zugeordnet sind aufgerufen. Das Ergebnis wird als JSON-String zurück geliefert und als Stream übertragen. Die Liste der Sendungsdaten die zurückgeschickt wird, kann mit folgenden optionalen GET Parametern eingeschränkt werden:
since Wird dieser Parameter angegeben, werden nur Datensätze zurück geliefert, die seit dem Zeitpunkt importiert oder bei denen neue Daten hinzugefügt wurden.
Datentyp:
Datum - Format(YYYYMMddHHmmss) in der Zeitzone UTC oder ISO-8601until Wird dieser Parameter angegeben, werden nur Datensätze zurück geliefert, die bis zu dem Zeitpunkt importiert oder bei denen neue Daten hinzugefügt wurden.
Datentyp:
Datum - Format(YYYYMMddHHmmss) in der Zeitzone UTC oder ISO-8601
2.2 Einzelabfrage
Der Parameter <Client-Id> muss mit der mitgeteilten Kunden-Id gefüllt werden.
2.2.1 GET
Mit dem GET-Verb kann eine Suche auf den Sendungsdaten durchgeführt werden. Dabei wird der jeweilige Suchparameter als GET-Parameter der Anfrage übergeben. Eine Kombination von mehreren Suchparametern ist noch vorhergesehen und führt zu einem leeren Ergebnis. Folgende Suchparameter stehen zur Verfügung:
trackingNr Führt eine Suche auf der Trackingnummer einer Sendung oder eines Paketes durch. Es wird immer die komplette Sendung zurück geliefert auch wenn die Trackingnummer sich auf Paketebene findet. Betroffene Felder sind: shipment_tracking_id auf Sendungsebene und send_id auf Paketebene
Datentyp:
stringreferenceNr Dieser Parameter ermöglicht eine Suche auf den Referenznummern einer Sendung, sowohl auf Sendungs- als auch auf Paketebene. Der angegebene Wert wird in folgenden Feldern gesucht: send_referenznr_01, send_referenznr_02, send_referenznr_03, send_referenznr_04, send_referenznr_05 auf Sendungsebene und send_referenznr_06, send_referenznr_07, send_referenznr_08, send_referenznr_09, send_referenznr_10 auf Paketebene.
Datentyp:
stringFinished Dieser Parameter ermöglicht eine Suche nach Sendungen welche älter als 6 Monate sind. Dafür müssen zwingend die Parameter trackingNr , referenceNr und Finished gesetzt werden um die Abfrage von 6 Monate oder älteren Sendungen zu ermöglichen. Der Parameter Finished nimmt dabei den Wert 'true' an.
Datentyp:
boolean
2.3 Sendungsanlage
2.3.1 PUT
Mit dem http-Verb PUT können eine oder mehrere Sendungen an den Service übermittelt werden. Bei erfolgreicher Annahme der Anfrage wird nur ein HTTP Status-Code 202 zurückgemeldet. Zur erfolgreichen Übermittlung müssen die Minimalfelder die in Absc