1      Allgemein

1.1    Änderungshistorie

1.2    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).

1.3    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ückgeliefert, 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:

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

URL Livesystem: https://service.shiptrack.com/clients/<Client-Id>/shipments

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 auf. Das Ergebnis wird als JSON-String zurückgeliefert 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ückgeliefert, die seit dem Zeitpunkt importiert oder bei denen neue Daten hinzugefügt wurden.
  Datentyp:
  Datum - Format(YYYYMMddHHmmss) in der Zeitzone UTC oder ISO-8601
• until Wird dieser Parameter angegeben, werden nur Datensätze zurückgeliefert, 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
• onlyUpdates Wenn dieser Parameter true ist, werden nur die Schlüssel der Datensätze zurückgeliefert, die sich geändert haben.
  Datentyp:
  Boolean (true/false)

2.2    Einzelabfrage

URL: https://service.shiptrack.com/clients/<Client-Id>/shipmentsSearch

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ückgeliefert auch wenn die Trackingnummer sich auf Paketebene findet. Betroffene Felder sind: shipment_tracking_id auf Sendungsebene und send_id auf Paketebene
  Datentyp:
  string
• referenceNr 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:
  string

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 Abschnitt 2.3.2 angegeben werden gefüllt sein.

Nach erfolgreicher Übermittlung stehen die Daten nicht sofort zum Abruf über die Sammel- oder Einzelabfrage zur Verfügung sondern müssen erst durch den Service verarbeitet werden.

Falls Sie größere Blöcke übertragen möchten, sprechen Sie uns bitte an, damit wir den Import darauf optimieren können! Eine Blockgröße von mehr als 10 Sendungen ist nicht ratsam.

2.3.2    Minimale Felder für Anlage einer neuen Sendung

2.3.3   Beispiel die für Anlage einer einzelnen neuen Sendung

{

  "shipment": [

    {

      "shipment_tracking_id": "123456789",

      "frachtfuehrer": "DHL",

      "send_versanddatum": {

        "time": "12:00:00",

        "date": "01/01/2016"

      },

      "package": [{

          "send_id": "123456789",

          "send_referenzid": "AV123456789DE"

        }]

    }

  ]

}

2.3.4    Zusatzparameter

Zur Unterscheidung der auszuführenden Workflows kann ein weiterer Headerparameter mitgegeben werden:

• source Wird dieser Parameter angegeben (nach Absprache mit der MHP), werden alle gelieferten Sendungen einem bestimmten Workflow zugeführt.
  Datentyp:
  string

2.4    Sendungsverfolgungsdatenformat

Nachfolgend wird das Format der Sendungsverfolgungsdaten, welche von der Schnittstelle zurückgeliefert und angenommen werden erläutert. Die Übertragung der Daten findet im JSON-Format statt. Dabei wird immer ein Dokument, welches ein Array an Sendungen enthält, übermittelt. Somit wird mindestens folgende Nachricht übertragen:

{
       „shipment“ : [ ],
       „shipment_count“ : "0"
}

Eine Abfrage die Daten enthält sieht wie folgt aus:

2.4.1    Format der Shipmenttags

"shipment_tags": [

    {

      "collection_index": "1",

      "tag": "outbound"

    },

    {

      "collection_index": "2",

      "tag": "b2b"

    }

  ]

Im nachfolgenden werden Angaben für Felder auf die einzelnen Ebenen im JSON durch einen Pfad mit Punkten getrennt angegeben. Zum Beispiel wird auf das Feld send_id, welches sich auf der Pakete-Ebene, die sich wiederum auf der Shipment-Ebene befindet, wie folgt angegeben: shipment.package.send_id

2.4.2    Status-Codes

Im zurückgelieferten Ergebnis sind sowohl Status-Werte auf Ebene der Sendung unter dem Schlüssel shipment.shipment_tracking_id.status_code zu finden, als auch auf der Ebene einzelner Pakete. Diese sind unter dem Schlüssel shipment.package.package_tracking_status.status_path zu finden. Die genannten Schlüssel enthalten von MHP normierte Status-Codes. Diese Status-Codes sind im Anhang in separaten Tabellen aufgelistet.

Der Status-Code, der unter dem shipment.package.package_tracking_status.status_code zu finden ist, ist der originale Status-Code der vom Frachtführer übermittelt wurde.

2.4.3    Minimal Felder

Das Ergebnis kann je nach vorhandenem Informationsvolumen mehr oder weniger Informationen enthalten. In der nachfolgenden Tabelle sind alle Felder mit einer Beschreibung aufgeführt die bei jeder Anfrage mindestens mitgesendet werden. Alle Felder befinden sich mindestens auf der Shipment-Ebene, weswegen diese nicht explizit angegeben wird.

2.4.4    Datumswerte

Datumswerte werden in den Sendungsdaten immer nach folgendem Schema dargestellt:

{

   "timezone": {

      "name": "UTC",

      "offset": "+0000"

   },

   "time": "08:49:08",

   "date": "07/03/2013"

}

2.4.5   Optionale Felder

Nachfolgend sind optionale Felder aufgeführt die in der Antwort enthalten seien können.

2.4.5.1   Shipmentebene

Alle diese Felder befinden sich auf der Shipment-Ebene, weswegen diese nicht explizit angegeben wird.

2.4.5.2   Shipmentstatusebene

Alle diese Felder können sich auf der Shipment-Tracking-Status-Ebene befinden.

2.4.5.3   Packageebene

Alle diese Felder können sich auf der Package-Ebene befinden.

2.4.5.4   Packagestatusebene

Alle diese Felder können sich ebenfalls auf der Package-Tracking-Status-Ebene befinden.

2.4.5.5   Dokumentebene

Diese Ebene befindet sich innerhalb der Shipment-Ebene.

2.4.5.6   Incidentebene

Diese Ebene befindet sich innerhalb der Shipment-Ebene.

2.4.5.7   Timingebene

Diese Ebene befindet sich innerhalb der Shipment-Ebene.

, 

3      Anhang

3.1    Mögliche Status-Codes auf Sendungsebene

Nachfolgend sind die sämtliche Status-Codes aufgelistet, die auf Sendungsebene verwendet werden.

3.2    Mögliche Status-Codes auf Paketebene

In der folgenden Tabelle sind alles Status-Codes aufgelistet, die auf Paketebene verwendet werden.

3.3    Frachtführerkürzel

Nachfolgend werden alle derzeit bekannten Frachtführerkürzel aufgelistet.