1   Allgemein

1.1   Einführung

Nachfolgend wird die Schnittstelle beschrieben, die Shiptrack.com im CSV-Format anbietet. Diese Dokumentation beschreibt CSV-Dateien, die aus der ecovium-Struktur aufgebaut sind und soll Ihnen als unterstützendes Mittel bei der Schnittstellenentwicklung dienen.

2   Ablage der Trackingdaten

Zur Ablage der Trackingdaten, die Sie später mit Hilfe dieses Dokumentes erstellt haben, gibt es zwei Möglichkeiten.

2.1    Datenablage bei ecovium

Die Datenablage erfolgt nur über FTP - Server. Sie können mitentscheiden, ob eine SFTP Anbindung, oder eine FTP Anbindung für Sie in Frage kommt. Die Zugangsdaten zu Ihrem persönlichen FTP-Verzeichnis fragen Sie bitte bei ecovium an.

2.1.1    Ablage auf einem FTP-Server

Diese Variante der Datenablage benutzt in der Regel den Port 21 und ist eine unverschlüsselte Verbindung.

2.1.2    Ablage auf einem SFTP-Server

Diese Variante verwendet in der Regel ebenfalls den Port 21 bei ecovium, aber beinhaltet zusätzliche SSL-Einstellungen, die dafür sorgen, dass Daten in beide Richtungen verschlüsselt übertragen werden.

2.2    Datenablage bei Ihnen oder einem Drittanbieter

Es besteht auch die Möglichkeit, dass Sie die Daten auf Ihrem eigenen (S)FTP – Server ablegen. In diesen Fall benötigen wir allerdings folgende Verbindungsinformationen zum entsprechenden Server:

2.3    Bereitstellungszeiten der Daten

Um den Datenfluss von Trackinginformationen optimal zu regeln und dem Kunden möglichst aktuelle Trackinginformationen bereitzustellen, ist es für uns notwendig, eine Auskunft darüber zu bekommen, in welchen Intervallen Sie die Trackingdaten auf unserem bzw. auf Ihrem Server bereitstellen.

3    Beschreibung der Datei

3.1    Dateinamen

Die Namenskonvention bleibt Ihnen frei überlassen. Allerdings muss jede Datei mit Statusrückmeldungen, die Sie uns übergeben die Dateiendung .csv besitzen. 

Um ein Überschreiben vorhandener Dateien zu verhindern wäre es von Vorteil, wenn jede Datei einen eigenen Namen besitzt. Dies kann z.B.: durch eine fortlaufende Nummer, oder durch das Nutzen des aktuellen Datums + Uhrzeit erfolgen.

Bsp.:

000000001.csv, 000000002.csv, 000000003.csv, … 100000001.csv, 100000002.csv

20151221081025.csv, 20151221091026.csv, 20151221101029.csv,

3.2    Dateicodierung

Die Kodierung der Dateien wird (wie in der Musterdatei unter Punkt 7 aufgeführt) als UTF8 erwartet.

3.3    CSV-Felder

3.3.1    Pflichtfelder

Einige Felder im CSV Format wurden von ecovium als Pflichtfelder definiert, die immer in einem CSV Dokument vorkommen müssen (siehe Punkte 5.1 und 6.1).

3.3.1    Optionale Felder

Die übrigen Felder sind sogenannte optionale Felder, die nicht immer in einem CSV Dokument vorkommen müssen. Dies kann z.B. daran liegen, dass Sie das Feld nicht kennen oder nicht befüllen können, da Sie die Daten dazu nicht bereitstellen bzw. übergeben können (siehe Punkte 5.2 und 6.2).

4    Modifizierungen

4.1    CSV-Veränderungen

Ecovium behält sich das Recht vor, das CSV jederzeit zu ändern. Eine Veränderung kann z.B. dann erfolgen, wenn Felder hinzugefügt bzw. entfernt werden.

4.2    Kundenbenachrichtigungen

Sofern wir Veränderungen am CSV Format durchführen, die für Sie relevant sind, werden wir Sie darüber zeitnah informieren, sofern Sie uns Kontaktinformationen mitgeteilt haben.

5    Felder mit Sendungsdaten

Die folgenden Felder enthalten Informationen über die Sendung. Bitte beachten Sie die Zuordnung der Felder in die Kategorien „Pflichtfelder“ und „Optionale Felder“.

5.1    Pflichtfelder

5.2    Optionale Felder

*¹ Der Servicecode ist ein fester Code, für den eine Service Beschreibung hinterlegt ist, die beschreibt, wie die Sendung verschickt wird (z.B. Nacht – oder Tagexpress, Samstaglieferung, usw.).

*² Die Empfänger Adressen werden in der Regel nur von Feld 01 bis Feld 03 befüllt. Dabei entspricht Feld01 meistens dem Namen des Empfängers, Feld02 und Feld 03 weiteren Informationen, wie z.B. Ort und Straße bzw. Straße und Hausnummer.

*³ In der Regel ein ISO-A2 genormter Wert. Mit Absprache auch ISOA3 möglich.

*⁴ z.B.: 276 für Deutschland mit Länderkürzel ‚DE‘ (siehe Ländertabelle im Anhang)

*⁵ Die Geodaten (Längen- und Breitengrad) werden in der Dezimalschreibweise angegeben, Beispiele: "54.787767", "-113.45678", "5.353422". Bitte beachten Sie, dass der Bereich nach dem Punkt auf 20 Stellen beschränkt ist.

6    Felder mit Statusdaten

Die folgenden Felder enthalten Informationen über den Status der Sendung. Bitte beachten Sie auch hier die Zuordnung der Felder in die Kategorien „Pflichtfelder“ und „Optionale Felder“.

6.1    Pflichtfelder

6.2    Optionale Felder

*¹  Die Geodaten (Längen- und Breitengrad) werden in der Dezimalschreibweise angegeben, Beispiele: "54.787767", "-113.45678", "5.353422". Bitte beachten Sie, dass der Bereich nach dem Punkt auf 20 Stellen beschränkt ist.

7    Musterdatei

7.1    Kopfzeile

Die Felder besitzen in unserer CSV-Vorlage eine bestimmte Reihenfolge, welche in der Kopfzeile der Datei aufgeführt wird: 

 Denken Sie daran, dass nicht alle Felder verwendet werden müssen oder aktuell auf Shiptrack.com angezeigt werden.

 7.2    Datei

8    Statuscodes

Um Trackinginformationen auswerten zu können, benötigen wir einen festen Statuscode mit einer dazugehörigen Beschreibung.

8.1     Shiptrack-Codes

Sofern sie so etwas nicht vorliegen haben können Sie unseren internen Statuscodes nutzen. Intern werden von uns folgenden Statuscodes genutzt: 

1.2     Externe Codes

Jegliche Änderungen, Anpassungen oder das Hinzufügen von Statuscodes und Beschreibungen sind für uns mit Arbeit verbunden. Wenn Sie diesbezüglich Wünsche haben, können Sie sich gerne mit uns in Kontakt setzten, sollen aber bedenken, dass Änderungen, Anpassungen und auch das Hinzufügen von neuen Statuscodes kostenpflichtige Leistungen sind.

9    Ländertabelle

Hier ist eine Version der aktuellen Länderkürzel mit Ihren entsprechenden hinterlegten ISO Codes aufgeführt.