1   Allgemein

1.1   Einführung

Nachfolgend wird die SOAP Schnittstelle beschrieben, die vom Shiptrack.com Service angeboten. Die Schnittstelle arbeitet nach dem SOAP-Standard. Die Authentifizierung des Aufrufers, erfolgt an der Schnittstelle mithilfe eines zuvor definierten Benutzernamens und Passworts über die HTTP-Basic Authentifizierungsmethode (siehe RFC2617).

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:

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

Über die SOAP Schnittstellen können die Sendungsverfolgungsdaten mithilfe von zwei Funktionen abgerufen werden, die ein gefiltertes Ergebnis der gesamten Sendungsverfolgungsdaten eines Kunden zurück liefern. Beide Funktionen liefern das Ergebnis in Form eines XML-Strings, dessen Format im nachfolgenden Kapitel erläutert wird.  Die zugehörigen WSDL Dateien, die den SOAP Webservice beschreiben, finden Sie hier:

2.1   Sammelabfrage

Die Endpunkt-URL der Sammelabfrage muss folgende Struktur aufweisen:

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 XML 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-8601

• until 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

Die URL für der Einzelabfrage hat folgenden Aufbau:

2.2.1   GetWithTrackingNr

Diese Methode 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 der Paketebene findet. Betroffene Felder sind: shipment_tracking_id auf Sendungsebene und send_id auf Paketebene.

2.2.2   GetWithReferenceNr

Dieser Aufruf 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.

2.3   Sendungsanlage via PUT

Mit Hilfe des http-Verbs PUT lassen sich sowohl einzelne als auch mehrere Sendungen an den Service übermitteln. Zur erfolgreichen Übermittlung müssen die in Punkt 2.3.1 definierten Felder angegeben werden.

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

2.3.1   Minimale Felder für die Anlage einer Sendung

2.3.2   Beispiel für die Anlage einer Sendung

2.4   Sendungsverfolgungsdatenformat

Nachfolgend wird das Format der Sendungsverfolgungsdaten, welche von der Schnittstelle zurück geliefert und angenommen werden erläutert.

Die Übertragung der Daten findet im XML-Format statt. Die Kodierung des XML erfolgt immer als UTF-8 und beginnt mit dem Tag „workitem“. Innerhalb des Tags „workitem“ können eine oder mehrere Sendungen übergeben werden. Eine Sendung wird dabei immer mit dem Tag „shipment“ eingeleitet. Wichtig dabei ist, dass bei dem „shipment“ Tag immer das Attribut „collection“ mit dem Wert „true“ vorhanden ist. Ebenso werden alle Tags, die in dem XML vorkommen, kleingeschrieben.

Mindestens folgender Inhalt muss übertragen werden:

Eine erfolgreiche Abfrage liefert folgende Daten zurück:

2.4.1   Grundstruktur

2.4.1.1   Grundstruktur mit mehreren Sendungen

2.4.1.2   Grundstruktur mit mit Paketen

Eine Sendung kann wiederum ein oder mehrere Pakete enthalten. Ein Paket wird dabei mit dem Tag „package“ eingeleitet. Auch bei diesem Tag muss das Attribut „collection“ mit dem Wert „true“ angegeben werden.

2.4.1.3   Grundstruktur mit mehreren Paketen

2.4.2   Status-Codes

Im zurück gelieferten 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 ecovium normierte Status-Codes. Diese Status-Codes sind im Anhang unter Punkt 3.1 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 mit gesendet werden.

2.4.4   Datumswerte

Datumswerte werden in den Sendungsdaten immer nach folgendem Schema dargestellt:

2.4.5   Optionale Felder

2.4.5.1   Shipment-ebene

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

2.4.5.2   Shipmentstatus-ebene

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

2.4.5.3   Paket-ebene

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

2.4.5.4   Packagestatus-ebene

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

2.4.5.5   Dokument-ebene

Diese Ebene befindet sich innerhalb der Shipment-Ebene. Dieses enthält Dokumente wie Label oder Abliefernachweise (PODs).

2.4.5.6   Incident-ebene

Diese Ebene befindet sich innerhalb der Shipment-Ebene.

2.4.5.7   Timing-ebene

Diese Ebene befindet sich innerhalb der Shipment-Ebene und enthält GTA, ETA oder FIX timings.

3   Anhang

3.1   Mögliche Status-Codes auf Sendungs- und Paketebene

Nachfolgend sind die sämtliche Status-Codes aufgelistet, die auf Sendungs- und Paketebene verwendet werden.

3.2    Frachtführerkürzel

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