NCT - XML Schnittstelle
1Â Â Allgemein
1.1  Einführung
Nachfolgend wird die Schnittstelle beschrieben, die der Shiptrack.com Service im XML-Format (im Folgenden auch WorkItem
genannt) anbietet. Die hier beschriebene Struktur der XML Dateien baut auf einem XSD auf, dass wir Ihnen in der Regel mit der Schnittstellendokumentation haben zukommen lassen, und Ihnen als unterstützendes Mittel bei der Schnittstellenentwicklung dienen soll.
2Â Â Ablage der Trackingdaten
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:
Name | Datentyp | Beschreibung |
---|---|---|
(S)FTP Port | Integer | Login Port für den FTP-Server (meistens 21 bei FTP oder 22 bei SFTP) |
(S)FTP IP Adresse / Servername | String | Adresse des Servers |
(S)FTP Ordner | String | Ablageverzeichnis/ Ablageordner des (S)FTP Servers |
Username | String | Login Benutzername für den Server |
Passwort | String | Login Passwort für den 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Â Â Â XML - Validierung
Die XML Dateien bauen auf einer XSD – Datei als Vorlage auf. Dementsprechend müssen alle uns bereitgestellten XML – Dateien mit der XSD – Datei valide sein.
3.2Â Â Â Dateinamen
Die Namenskonvention bleibt Ihnen frei überlassen. Allerdings muss jede Datei mit Statusrückmeldungen, die Sie uns übergeben die Dateiendung .xml
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.xml, 000000002.xml, 000000003.xml, … 100000001.xml, 100000002.xml
20151221081025.xml, 20151221091026.xml, 20151221101029.xml
3.3Â Â Â Dateicodierung
Die Kodierung der Dateien wird (wie in der Musterdatei in Punkt 7 aufgeführt) als UTF8 erwartet.
3.4Â Â Â XML-Felder
3.4.1Â Â Â Pflichtfelder
Im XSD werden Felder bzw. einzelne Elemente definiert, die immer in einem XML Dokument vorkommen müssen.
3.4.1Â Â Â Optionale Felder
Im XSD werden Felder bzw. einzelne Elemente definiert, die nicht immer in einem XML 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.
Â
3.5Â Â Â Element-Ebenen
Nicht alle Felder müssen verwendet werden und werden aktuell auf Shiptrack.com angezeigt. Aus diesem Grund werden auf den nächsten Seiten nochmal die einzelnen Ebenen speziell aufgeführt und näher beschrieben.
3.6Â Â Â Beschreibung der XML-Ebenen
3.6.1Â Â Â workItem
Als führende Ebene wird die workItem Ebene beschrieben. Hier ist definiert, wie das Shiptrack-workItem aufgebaut ist und was sich darin befindet.
3.6.2Â Â Â shipment
Die nächste Ebene ist die shipment - Ebene. Hier werden alle Sendungsinformationen definiert, die Sie bereitstellen können.
3.6.3Â Â Â package
Jede Sendung besitzt ein oder mehrere Pakete. Sollte eine Sendung keine Pakete besitzen, ist die Sendung selbst als Paket anzusehen und zu setzen. Auf der Paketebene werden als dritte Ebene alle Informationen zum Paket (Höhe, Länge, Breite, Gewicht…) definiert.
3.6.4Â Â Â package_tracking_status
Als Ebene innerhalb von package wird die package_tracking_status - Ebene definiert. Hier werden alle Statusinformationen zum Paket aufgenommen.
3.7Â Â Â Beziehungen zwischen den Ebenen
1 workitem kann mehrere shipment enthalten (1:n)
1 shipment kann mehrere package besitzen (1:n)
1 package kann mehrere package_tracking_status besitzen (1:n)
Â
<workitem>
<shipment>
<package>
<package_tracking_status></package_tracking_status>
<package_tracking_status></package_tracking_status>
<package_tracking_status></package_tracking_status>
</package>
</shipment>
</workitem>
Â
Â
Â
4Â Â Â Modifizierung
4.1   XML - Veränderungen
Die ecovium GmbH behält sich das Recht vor, das XSD jederzeit zu ändern. Eine Veränderung des XSD kann z.B. dann erfolgen, wenn neue Felder hinzugefügt werden. Ein Problem bei der Datenverarbeitung und Datenerzeugen der XML - Dateien durch das XSD dürfte nur dann auftreten, wenn neue Pflichtfelder definiert werden.
4.2Â Â Â Kundenbenachrichtigungen
Sofern Veränderungen am XSD durchgeführt werden, die für Sie relevant sind, werden wir Sie darüber zeitnah informieren, sofern Sie uns Kontaktinformationen mitgeteilt haben.
Â
Â
Â
5Â Â Â Beschreibung der XML-Elemente
5.1Â Â Â workItem - Elemente
5.1.1Â Â Â Pflichtfelder
Jede Datei besteht aus einem workItem, in dem eine oder mehrere Sendungen übergeben werden. Jede Sendung wird als ein shipment definiert.
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
shipment | 1 | unbounded | shipment | Eine oder mehrere Sendungen |
Â
5.2Â Â Â shipment - Elemente
5.2.1Â Â Â Pflichtfelder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
shipment_tracking_id | 1 | 1 | String | Eindeutige Sendungsnummer |
package | 1 | unbounded | package | Paket einer Sendung |
5.2.2Â Â Â Optionale Felder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
send_versanddatum | 0 | 1 | Date | Datum an dem die Sendung versendet wurde; Format dd/MM/yyyy |
carrier_name | 0 | 1 | String | Frachtführer/ Spedition |
send_referenznr_01 | 0 | 1 | String | 1 Referenznummer des Kunden |
send_referenznr_02 | 0 | 1 | String | 2 Referenznummer des Kunden |
send_referenznr_03 | 0 | 1 | String | 3 Referenznummer des Kunden |
send_referenznr_04 | 0 | 1 | String | 4 Referenznummer des Kunden |
send_referenznr_05 | 0 | 1 | String | 5 Referenznummer des Kunden |
send_gewichtgesamt | 0 | 1 | String | Gesamtgewicht der Sendung |
send_service_code | 0 | 1 | String | Servicecode zur Sendung*1 |
send_service_details | 0 | 1 | String | Beschreibung zum verwendeten Servicecode*1 |
abs_adr_nr | 0 | 1 | String | Kundennummer des Absender (vom Spediteur) |
abs_land | 0 | 1 | String | Land des Absender |
abs_land_kurz | 0 | 1 | String | Zweistelliges Absenderländerkürzel (ISO3166)*3 |
abs_staat | 0 | 1 | String | Staat des Absender |
abs_adr_01 | 0 | 1 | String | Erste Adresse des Absenders |
abs_adr_02 | 0 | 1 | String | Zweite Adresse des Absenders |
abs_adr_03 | 0 | 1 | String | Dritte Adresse des Absenders |
abs_strasse | 0 | 1 | String | Straße des Absenders |
abs_hnr | 0 | 1 | String | Hausnummer des Absenders |
abs_plz | 0 | 1 | String | Postleitzahl des Absenders |
abs_ort | 0 | 1 | String | Ort des Absenders |
abs_geodat_longitude | 0 | 1 | String | Längengrad der Position des Absenders*5 |
abs_geodat_latitude | 0 | 1 | String | Breitengrad der Position des Absenders*5 |
abs_mail | 0 | 1 | String | E-Mail Adresse des Absenders |
abs_telefon | 0 | 1 | String | Telefonnummer des Absenders |
abs_telefax | 0 | 1 | String | Fax des Absenders |
empf_adr_01 | 0 | 1 | String | Empfänger Adresse 01*2 |
empf_adr_02 | 0 | 1 | String | Empfänger Adresse 02*2 |
empf_adr_03 | 0 | 1 | String | Empfänger Adresse 03*2 |
empf_adr_04 | 0 | 1 | String | Empfänger Adresse 04*2 |
empf_adr_05 | 0 | 1 | String | Empfänger Adresse 05*2 |
empf_fax | 0 | 1 | String | Fax des Empfängers |
empf_kdnr | 0 | 1 | String | Kundennummer des Empfängers (vom FF) |
empf_hnr | 0 | 1 | String | Hausnummer des Empfängers |
empf_iso | 0 | 1 | String | Iso Code für das Empfängerland*4 |
empf_land | 0 | 1 | String | Land des Empfängers |
empf_ort | 0 | 1 | String | Ort des Empfängers |
empf_plz | 0 | 1 | String | Postleitzahl des Empfängers |
empf_staat | 0 | 1 | String | Staat des Empfängers |
empf_strasse | 0 | 1 | String | Straße des Empfängers |
empf_geodat_longitude | 0 | 1 | String | Längengrad der Position des Empfängers*5 |
empf_geodat_latitude | 0 | 1 | String | Breitengrad der Position des Empfängers*5 |
empf_tel | 0 | 1 | String | Telefonnummer des Empfängers |
empf_mobile | 0 | 1 | String | Mobilnummer des Empfängers |
empf_land_kurz | 0 | 1 | String | Zweistelliges Absenderländerkürzel (ISO3166)*3 |
empf_mail | 0 | 1 | String | E-Mail Adresse des Empfängers |
empf_postfach | 0 | 1 | String | Postfach des Empfängers |
ruecksendung | 0 | 1 | Bool | Kennzeichnung, ob es sich bei der Sendung um eine Rücksendung handelt "true"; ansonsten "false". |
*1 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.).
*2 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.
*3 In der Regel ein ISO-A2 genormter Wert. Mit Absprache auch ISOA3 möglich.
*4 z.B.: 276 für Deutschland mit Länderkürzel ‚DE‘ (siehe Ländertabelle im Anhang)
*5 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.
Â
5.3Â Â Â package - Elemente
5.3.1Â Â Â Pflichtfelder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
package_tracking_status | (1) | (1) | package_tracking_status | Events des einzelnes Paketes |
send_id | 1 | 1 | String | Eindeutige Paketnummer |
5.3.2Â Â Â Optionale Felder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
send_referenznr_06 | 0 | 1 | String | Referenznummer 6*1 |
send_referenznr_07 | 0 | 1 | String | Referenznummer 7*1 |
send_referenznr_08 | 0 | 1 | String | Referenznummer 8*1 |
send_referenznr_09 | 0 | 1 | String | Referenznummer 9*1 |
send_referenznr_10 | 0 | 1 | String | Referenznummer 10*1 |
send_beschreibunginhalt | 0 | 1 | String | Beschreibungsinhalt des Paketes |
send_gewichteinzel | 0 | 1 | String | Einzelgewicht des Pakets |
send_hoehe | 0 | 1 | String | Höhe des Pakets |
send_laenge | 0 | 1 | String | Länge des Pakets |
send_breite | 0 | 1 | String | Breite des Pakets |
*1 Â Die Referenznummer 06-10 werden nur auf Paketebene verwendet und sind Referenzen, die i. d. R. vom Kunden angegeben werden.
Â
5.4Â Â Â package_tracking_status - Elemente
5.4.1Â Â Â Pflichtfelder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
status_code | 1 | 1 | String | Eventcode / Statuscode |
status_date | 1 | 1 | Date | Datum und ggf. Uhrzeit des Status |
5.4.2Â Â Â Optionale Felder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
status_details | 0 | 1 | String | Beschreibung des Status |
status_country | 0 | 1 | String | 2- stelliges Länderkürzel für das Land, wo die Scannung stattfindet |
status_state | 0 | 1 | String | Staat, wo die Scannung stattfindet |
status_city | 0 | 1 | String | Ort oder Stadt, wo die Scannung stattfindet |
status_zip | 0 | 1 | String | Postleitzahl des Ortes oder der Stadt, wo die Scannung stattfindet |
status_street | 0 | 1 | String | Straße (und Hausnummer), wo die Scannung stattfindet |
status_depot_name | 0 | 1 | String | Name des Scandepots |
status_drop_location | 0 | 1 | String | Ablageort bei der Scannung |
status_recipient | 0 | 1 | String | Unterschriftsleistender bei der Scannung |
status_additional_info | 0 | 1 | String | Zusätzliche Informationen zu der Statusbeschreibung Status |
status_loc | 0 | 1 | GeoLoc | Geodaten für den Standort der Scannung |
Â
5.5Â Â Â date -Element
Datumswerte werden in den Trackingdaten immer nach folgendem Schema dargestellt:
5.5.1Â Â Â Pflichtfelder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
date | 1 | 1 | Date | Datum im Format mm/dd/yyyy |
5.5.2Â Â Â Optionale Felder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
timezone | 0 | 1 | String | Zeitzone als UTC/GMT. Wenn Feld nicht angegeben ist, ist die Zeitzone unbekannt |
time | 0 | 1 | DateTime | Zeit im Format hh:mm:ss |
Â
5.6Â Â Â GeoLoc - Element
In diesem Element werden eventuelle Geodaten übertragen.
5.6.1Â Â Â Pflichtfelder
Name | Vorkommen | Typ | Beschreibung | |
---|---|---|---|---|
Min. | Max. | |||
lng | 1 | 1 | String | Längenangabe (Longitude) |
lat | 1 | 1 | String | Breitenangabe (Latitude) |
Â
Die Geodaten können positive und negative Werte annehmen. Bei negativen Geodaten wird vor der Geokoordinate eine Minus Zeichen (-) geschrieben. Bei positiven Geodaten ist ein Plus-Zeichen nicht erforderlich, kann aber gesetzt werden.
Â
Â
Â
6Â Â Â Musterdatei
<?xml version="1.0" encoding="utf-8"?>
<workitem>
<shipment collection="true">
<shipment_tracking_id>12356M547421</shipment_tracking_id>
<carrier_name>Spedition Muster</carrier_name>
<send_versanddatum>
<time>12:00:00</time>
<date>12/11/2015</date>
</send_versanddatum>
<abs_adr_01>Max Mustermann</abs_adr_01>
<abs_adr_02>Musterstraße 33</abs_adr_02>
<abs_adr_nr>12345</abs_adr_nr>
<abs_telefax>4321-20004</abs_telefax>
<abs_hnr>33</abs_hnr>
<abs_iso>276</abs_iso>
<abs_ort>Berlin</abs_ort>
<abs_plz>10439</abs_plz>
<abs_strasse>Musterstraße 33</abs_strasse>
<abs_telefon>20001-4321</abs_telefon>
<abs_land>Deutschland</abs_land>
<abs_land_kurz>DE</abs_land_kurz>
<abs_mail>Mustermann20001@mail.com</abs_mail>
<abs_loc>
<lng>13.4279396999999996</lng>
<lat>52.4985779000000008</lat>
</abs_loc>
<empf_adr_01>DE Berlin Mustermann</empf_adr_01>
<empf_adr_02>HIN-SDG</empf_adr_02>
<empf_adr_03>Wunschtermin und 48 Std-ServiceundNN</empf_adr_03>
<empf_fax>4321-10001</empf_fax>
<empf_kdnr>12344</empf_kdnr>
<empf_hnr>11</empf_hnr>
<empf_iso>276</empf_iso>
<empf_land>Deutschland</empf_land>
<empf_land_kurz>DE</empf_land_kurz>
<empf_ort>Berlin</empf_ort>
<empf_plz>10439</empf_plz>
<empf_strasse>Stavangerstr</empf_strasse>
<empf_tel>10001-4321</empf_tel>
<empf_mobile>10001</empf_mobile>
<empf_mail>Mustermann10001@mail.com</empf_mail>
<send_mandant>701</send_mandant>
<send_gewichtgesamt>22,56</send_gewichtgesamt>
<send_referenznr_01>EUDE01</send_referenznr_01>
<send_referenznr_02>12345</send_referenznr_02>
<ruecksendung>false</ruecksendung>
<package collection="true">
<send_gewichteinzel>20</send_gewichteinzel>
<send_hoehe>10</send_hoehe>
<send_laenge>10</send_laenge>
<send_breite>10</send_breite>
<package_tracking_status collection="true">
<status_code>data_transmitted</status_code>
<status_date>
<time>06:11:12</time>
<date>12/11/2015</date>
</status_date>
<status_details>Daten wurden an Frachtführer gemeldet</status_details>
<status_country>DE</status_country>
<status_state>DataTransmitted</status_state>
<status_city>Berlin</status_city>
<status_zip>10439</status_zip>
<status_street>Einbahnstraße 22</status_street>
<status_depot_name>Eingangsdepot</status_depot_name>
<status_additional_info>Auto Generated Status</status_additional_info>
<status_loc>
<lng>13.4279396999999996</lng>
<lat>52.4985779000000008</lat>
</status_loc>
</package_tracking_status>
<package_tracking_status collection="true">
<status_code>pick_up</status_code>
<status_date>
<time>10:47:12</time>
<date>12/11/2015</date>
</status_date>
<status_details>Paket wurde abgeholt</status_details>
<status_country>DE</status_country>
<status_state>PickUp</status_state>
<status_city>Berlin</status_city>
<status_zip>10439</status_zip>
<status_street>Einbahnstraße 22</status_street>
<status_depot_name>Eingangsdepot</status_depot_name>
<status_additional_info>Auto Generated Status</status_additional_info>
<status_loc>
<lng>13.4279396999999996</lng>
<lat>52.4985779000000008</lat>
</status_loc>
<package_tracking_status collection="true">
<status_code>information</status_code>
<status_date>
<time>20:00:00</time>
<date>12/12/2015</date>
</status_date>
<status_details>Das Paket wurde zwischengelagert</status_details>
<status_country>DE</status_country>
<status_state>information</status_state>
<status_city>Leipzig</status_city>
<status_zip>4103</status_zip>
<status_street>Leipziger Str. 22</status_street>
<status_depot_name>Warenlagerdepot</status_depot_name>
<status_additional_info>Auto Generated Status</status_additional_info>
<status_loc>
<lng>12.3108043913033001</lng>
<lat>51.2877518768179002</lat>
</status_loc>
</package_tracking_status>
<package_tracking_status collection="true">
<status_code>delay</status_code>
<status_date>
<time>14:31:51</time>
<date>12/13/2015</date>
</status_date>
<status_details>Verzögerung</status_details>
<status_country>DE</status_country>
<status_state>Delay</status_state>
<status_city>Leipzig</status_city>
<status_zip>4103</status_zip>
<status_street>Bahnhofsstraße 8</status_street>
<status_additional_info>Stau</status_additional_info>
</package_tracking_status>
<package_tracking_status collection="true">
<status_code>delivered</status_code>
<status_date>
<time>12:12:21</time>
<date>12/14/2015</date>
</status_date>
<status_details>Zustellung der Sendung</status_details>
<status_country>DE</status_country>
<status_state>Delivered</status_state>
<status_city>Schwerin</status_city>
<status_zip>19053</status_zip>
<status_street>Wittenburger Str. 54</status_street>
<status_drop_location>Briefkasten</status_drop_location>
<status_recipient>Herr Mustermann</status_recipient>
<status_additional_info>Auto Generated Status</status_additional_info>
<status_loc>
<lng>12.3642006801596001</lng>
<lat>51.3375641499999986</lat>
</status_loc>
</package_tracking_status>
</package>
</shipment>
</workitem>
Â
Â
Â
7Â Â Â Statuscodes
Um Trackinginformationen auswerten zu können, benötigen wir einen festen Statuscode mit einer dazugehörigen Beschreibung.
7.1Â Â Â Â Shiptrack-Codes
Sofern sie so etwas nicht vorliegen haben können Sie unseren internen Statuscodes nutzen. Intern werden von uns folgenden Statuscodes genutzt:Â
Statuscode | Beschreibung |
---|---|
data_transmitted | Daten wurden an Frachtführer gemeldet |
transit | In Bewegung |
out_for_delivery | Im Zustellprozess |
delivered | Zugestellt |
pick_up | Paket wurde abgeholt |
defect_delivered | Ausgeliefert mit Mängeln |
fault | Fehler |
delay | Verzögerung |
cancelled | Storniert |
deny | Annahme verweigert |
information | Status-Updates |
Â
7.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.
Â
Â
Â
8    Ländertabelle
Hier ist eine Version der aktuellen Länderkürzel mit Ihren entsprechenden hinterlegten ISO Codes aufgeführt.
Â