REST API - Shipment- and Statusdata
- Benedikt Redmann (Unlicensed)
- Michael.Landwehr
- Sebastian Breitzke
- MHPDE Support (Unlicensed)
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 endpoints according to the REST paradigm. Each URL endpoint can be used to edit or query a specific resource. All queries are made via HTTPS. The HTTP headers specified in the following table must be set with the listed values. The caller is authenticated at the interface using a previously defined user name and password via the HTTP basic authentication method (see RFC2617).
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:
{
"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 |
|---|---|---|
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 |
Inhalt:
|
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-8601until 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:
stringreferenceNr 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 |
|---|---|
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!) |
send_versanddatum | Date on which the shipment was sent. |
2.3.3 Example request of a PUT of a single shipment
{
"shipment": [{
"shipment_tracking_id": "123456789",
"frachtfuehrer": "DHL",
"send_versanddatum": {
"time": "12:00:00",
"date": "01/01/2016"
},
"package": [{
"send_id": "123456789"
}]
}]
}
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:
{
"shipment": [],
"shipment_count": "0"
}
A query containing data looks like this:
2.4.1 Format of shipment tags
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 |
|---|---|
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:
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 |
carrier_contract_id | Contract number with the carrier to uniquely identify the configuration |
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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.