REST API - Shipment- and Statusdata

1   General

1.1   Introduction

Below is a description of the interface which the Shiptrack.com Service offers. The interface is divided into several URL end points according to the REST paradigm. Using each URL end product, a specific resource can be processed or queried. All queries are by HTTPS. Here the HTTP headers indicated in the following table must be placed with the values listed. The authentication of the call, carried out at the interface using a previously defined user name and password via the HTTP basic authentication method (cf. RFC2617).

 

HTTP-Header

Value

HTTP-Header

Value

Content-Type

application/json

1.2   Error handling

In order for a meaningful fault report to be issued when a fault occurs in the interface, the interface sends a response with an HTTP status code which represents a fault. In addition, a message is returned which contains detailed information on the fault. If a client id is used which does not exist, the HTTP Status code 404 will be returned. The corresponding error message looks as follows:

1 2 3 4 { "Message": "Requested client does not exists" "ErrorCode": "404.1" }

 

The standard error code for undefined errors is the HTTP status code 505. Below is a table with all known Shiptrack.com specific error codes:

Errorcode

HTTP-Status

Description

Errorcode

HTTP-Status

Description

404.1

404

The client ID indicated does not exist in the database

400.1

400

The data format indicated in the since parameter does not correspond to the guidelines

500.1

500

No status tree is configured to evaluate the status

 

 

 

2   Shipment tracking data

There are two different methods to call the shipment tracking data. The first method is the collective query. With this query, large data quantities can be transferred between two systems. To prevent getting the same data for each call, we’ve implemented the option to only transfer updated data since the last call. In addition, it is possible to send new shipments or additional information on shipments to Shiptrack.com. The single query is available as the second method with which individual shipments can be queried. Below, both methods will be explained in greater detail.

2.1   Collective query

The endpoint URL for the collective query has the following structure:

The parameter <Client-Id> musst be filled with the provided customer ID.

2.1.1   GET

With the GET http method, all shipments which are assigned to the customers with the customer ID indicated in the client ID, are requested. The result is returned as a JSON string and transferred as a stream. The list of the shipment data which is returned can be limited with the following optional GET parameters:

  • since If this parameter is selected, only data records are returned which have been added within the time frame or for which new data were added.
    data type:
    Date - Format(YYYYMMddHHmmss) in the time zone UTC or ISO-8601

  • until If this parameter is selected, only data records are returned which have been added within the timeframe or for which new data were added.
    data type:
    Date - Format(YYYYMMddHHmmss) in the time zone UTC or ISO-8601

 

2.2   Single query

To use the single query, the URL must be structured as follows:

The parameter <Client-Id> musst be filled with the customer ID provided by ecovium.

2.2.1   GET

With the GET verb, a search can be performed on the shipment data. Here the respective search parameter is transferred as a GET parameter of the query. A combination of several search parameters is still provided for and results in an empty result. The following search parameters are available:

  • trackingNr Performs a search on the tracking number of a shipment or a package. The complete shipment is always returned also if the tracking number is located on the package level. Relevant fields are: shipment_tracking_id on shipment level and send_id on package level
    data type:
    string

  • referenceNr This parameter allows a search on the reference numbers of a shipment both on the shipment and also on the package level. The value indicated is resarched in the following fields: send_referenznr_01, send_referenznr_02, send_referenznr_03, send_referenznr_04, send_referenznr_05 on shipment level and send_referenznr_06, send_referenznr_07, send_referenznr_08, send_referenznr_09, send_referenznr_10 on the package level.
    data type:
    string

 

2.3   Shipment creation

2.3.1   PUT

With the http verb PUT, one or more shipments can be sent to the service. With the successful acceptance of the query, only a HTTP status 202 is reported. The minimum fields which are indicated in the section 2.3.2 have to be filled for a successful transfer.

After a successful transfer, the data are not immediately available for a call via the collective or single query but must instead be processed by the service.

If you want to transfer larger size of data, please inform us, so that we can optimize the import of shipments for you! A larger size of data then 10 shipments is not suggested.

2.3.2   Minimal fields

Field

Description

Field

Description

shipment_tracking_id

Tracking shipment number of the freight carrier.

frachtfuehrer

Short form of the freight carrier with which the shipment is transported.

package.send_id

Tracking package number of the freight carrier.

(When there is no deviant package number, you have to apply the shipment number as a package number!)

package.send_referenzid

(Only mandatory, if the carrier is DPB (Deutsche Post))

RFID for country evidence.

(When there is no package number, you have to add the shipment- & package number like a RFID!)

send_versanddatum

Date on which the shipment was sent.

2.3.3   Example request of a PUT of a single shipment

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "shipment": [{ "shipment_tracking_id": "123456789", "frachtfuehrer": "DHL", "send_versanddatum": { "time": "12:00:00", "date": "01/01/2016" }, "package": [{ "send_id": "123456789", "send_referenzid": "AV123456789DE" }] }] }

 

2.3.4   Additional parameter

To distinguish the workflows to be executed, another header parameter can be specified:

  • source If this parameter is specified (after consultation with the Ecovium), all consignments delivered are supplied to a given workflow.
    data type:
    string

 

2.4   Shipment tracking data format

In the following part the format of the shipment tracking data, which is returned from the interface and accepted, is explained. The data is transferred in the JSON format. A document containing an array of items is always transmitted. Thus, at least the following message is transmitted:

1 2 3 4 { "shipment": [], "shipment_count": "0" }

 

A query containing data looks like this:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 { "shipment": [{ "frachtfuehrer": "UPS", "abs_adr_01": "ECOVIUM GMBH", "abs_strasse": "JUSTUS-VON-LIEBIG-STRASSE 3", "abs_ort": "NEUSTADT A. RBGE.", "abs_plz": "31535", "abs_land_kurz": "DE", "empf_adr_01": "SPIELE SACHEN GMBH", "empf_adr_02": "z.Hd. Hans Grube", "empf_strasse": "TOY-STRASSE 3", "empf_ort": "OBER-MOERLEN", "empf_plz": "61239", "empf_land_kurz": "DE", "empf_locale": "de-DE", "send_referenznr_01": "ls11500197", "send_abholdatum": { "date": "10/08/2015" }, "send_versanddatum": { "date": "10/08/2015" }, "send_gewichtgesamt": "20.00", "package": [{ "collection_index": "1", "send_id": "1Z041R9A6870044607", "send_gewichteinzel": "10", "send_nr": "1", "send_hoehe": "0", "send_laenge": "0", "send_breite": "0", "send_versandart": "512", "send_2n_prodcode": "8398865", "send_ident_prodcode_01": "0", "send_ident_prodcode_02": "0", "package_tracking_status": [{ "status_country": "DE", "status_code": "Manifest Pickup", "status_path": [{ "collection_index": "1", "status_code": "data_transmitted" }], "status_path_count": "1", "status_date": { "time": "09:09:04", "date": "10/08/2015" }, "status_details": "Order Processed: Ready for UPS", "collection_index": "1" }, { "status_country": "DE", "status_city": "LANGENHAGEN", "status_code": "Pick-Up", "status_path": [{ "collection_index": "1", "status_code": "pick_up" }], "status_path_count": "1", "status_date": { "time": "20:54:59", "date": "10/08/2015" }, "status_details": "Origin Scan", "collection_index": "2" }, { "status_country": "DE", "status_city": "LANGENHAGEN", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "20:55:00", "date": "10/08/2015" }, "status_details": "Origin Scan", "collection_index": "3" }, { "status_country": "DE", "status_city": "LANGENHAGEN", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "23:18:00", "date": "10/08/2015" }, "status_details": "Departure Scan", "collection_index": "4" }, { "status_country": "DE", "status_city": "FRANKFURT", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "04:08:00", "date": "10/09/2015" }, "status_details": "Arrival Scan", "collection_index": "5" }, { "status_country": "DE", "status_city": "FRANKFURT", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "06:26:00", "date": "10/09/2015" }, "status_details": "Out For Delivery", "collection_index": "6" }, { "status_country": "DE", "status_city": "OFFENBACH", "status_zip": "63073", "status_Consignee": "SAHIN", "status_code": "Delivered", "status_path": [{ "collection_index": "1", "status_code": "delivered" }], "status_path_count": "1", "status_date": { "time": "09:42:00", "date": "10/09/2015" }, "status_details": "Delivered", "collection_index": "7" } ], "package_tracking_status_count": "7" }, { "collection_index": "2", "send_id": "1Z041R9A6870044616", "send_gewichteinzel": "10", "send_nr": "2", "send_hoehe": "0", "send_laenge": "0", "send_breite": "0", "send_versandart": "512", "send_2n_prodcode": "8398865", "send_ident_prodcode_01": "0", "send_ident_prodcode_02": "0", "package_tracking_status": [{ "status_country": "DE", "status_code": "Manifest Pickup", "status_path": [{ "collection_index": "1", "status_code": "data_transmitted" }], "status_path_count": "1", "status_date": { "time": "09:09:04", "date": "10/08/2015" }, "status_details": "Order Processed: Ready for UPS", "collection_index": "1" }, { "status_country": "DE", "status_city": "LANGENHAGEN", "status_code": "Pick-Up", "status_path": [{ "collection_index": "1", "status_code": "pick_up" }], "status_path_count": "1", "status_date": { "time": "21:00:59", "date": "10/08/2015" }, "status_details": "Origin Scan", "collection_index": "2" }, { "status_country": "DE", "status_city": "LANGENHAGEN", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "21:01:00", "date": "10/08/2015" }, "status_details": "Origin Scan", "collection_index": "3" }, { "status_country": "DE", "status_city": "LANGENHAGEN", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "23:18:00", "date": "10/08/2015" }, "status_details": "Departure Scan", "collection_index": "4" }, { "status_country": "DE", "status_city": "FRANKFURT", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "04:08:00", "date": "10/09/2015" }, "status_details": "Arrival Scan", "collection_index": "5" }, { "status_country": "DE", "status_city": "FRANKFURT", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "05:56:00", "date": "10/09/2015" }, "status_details": "Out For Delivery", "collection_index": "6" }, { "status_country": "DE", "status_city": "FRANKFURT", "status_code": "In transit", "status_path": [{ "collection_index": "1", "status_code": "transit" }], "status_path_count": "1", "status_date": { "time": "06:26:00", "date": "10/09/2015" }, "status_details": "Out For Delivery", "collection_index": "7" }, { "status_country": "DE", "status_city": "OFFENBACH", "status_zip": "63073", "status_Consignee": "SAHIN", "status_code": "Delivered", "status_path": [{ "collection_index": "1", "status_code": "delivered" }], "status_path_count": "1", "status_date": { "time": "09:42:00", "date": "10/09/2015" }, "status_details": "Delivered", "collection_index": "8" } ], "package_tracking_status_count": "8" } ], "package_count": "2", "send_referenznr_02": "D05865", "send_anz": "2", "empf_tel": "069 175 3637 0", "collection_index": "1", "shipment_tracking_id": "1Z041R9A6870044607", "shipment_id": "3aadea46-75ac-4a85-a586-6476febce759", "shipment_tracking_url": "https://portal.shiptrack.com/tracking/2aadea4675ac2a85a5866476febce752", "shipment_tracking_status": { "status_first_refresh_date": { "time": "09:09:04", "date": "10/08/2015" }, "status_last_refresh_date": { "time": "09:42:00", "date": "10/09/2015" }, "status_code": "delivered", "status_date": { "timezone": { "name": "UTC", "offset": "+0000" }, "time": "09:16:56", "date": "10/12/2015" } }, "configurations": [{ "id": "76e457fc-1c5f-4981-9b24-53dd31e335ef", "last_change": { "timezone": { "name": "UTC", "offset": "+0000" }, "time": "15:39:02", "date": "10/08/2015" }, "collection_index": "1" }, { "id": "76e457fc-1c5f-4981-9b24-53dd31e335ef", "last_change": { "timezone": { "name": "UTC", "offset": "+0000" }, "time": "09:19:36", "date": "10/09/2015" }, "collection_index": "2" } ], "configurations_count": "2", "status_tags": [{ "status_code": "delivered", "collection_index": "1" }], "status_tags_count": "1" }], "shipment_count": "1" }

2.4.1    Format of shipment tags

1 2 3 4 5 6 7 8 9 "shipment_tags": [{ "collection_index": "1", "tag": "outbound" }, { "collection_index": "2", "tag": "b2b" } ]

 

In the following, information for fields on the individual levels in the JSON is given separated by a path with dots. For example, the send_id field, which is at the package level, which is at the shipment level, is specified as: shipment.package.send_id

 

2.4.2    Status codes

In the returned result, both the status values on the shipment level can be found on the shipment level in the field shipment.shipment_tracking_id.status_code as well as on the level of the individual packages. They can be found in the field shipment.package.package_tracking_status.status_path. The codes indicated include status codes standardised by ecovium. These status codes are listed in the Annex in separate tables.

The status code which can be found under shipment.package.package_tracking_status.status_code is the original status code sent by the freight carrier.

2.4.2    Minimal fields

The result has, referring to the existing information in the request, more or less information. In the following table are the fields with a description shown, which are transferred by every request. All fields are on the shipment layer, only the field send_id is on the package layer. The package layer can be found on the shipment layer.

Field

Description

Field

Description

shipment_tracking_id

Tracking-Shipment number of the carrier. (Is not unique over a longer period)

shipment_id

Unique Id of the shipment in the Shiptrack.com System.

frachtfuehrer

Shortcut of the carrier, who is shipping the shipment.

package.send_id

Tracking-package number of the carrier.

send_versanddatum

Date, when the shipping progress of the shipment started.

 

2.4.4    Date values

Date values are always shown in the shipment data according to the following diagram:

1 2 3 4 5 6 7 8 {    "timezone": {       "name": "UTC",       "offset": "+0000"    },    "time": "08:49:08",    "date": "07/03/2013" }

Field

Description

Field

Description

date

Date in format mm/dd/yyyy

time

Time in format hh:mm:ss

timezone

Time zone. Optional field. If the field is not indicated, the time zone is not known.

timezone.name

Name of the time zone

timezone.offset

Offset to the UTC time zone

 

2.4.5    Optional fields

The optional fields ,which can be included in the response, are listed below. The individual levels are separated using dots.

2.4.5.1    shipment layer

All of these fields are at the shipment level, which is why this is not specified explicitly.

Feld

Beschreibung

Feld

Beschreibung

send_referenznr_01

Reference number 1

send_referenznr_02

Reference number 2

send_referenznr_03

Reference number 3

send_referenznr_04

Reference number 4

send_referenznr_05

Reference number 5

abs_adr_01

Consignor Address 1

abs_adr_02

Consignor Address 2

abs_adr_03

Consignor Address 3

abs_strasse

Street of the consignor

abs_plz

Zip code of the consignor

abs_ort

City of the consignor

abs_land

Country of the consignor

abs_land_kurz

Two-digit consignor country shortcut (ISO3166)

abs_staat

State/Province of the consignor

abs_mail

E-Mail Address of the consignor

abs_telefon

Telephone number of the consignor

abs_telefax

Fax of the consignor

abs_loc

Location ofthe consignor

empf_adr_01

Consignee Address 1

empf_adr_02

Consignee Address 2

empf_adr_03

Consignee Address 3

empf_strasse

Street of the consignee

empf_hnr

House Number of the consignee

empf_plz

Zip code of the consignee

empf_ort

City of the consignee

empf_land_kurz

Two-digit consignee country shortcut (ISO3166)

empf_land

Country of the consignee

empf_staat

State of the consignee

empf_iso

Iso code of the consignee

empf_nationalitaet

Nationality of the consignee

empf_postfach

P.O. Box of the consignee

empf_unterschrift

Consignee signature/name

empf_mail

E-Mail Address of the consignee

empf_tel

Telephone number of the consignee

empf_kdnr

Customer number of the consignee

empf_locale

Language of recipient (possible values: af-ZA, am-ET, be-BY, bg-BG, ca-ES, cs-CZ, da-DK, de-AT, de-CH, de-DE, el-GR, en-AU, en-CA, en-GB, en-IE, en-NZ, en-US, es-ES, et-EE, eu-ES, fi-FI, fr-BE, fr-CA, fr-CH, fr-FR, he-IL, hi-IN, hr-HR, hy-AM, is-IS, it-CH, it-IT, ja-JP, kk-KZ, ko-KR, la-LN, lt-LT, nl-BE, nl-NL, no-NO, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SI, sr-YU, sv-SE, tr-TR, uk-UA, zh-CN, zh-HK, zh-TW)

send_gewichtgesamt

Weight of all packages of a shipment

shipment_tracking_url

Link to a booking portal page with tracking information

send_abholdatum

Pickup-Date of the shipment

send_anz

Amount of packages in a shipment

send_kundenkennung

if necessary special customer number

send_termindatum

Delivery maturity

send_service_code

Code for additional information for the shipment

send_service_details

Additional information for the shipment

send_nachnahmebetrag

COD amount

send_nachnahmewaehrung

Currency of the COD amount

send_mandant

Client of a shipment

send_service_code

Service type

send_service_details

Service type details

send_customerservice

Free designation of the service type (e.g. express, overnight)

shipment_tags

Special key value parameters (inbound, outbound b2b,b2c)

send_estimatedtimeofarrival

Estimated Time Of Arrival

send_contractedtimeofarrival

Contracted Time Of Arrival

send_versandart_kunde

Service type of the shipping

sourcesystem_shipmentid

Unique shipment-id from your source system

2.4.5.2   Shipment status layer

Field

Description

Field

Description

status_date

Status date

status_code

Shiptrack-Statuscode

 

2.4.5.3   Package layer

All these fields can appear on the package layer.

Fields

Description

Fields

Description

send_referenznr_06

Reference number 6

send_referenznr_07

Reference number 7

send_referenznr_08

Reference number 8

send_referenznr_09

Reference number 9

send_referenznr_10

Reference number 10

send_anzahllademittel_01

Number of loading equipment 01

send_anzahllademittel_02

Number of loading equipment 02

send_anzahllademittel_03

Number of loading equipment 03

send_anzahllademittel_04

Number of loading equipment 04

send_artlademittel_01

Kind of loading equipment 01

send_gewichteinzel

Weight of the package

send_hoehe

Height of the package

send_laenge

Length of the package

send_breite

Width of the package

send_versandart

Kind of delivery

send_zusatz

Additional package

sourcesystem_packageid

Unique package-id from your sourcesystem

 

2.4.5.4 Package status layer

The following fields can all be a part of the package status layer.

Field

Description

Field

Description

status_date

Date, on which the status has occurred

status_details

Details, which are available for the occurred status

status_code

Statuscode 

status_path.status_code

Shiptrack-Statuscode

status_recipient

The recipient of the package

status_drop_location

Details, where for example the package is stored

status_country

Shortcut for the country Code of the status

status_zip

Zip code of the status

status_city

City of the status

Status_state

State of the status

status_street

Street, where the status occurred

status_depot_name

Name of the depot, where the status occurred

status_additional_info

Additional information for the status

status_loc

Location of the status

 

2.4.5.5 Document layer

The following layer is part of the shipment layer and contains documents, such as return labels or POD’s (proof of deliveries).

Field

Description

Field

Description

shipment_document_id

Unique DocumentId

shipment_document_status_type

Status of the document. Currently possible statuses:("ShipmentDocumentOnInternalStorageStatus"

,"ShipmentDocumentOnExternalStorageStatus",

"ShipmentDocumentExistsStatus",

"ShipmentDocumentDownloadErrorStatus")

shipment_document_type

Document type Examples: PoD,"CustomsDocument","Invoice","Misc","Waybill", "Return"

url

Unique path to the document

created

Creation date of the document in the database

shipment_document_originalname

Original name of the document, if available.

mimetype

Type of document (tif, gif, png, pdf ...)

size

Document size in byte

shipment_document_description

Description of the document

 

2.4.5.6 Incident layer

This layer is part of the shipment layer.

Field

Description

Field

Description

name

Name of the rule definition which resulted in the creation of the incident

definition

Guid Id of the rule definition which resulted in the creation of the incident

created

Creation date of the incident

 

2.4.5.7 Timing layer

This layer is also part of the shipment layer and contains timings like GTA, ETA or FIX.

Field

Description

Field

Description

type

Timing type  (ETA, GTA, FIX)

calculation_quality

Hit/Data quality of ETA (ContryToCountry → PlzToPlzWithServicedefinition)

source.label

who created or calculated it (Ecovium or carrier)

source.service_definition_guid

Unique Id based on shipping type

source.transit_times_guid

Unique Id based on shipping time in the shipping type.

source.hours_added.hours_total

Sum of days based of: hours_saturday, hours_sunday & hours_holiday

source.hours_added.hours_saturday

Number of Saturdays that were added to the runtime

source.hours_added.hours_sunday

Number of Sundays that were added to the runtime

source.hours_added.hours_holiday

Number of public holidays that were added to the runtime

creation_date

Creation time of the calculation

range.from_date

Calculated time of delivery (Date + Time)

range.to_date

Calculated time until delivery (Date + Time)

 

 

 

3 Annex

3.1 Possible status codes on shipment and package level

All status codes that are used at shipment and package level are listed below.

3.2    Freight carrier shortcut

All currently known freight carrier short form codes are listed below.