1   General

1.1   Introduction

This documentation describes the CSV interface which ecovium offers carriers to transfer their status data. It describes the format of the CSV files and should support you while developing.

2    Data storage

2.1    Data storage at ecovium

The storage of the CSV 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:

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.

3    File description

3.1    File names

You are free to choose the naming convention. However, any status feedback file that you submit to us must have the .csv 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.csv, 000000002.csv, 000000003.csv, … 100000001.csv, 100000002.csv

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

3.2    File encoding

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

3.3    CSV-Fields

3.3.1    Mandatory fields

Some fields in the CSV format where defined as mandatory by ecovium. You can find those at poinst 5.1 and 6.1).

3.3.1    Optional fields

All remaining fields are optional and don’t have to be added to the CSV files. This may be because you do not know the field or cannot fill it in because you cannot provide or transfer the data (see points 5.2 and 6.2).

4    Modifications

4.1    CSV-changes

The ecovium GmbH reserves the right to change the CSV at any time. A change can happen when new fields are added or removed.

4.2    Customer notifications

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

5    Shipment data

The following fields contain information about the shipment. Please note the assignment of the fields to the categories mandatory and optional fields.

5.1    Mandatory fields

5.2    Optional fields

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

*² 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

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

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

*⁵ 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.

6    Status data

6.1    Mandatory fields

6.2    Optional fields

*¹ 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.

7    Sample data

7.1    Header

In our CSV template the fields have a specific order, which is listed in the header of the file:

Keep in mind that not all fields can be used or are currently being displayed in Shiptrack.com

 7.2    File

8    Status codes

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

8.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:

1.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.

9    Countries

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