SOAP API - Shipment- and Statusdata
- Benedikt Redmann (Unlicensed)
- Michael.Landwehr
1 General
1.1 Introduction
The SOAP interface offered by the Shiptrack.com Service is described below. It works according to the SOAP standard. The caller is authenticated using a previously defined user name and password via the HTTP basic authentication method (see RFC2617).
1.2 Error handling
In order for the caller to receive a meaningful error message when an error occurs in the interface, it sends a response with an HTTP status code that represents the error. A message is also returned that contains detailed information about the error. For example, the HTTP status code 404 is returned for the error that a customer is specified as a parameter that does not exist. The corresponding detail error message looks like this:
The standard error code for undefined errors is HTTP status code 505. Below is a table listing all known Shiptrack.com specific error codes:
Error code | 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
By using the SOAP interface you can receive shipment tracking data using two functions, which return a filtered result of the entire shipment tracking data for a client. Both functions deliver the result in the form of an XML string, the format of which is explained in the following chapter. The associated WSDL files that describe the SOAP web service can be found here:
2.1 Collective query
The endpoint URL for the collective query is the following:
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 returned. The response is returned as a XML 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 timeframe 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 look as follows:
2.2.1 GetWithTrackingNr
Performs a search on the tracking number of a shipment or a package. The shipment is also returned if the tracking number is located on the package level. Affected fields: shipment_tracking_id on the shipment layer and send_id on the package layer.
Parameter | Description |
|---|---|
client | Id of the Shiptrack.com customer. Is provided by ecovium |
trackingNr | Tracking number which should be searched |
2.2.2 GetWithReferenceNr
This call enables a search on the reference numbers of a shipment, both at shipment and at package level. The specified value is searched for in the following fields: send_reference_01, send_reference_02, send_reference_03, send_reference_04, send_reference_05 at shipment level and send_reference_06, send_reference_07, send_reference_08, send_reference_09, send_reference_10 at package level.
Parameter | Description |
|---|---|
client | Id of the Shiptrack.com customer. Is provided by ecovium |
referenceNr | Reference number which should be searched |
2.3 PUT
With the help of the http verb PUT, both individual and multiple shipments can be sent to the service. For successful transmission, the fields defined in point 2.3.1 must be specified.
After successful transmission, the data is not immediately available for retrieval via the collective or individual query, but must first be processed by the service.
2.3.1 Minimal fields for shipment creation
Parameter | Description |
|---|---|
shipment_tracking_id | Tracking shipment number of the freight carrier. |
frachtfuehrer | Short form of the freight carrier with which the shipment is transported. |
send_versanddatum | Date on which the shipment was sent. |
2.3.2 Example for the creation of a single shipment
<?xml version="1.0" encoding="utf-8"?>
<workitem>
<shipment collection="true">
<frachtfuehrer>HVS</frachtfuehrer>
<send_versanddatum>
<date>01/22/2017</date>
</send_versanddatum>
<shipment_tracking_id>365767978452</shipment_tracking_id>
</shipment>
</workitem>
2.4 Shipment tracking data format
The format of the shipment tracking data that is returned and accepted by the interface is explained below.
The data is transmitted in XML format. The XML is always encoded as UTF-8 and begins with the "workItem" tag. One or more shipments can be transferred within the "workItem" tag. A shipment is always introduced with the tag "shipment". It is important that the "collection" attribute with the value "true" is always present for the "shipment" tag. Likewise, all tags that occur in the XML are written in lower case.
At least the following content must be transmitted:
<?xml version="1.0" encoding="utf-8"?>
<workitem>
<shipment_count>0</shipment_count>
</workitem>A successfull request returns the following data:
2.4.1 Basic structure
2.4.1.1 Basic structure for multiple shipments
2.4.1.2 Basic structure with one package
A shipment can contain one or multiple packages. A package is introduced with the tag “package”. The “collection” attribute must also be specified with the value “true” for this tag.
2.4.1.3 Basic structure with multiple packages
2.4.2 Status codes
In the returned result, status values can be found at shipment level under the shipment.shipment_tracking_id.status_code key, as well as at the level of individual packages. These can be found under the shipment.package.package_tracking_status.status_path key. The keys mentioned contain status codes standardized by ecovium. These status codes are listed in the appendix under point 3.1.
The status code found under shipment.package.package_tracking_status.status_code is the original status code sent by the carrier.
2.4.3 Minimal fields
The result can contain more or less information depending on the volume of information available. The following table lists all fields with a description that are at least sent with every request.
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 scheme:
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 values
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 |
sourcesystem_packageid | Unique package-id from your sourcesystem |
2.4.5.4 Package status layer
The following fields are located in 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.