NCT - XML interface

Owned by Michael.Landwehr
Last updated: Jun 15, 2022
6 min read

1   General

1.1   Introduction

This interface, which is offered by Shiptrack.com, is a XML format (hereinafter also referred to as workItem) is described below. The structure of the XML files described here is based on an XSD that you can find at point 3.1.

2    Data storage

2.1    Data storage at ecovium

The storage of the XML files will be done via file servers. You can chose if you want to use a SFTP or a FTP server. The credentials to your personal file server storage will be given out by ecovium.

2.1.1   Storage on a FTP server

This variant of data storage usually uses the port 21 and is a non encrypted connection.

2.1.2    Storage on a SFTP server

This variant usually also uses port 21 at ecovium, but includes additional SSL settings that ensure that the data is being transmitted in encrypted form in both directions.

2.2    Storage with you or a third party

Moreover it is possible that you store the data on your own file server, or a one which is being provided by a third party. In this case, we need the following information regarding the connection to the corresponding server:

Name

Datentyp

Beschreibung

(S)FTP Port

Integer

Server port

(S)FTP IP Adresse / Servername

String

Server address

(S)FTP Ordner

String

Directory in which the files are being stored on the server

Username

String

Login username for the server

Passwort

String

Login password for the server

 

2.3    Delivery times of the data

In order to optimally regulate the data flow of tracking information and also to provide the customer with tracking information that is as up-to-date as possible, it is necessary for us to receive information about the intervals at which you provide the tracking data on our or your server.

Inhalt

 

 

3    File description

3.1    XML - validation

The XML files are based on a XSD file, which acts as template. Therefore the transmitted XML files need to be validated against the XSD file below:

 

  File Modified

File workItem (V 1.1).xsd

Jun 15, 2022 by Michael.Landwehr

3.2    File names

You are free to choose the naming convention. However, any status feedback file that you submit to us must have the .xml extension.

To prevent existing files from being overwritten, it would be beneficial if each file had its own name. This can be done, for example: by a consecutive number, or by using the current date + time.

E.g.:

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

20151221081025.xml, 20151221091026.xml, 20151221101029.xml

3.3    File encoding

The files are expected to be encoded as UTF8 (as listed in point 6 of the sample file).

3.4    XML-fields

3.4.1    Mandatory fields

The XSD defines all fields or individual elements which must always appear in a XML status file.

3.4.1    Optional fields

Moreover the XSD contains fields or individual elements, which do not have to appear in the XML status file. This may be due to the fact that you do not know the field or cannot fill it in because you cannot provide or transfer the data for it.

 

3.5    Element-layer

Not all fields are required or are currently being displayed on Shiptrack.com. For this reason, the individual levels are specifically listed and described in more detail on the following pages.

3.6    Description of the XML-layers

3.6.1    workItem

The top layer is the workItem layer. It defines how the Shiptrack workItem is structured and what it contains.

3.6.2    shipment

The next layer is the shipment-layer. It contains information on shipment level.

3.6.3    package

Each shipment contains one or more packages. If a shipment contains no packages, the shipment itself should be viewed as the package and set as such. The package layer contains all information on package level, such as length, width, height and weight.

3.6.4   package_tracking_status

Inside the package layer is the package_tracking_status. The status events for the package are stored there.

3.7   Beziehungen zwischen den Ebenen

  • 1 workItem can contain multiple shipments (1:n)

  • 1 shipment can contain multiple packages (1:n)

  • 1 package can contain multiple package_tracking_status (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    Modifications

4.1    XML - changes

The ecovium GmbH reserves the right to change the XSD at any time. The XSD can be changed, for example, when new fields are added. A problem with the data processing and data generation of the XML files by the XSD should only occur if new mandatory fields are defined.

4.2    Customer notifications

If changes are made to the XSD that are relevant to you, we will inform you promptly if you have given us contact information.

 

 

 

5    Description of XML elements

5.1    workItem - element

5.1.1    Mandatory fields

Every file consists of one workItem, in which one or multiple shipments are transferred.

Name

Occurrence

Type

Description

Min.

Max.

shipment

1

unbounded

shipment

One or multiple shipments

 

5.2    shipment - element

5.2.1    Mandatory fields

Name

Occurrence

Type

Description

Min.

Max.

shipment_tracking_id

1

1

String

Unique shipment number

package

1

unbounded

package

Package(s) of the shipment

5.2.2    Optional fields

Name

Occurrence

Type

Description

Min.

Max.

send_versanddatum

0

1

Date

Shipping date (format dd/MM/yyyy)

carrier_name

0

1

String

Carrier/Forwarder/Parcel service provider

send_referenznr_01

0

1

String

1st Customer reference number

send_referenznr_02

0

1

String

2nd Customer reference number

send_referenznr_03

0

1

String

3rd Customer reference number

send_referenznr_04

0

1

String

4th Customer reference number

send_referenznr_05

0

1

String

5th Customer reference number

send_gewichtgesamt

0

1

String

Total weight of the shipment

send_service_code

0

1

String

The shipment’s service code*1

send_service_details

0

1

String

Description of the service code*1

abs_adr_nr

0

1

String

Customer number of the consignee

abs_land

0

1

String

Consignee country name

abs_land_kurz

0

1

String

Two-digit consignee country code (ISO3166)*3

abs_staat

0

1

String

Consignee state

abs_adr_01

0

1

String

1st address line of the consignee

abs_adr_02

0

1

String

2nd address line of the consignee

abs_adr_03

0

1

String

3rd address line of the consignee

abs_strasse

0

1

String

Street of the consignee

abs_hnr

0

1

String

House number of the consignee

abs_plz

0

1

String

Zip code of the consignee

abs_ort

0

1

String

City of the consignee

abs_geodat_longitude

0

1

String

Longitude of the consignee's address*5

abs_geodat_latitude

0

1

String

Latitude of the consignee's address*5

abs_mail

0

1

String

E-Mail address of the consigee

abs_telefon

0

1

String

Telephone number of the consignee

abs_telefax

0

1

String

Fax number of the consignee

empf_adr_01

0

1

String

1st address line of the recipient*2

empf_adr_02

0

1

String

2nd address line of the recipient*2

empf_adr_03

0

1

String

3rd address line of the recipient*2

empf_adr_04

0

1

String

4th address line of the recipient*2

empf_adr_05

0

1

String

5th address line of the recipient*2

empf_fax

0

1

String

Fax number of the recipient

empf_kdnr

0

1

String

Customer number of the recipient

empf_hnr

0

1

String

House number of the recipient

empf_iso

0

1

String

Iso Code of the recipient’s country*4

empf_land

0

1

String

Recipient country

empf_ort

0

1

String

City of the recipient

empf_plz

0

1

String

Zip code of the recipient

empf_staat

0

1

String

State of the recipient

empf_strasse

0

1

String

Street of the recipient

empf_geodat_longitude

0

1

String

Longitude of the recipient’s address*5

empf_geodat_latitude

0

1

String

Latitude of the recipient’s address*5

empf_tel

0

1

String

Telephone number of the recipient

empf_mobile

0

1

String

Mobile number of the recipient

empf_land_kurz

0

1

String

Two-digit consignee country code (ISO3166)*3

empf_mail

0

1

String

E-Mail address of the recipient

empf_postfach

0

1

String

Post box of the recipient

ruecksendung

0

1

Bool

Indicates whether the shipment is a return "true"; otherwise "false".

*1 The service code is a fixed code that describes how the shipment is sent (e.g. night or day express, Saturday delivery, etc.).

*2 The recipient addresses are usually only filled from field 01 to field 03. Field 01 usually corresponds to the name of the recipient, Field 02 and Field 03 to additional information such as a contact or floor information

*3 Usually an ISO-A2 standardized value. ISOA3 also possible on request.

*4 e.g.: 276 for Germany with country code 'DE' (see country table in the appendix)

*5 The geodata (longitude and latitude) are given in decimal notation, examples: "54.787767", "-113.45678", "5.353422". Please note that the area after the period is limited to 20 digits.

 

5.3    package - element

5.3.1    Mandatory fields

Name

Occurrence

Type

Description

Min.

Max.

package_tracking_status

(1)

(1)

package_tracking_status

Package status events

send_id

1

1

String

Unique package number

5.3.2    Optional fields

Name

Occurrence

Type

Description

Min.

Max.

send_referenznr_06

0

1

String

6th reference number*1

send_referenznr_07

0

1

String

7th reference number*1

send_referenznr_08

0

1

String

8th reference number*1

send_referenznr_09

0

1

String

9th reference number*1

send_referenznr_10

0

1

String

10th reference number*1

send_beschreibunginhalt

0

1

String

Description of the packages' content

send_gewichteinzel

0

1

String

Package weight

send_hoehe

0

1

String

Package height

send_laenge

0

1

String

Package length

send_breite

0

1

String

Package width

*1  The reference numbers 06-10 are only used at package level and are references that are usually to be specified by the customer.

 

5.4    package_tracking_status - element

5.4.1    Mandatory fields

Name

Occurrence

Type

Description

Min.

Max.

status_code

1

1

String

Status code

status_date

1

1

Date

Date and time when the status occurred.

5.4.2    Optional fields

Name

Occurrence

Type

Description

Min.

Max.

status_details

0

1

String

Status description

status_country

0

1

String

Two digit country code of the status scan

status_state

0

1

String

State of the status scan

status_city

0

1

String

City of the status scan

status_zip

0

1

String

Zip code of the status scan

status_street

0

1

String

Street and house number of the status scan

status_depot_name

0

1

String

Name of the depot which has done the scan

status_drop_location

0

1

String

Storage location during scanning

status_recipient

0

1

String

Name of the recipient, which accepted the parcel

status_additional_info

0

1

String

Additional information about the status description

status_loc

0

1

GeoLoc

Geo data of the status scan

 

5.5    date - element

Date values ​​are always displayed in the tracking data according to the following scheme:

5.5.1    Mandatory field

Name

Occurrence

Type

Description

Min.

Max.

date

1

1

Date

Date (format dd/MM/yyyy)

5.5.2    Optional fields

Name

Occurrence

Type

Description

Min.

Max.

timezone

0

1

String

Time zone as UTC/GMT. If field is not specified, the time zone is unknown

time

0

1

DateTime

Time in hh:mm:ss format

 

5.6    GeoLoc - element

Any geodata is to be transferred in this element.

5.6.1    Mandatory fields

Name

Occurrence

Type

Description

Min.

Max.

lng

1

1

String

Longitude

lat

1

1

String

Latitude

 

The geodata can have positive and negative values. In the case of negative geodata, a minus sign (-) is written in front of the geocoordinate. A plus sign is not required for positive geodata, but can be set.

 

 

 

6    Sample data

<?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    Status codes

In order to be able to evaluate tracking information, we need a fixed status code with an associated description.

7.1     Shiptrack-codes

If you don't have something like this, you can use our internal status code. We use the following status codes internally:

Statuscode

Description

data_transmitted

Parcel data has been transmitted

transit

In transit

out_for_delivery

Consignment on the way to the recipient

delivered

Parcel has been delivered

pick_up

Shipment was picked up at the recipient

defect_delivered

Defective delivered to the parcel shop or recipient

fault

Error

delay

Delayed

cancelled

Canceled by the sender

deny

Package refused

information

Information

 

7.2     External Codes

Any changes, adjustments or adding status codes and descriptions are work for us. If you have any requests in this regard, you are welcome to contact us, but you should bear in mind that changes, adjustments and the addition of new status codes are chargeable services.

 

 

 

8     Countries

Here is a version of the current country codes with their corresponding stored ISO codes.