Versions Compared

Old Version 31

changes.mady.by.user Michael.Landwehr

Saved on

compared with

New Version 32

changes.mady.by.user Michael.Landwehr

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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:

Table of Contents

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:

Attachments
uploadfalse

2.1 Collective query

The endpoint URL for the collective query is the following:

Info

https://service.shiptrack.com:8443/shipments

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:

Info

https://service.shiptrack.com:8443/shipments

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

Code Block
languagexml
<?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:

Code Block
<?xml version="1.0" encoding="utf-8"?>
<workitem>
  <shipment_count>0</shipment_count>
</workitem>

A successfull request returns the following data:

Expand
Code Block
<?xml version="1.0" encoding="utf-8"?>
<workitem>
  <shipment collection="true">
    <frachtfuehrer>UPS</frachtfuehrer>
    <abs_adr_01>ECOVOUM GMBH</abs_adr_01>
    <empf_adr_01>ROSEN VERSENDER</empf_adr_01>
    <empf_adr_02>ZHD ROSENVERKAEFAUER 1</empf_adr_02>
    <abs_strasse>JUSTUS-VON-LIEBIG-STRASSE 3</abs_strasse>
    <abs_ort>NEUSTADT A. RBGE.</abs_ort>
    <abs_plz>31535</abs_plz>
    <abs_land_kurz>DE</abs_land_kurz>
    <empf_strasse>MARIA-KIRCHNER-STR. 32</empf_strasse>
    <empf_ort>ARNSTORF</empf_ort>
    <empf_plz>94424</empf_plz>
    <empf_land_kurz>DE</empf_land_kurz>
    <send_referenznr_01>5601519</send_referenznr_01>
    <send_abholdatum>
      <date>03/24/2014</date>
    </send_abholdatum>
    <send_versanddatum>
      <date>03/24/2014</date>
    </send_versanddatum>
    <send_gewichtgesamt>1.00</send_gewichtgesamt>
    <package collection="true">
      <collection_index>1</collection_index>
      <send_id>1Z7110966853336416</send_id>
      <send_gewichteinzel>1</send_gewichteinzel>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_code>Manifest Pickup</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>data_transmitted</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>12:39:40</time>
          <date>03/24/2014</date>
        </status_date>
        <status_details>Order Processed: Ready for UPS</status_details>
        <collection_index>1</collection_index>
      </package_tracking_status>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_city>HERFORD</status_city>
        <status_code>Pick-Up</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>pick_up</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>19:35:00</time>
          <date>03/24/2014</date>
        </status_date>
        <status_details>Origin Scan</status_details>
        <collection_index>2</collection_index>
      </package_tracking_status>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_city>HERFORD</status_city>
        <status_code>In transit</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>transit</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>23:00:00</time>
          <date>03/24/2014</date>
        </status_date>
        <status_details>Departure Scan</status_details>
        <collection_index>3</collection_index>
      </package_tracking_status>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_city>NURNBERG</status_city>
        <status_code>In transit</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>transit</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>05:54:00</time>
          <date>03/25/2014</date>
        </status_date>
        <status_details>Arrival Scan</status_details>
        <collection_index>4</collection_index>
      </package_tracking_status>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_city>NURNBERG</status_city>
        <status_code>In transit</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>transit</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>19:43:00</time>
          <date>03/25/2014</date>
        </status_date>
        <status_details>Departure Scan</status_details>
        <collection_index>5</collection_index>
      </package_tracking_status>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_city>OETZING</status_city>
        <status_code>In transit</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>transit</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>22:00:00</time>
          <date>03/25/2014</date>
        </status_date>
        <status_details>Arrival Scan</status_details>
        <collection_index>6</collection_index>
      </package_tracking_status>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_city>OETZING</status_city>
        <status_code>In transit</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>transit</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>09:27:00</time>
          <date>03/26/2014</date>
        </status_date>
        <status_details>Destination Scan</status_details>
        <collection_index>7</collection_index>
      </package_tracking_status>
      <package_tracking_status collection="true">
        <status_country>DE</status_country>
        <status_city>ARNSTORF</status_city>
        <status_zip>94424</status_zip>
        <status_recipient>MUELLER</status_recipient>
        <status_code>Delivered</status_code>
        <status_path collection="true">
          <collection_index>1</collection_index>
          <status_code>delivered</status_code>
        </status_path>
        <status_path_count>1</status_path_count>
        <status_date>
          <time>13:41:00</time>
          <date>03/26/2014</date>
        </status_date>
        <status_details>Package/Shipment delivered</status_details>
        <collection_index>8</collection_index>
      </package_tracking_status>
      <package_tracking_status_count>8</package_tracking_status_count>
    </package>
    <package_count>1</package_count>
    <shipment_tracking_id>1Z7110966853336416</shipment_tracking_id>
    <shipment_id>3a7b13db-b20a-45bd-8e05-575e1311f2fb</shipment_id>
    <shipment_tracking_status>
      <status_first_refresh_date>
        <time>12:39:40</time>
        <date>03/24/2014</date>
      </status_first_refresh_date>
      <status_last_refresh_date>
        <time>13:41:00</time>
        <date>03/26/2014</date>
      </status_last_refresh_date>
      <status_code>delivered</status_code>
      <status_date>
        <timezone>
          <name>UTC</name>
          <offset>+0000</offset>
        </timezone>
        <time>09:26:12</time>
        <date>08/01/2014</date>
      </status_date>
    </shipment_tracking_status>
    <collection_index>1</collection_index>
  </shipment>
  <shipment_count>1</shipment_count>
</workitem>

2.4.1 Basic structure

Code Block
languagexml
<?xml version="1.0" encoding="utf-8"?>
<workitem>
  <shipment collection="true">
    <package collection="true">
      <article collection="true">       
      </article>
    </package>
  </shipment>
</workitem>

2.4.1.1 Basic structure for multiple shipments

Code Block
languagexml
<?xml version="1.0" encoding="utf-8"?>
<workitem>
  <shipment collection="true">
    <package collection="true">
      <article collection="true">        
      </article>
    </package>
  </shipment>
  <shipment collection="true">
    <package collection="true">
      <article collection="true">        
      </article>
    </package>
  </shipment>
  <shipment collection="true">
    <package collection="true">
      <article collection="true">        
      </article>
    </package>
  </shipment>
</workitem>

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.

Code Block
languagexml
<?xml version="1.0" encoding="utf-8"?>
<workitem>
  <shipment collection="true">
    <package collection="true">      
    </package>
  </shipment>
</workitem>

2.4.1.3 Basic structure with multiple packages

Code Block
languagexml
<?xml version="1.0" encoding="utf-8"?>
<workitem>
  <shipment collection="true">
    <package collection="true">   
   
    </package>
    <package collection="true">

     </package>
    <package collection="true"> 

    </package>
  </shipment>
</workitem>

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:

Code Block
languagexml
  <timezone>
    <name>UTC</name>
    <offset>+0000</offset>
  </timezone>
  <time>09:26:12</time>
  <date>08/01/2014</date>

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 (MHP 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.

Include Page
Status codes
Status codes

3.2    Freight carrier shortcut

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

Include Page
Freight carrier shortcuts
Freight carrier shortcuts