NCT - CSV interface

Owned by Michael.Landwehr
Jun 15, 2022
5 min read

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:

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

Name

Occurrence

Type

Description

Min.

Max.

shipment_tracking_id

1

1

String

Unique shipment number

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

send_id

0

1

String

Unique package number

send_referenznr_06

0

1

String

6th reference number

send_referenznr_07

0

1

String

7th reference number

send_referenznr_08

0

1

String

8th reference number

send_referenznr_09

0

1

String

9th reference number

send_referenznr_10

0

1

String

10th reference number

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.

 

 

 

6    Status data

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

6.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_geodat_longitude

0

1

String

Longitude of the status scan *1  

status_geodat_latitude

0

1

String

Latitude of the status scan *1

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

*1 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:

"shipment_tracking_id";"carrier_name";"send_versanddatum";"send_referenznr_01";"send_referenznr_02";"send_referenznr_03";"send_referenznr_04";"send_referenznr_05";"send_gewichtgesamt";"send_servicecode";"send_service_details";"abs_adr_nr";"abs_land";"abs_land_kurz";"abs_staat";"abs_adr_01";"abs_adr_02";"abs_adr_03";"abs_strasse";"abs_hnr";"abs_plz";"abs_ort";"abs_geodat_longitude";"abs_geodat_latitude";"abs_mail";"abs_telefon";"abs_telefax";"empf_adr_01";"empf_adr_02";"empf_adr_03";"empf_adr_04";"empf_adr_05";"empf_fax";"empf_kdnr";"empf_hnr";"empf_iso";"empf_land";"empf_ort";"empf_plz";"empf_staat";"empf_strasse";"empf_geodat_longitude";"empf_geodat_latitude";"empf_tel";"empf_mobile";"empf_land_kurz";"empf_mail";"empf_postfach";"send_id";"send_referenznr_06";"send_referenznr07";"send_referenznr08";"send_referenznr09";"send_referenznr10";"send_beschreibunginhalt";"send_gewichteinzel";"send_hoehe";"send_laenge";"send_breite";"ruecksendung";"status_code";"status_date";"status_details";"status_country";"status_state";"status_city";"status_zip";"status_street";"status_depot_name";"status_drop_location";"status_geodat_longitude";"status_geodat_latitude";"status_recipient";"status_additional_info"

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

 7.2    File

  File Modified

File NCT_example.csv

Jun 15, 2022 by Michael.Landwehr

 

 

 

 

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:

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

 

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.