Tracking Sweden API. Version 3.1

Transcription

1 Tracking Sweden API Version 3.1

2 : Date: Sida 2 av 14 Revision history Version Date Comments Removed statistic variables and made remaining optional Added XML parametres as well as reorganized the document Adjusted and added texts/codes for status_event_code 2.05b Added gls_shipment. 2.05a Added definition of request variables: request.format.mime och request.format.type New error code 9 Delivered to terminal by shipper New field handling_unit_number (kolliid) added and new actions (status_event_code). Note that code 13 now is Picked up by consignee (was a duplicate with code 4 Arrived ) Added status_event_time, new event (status_event_code): In terminal (13) Collected (14).

3 : Date: Sida 3 av 14 TABLE OF CONTENTS REVISION HISTORY TRACKING SWEDEN GENERAL VARIABLES/NODES Request Response System INFORMATION CONCERNING ONE CONSIGNMENT (WAYBILL) Request Response Consignment events Codes for status_event_code INFORMATION CONCERNING CUSTOMER CONSIGNMENTS (CUSTOMER) Request Response... 13

4 : Date: Sida 4 av 14 1 Tracking Sweden The service gives external customers the possibility to connect to Schenker s systems and always get accurate information. The interface supports two methods: To get information about current status of a consignment by waybill number or from client ID and reference get a list of waybill numbers. Examples ready to run will be found in the documentation. Just copy and paste them in to your web browser to get an overview of the possibilities. The service can be invoked by httprequest using XML or HQF (http Query Format) and can also be returned in these two formats. Examples of requests and responses for both ways can be found in this document. Figure 1 Flow chart of the service For further information of how Schenker s online services are built and should be invoked we recommend reading our separate introduction. URL to use for HQF: URL to use for XML:

5 : Date: Sida 5 av 14 2 General variables/nodes The general variables are for administrating communication and are mutual for all communication. The variables are: request, response and system. The variable data_list is an array with the message information which is specific per method. For XML it will be <request>, <response>, <system> and <data_list> which consists of <data index=? > nodes with the message information. An XML document can only contaion one top node and se we enclose the aboce mentioned nodes with <xml>. A request will thus have the following structure: <?xml version= 1.0?> <xml> <request>...</request> <response>...</response> <system>...</system> <data_list> <data index= 0 >...</data> </data_list> </xml> The title M symbolizes mandatory field. 2.1 Request Contains information to the service. The request can be done in two ways. Either with client ID and reference (customer) or with waybill number or package ID (waybill). Add prefix request. to the variables if using HQF or place the nodes under <xml><request> if using XML. service.action <service><action> M String WDR 10 Value select service.method <service><method> M String WDR 10 Value customer or waybill format.mime <format><mime> M String WDR - Response format. Value text%2fhtml, text%2fplain or text%2fxml format.type <format><type> String WDR - Response type. Value url_simple eller full. Which to use is set by response format. If response format is text%2fplain, the type should be url_simple. If response format is text%2fhtml, the type should be full. For text%2fxml the type could be set to anything. 2.2 Response Contains information from the service. Is found after prefix response. If using HQF or under <xml><response> if using XML.

6 : Date: Sida 6 av 14 service.name <service><name> M String WDR - Name of the service service.version <service><version> M String WDR - Version number (1.0) data_list_count <data_list_count> M Int WDR - Number of items in the data_list 2.3 System Contains error code generated from the system. For HQF system.error.id=0 means OK. For XML <system><error><id>0</id></error></system> means OK. Also contains statistic variables to the system. Add prefix system. if using HQF or place the nodes under <xml><system> if using XML. error.id <error><id> M Int WDR 5 Errorcode error.message <error><message> String WDR 100 Error message statistics.remote.coun try_code statistics.remote.send _data_format statistics.remote.acce ss_type statistics.remote.appli cation_name statistics.remote.admi n_e_mail statistics.user.organiz ation_id statistics.user.langua ge_code <statistics><remote> <country_code> <statistics><remote> <send_data_format> <statistics><remote> <access_type> <statistics><remote> <application_name> <statistics><remote> <admin_e_mail> <statistics><user><o rganization_id> <statistics><user><l anguage_code> String WDR - Countrycode for client, ex. se or us String WDR - Clients way of sending the request, xml or hqf (Http Query Format) String WDR - Clients request type, A (browser), B (wap-device) String WDR - Clients page or module which sends the request String WDR - address to the clients administrator String WDR - Clients VAT-number or Organisation number String WDR - Languagecode for clinet, ex. sv_se 3 Information concerning one consignment (waybill) Returns current status of consignment. 3.1 Request Information being sent to the service. HQF Request on waybill number: request.service.method=waybill Add prefix data_list.0. to variable. XML

7 : Date: Sida 7 av 14 Request on waybill number:... <request> <service> <method>waybill</method> </service> </request>... Place the node under <xml><data_list><data index= 0 >. transport_document_ number handling_unit_numbe r <transport_documen t_number> <handling_unit_num ber> M String RFF 1153-AAS DE Transport document number of the shipment, ex; waybillnumber or consignment number String - 18 Package ID Example of requesting current status with XML via waybill number, response in XML format: <?xml version="1.0" encoding="iso "?> <xml> <request> <format> <mime>text%2fxml</mime> <type>full</type> </format> <service> <method>waybill</method> <action>select</action> </service> </request> <data_list> <data index="0"> <consignor_reference_number /> <consignor_identification /> <handling_unit_number /> <transport_document_number>[waybill number]</transport_document_number> </data> </data_list> <system> <statistics> <remote> <country_code>se</country_code> <send_data_format>web2</send_data_format> <admin_e_mail>[clients administrators address]</admin_e_mail> <access_type>a</access_type> <application_name>[clients application where from the request is sent]</application_name>

8 : Date: Sida 8 av 14 </remote> <user> <organization_id>[clients VAT/org-number]</organization_id> <language_code>sv</language_code> </user> </statistics> </system> <response /> </xml> (same as above but with test values, ready to be tested in web browser) ncoding="iso "%20?><xml><request><format><mime>text%2fxml</mime><type>full</type></format><servic e><method>waybill</method><action>select</action></service></request><data_list><data%20i ndex="0"><consignor_reference_number%20/><consignor_identification%20/><handling_unit_nu mber%20/><transport_document_number> </transport_document_number></data></ data_list><system><statistics><remote><country_code>se</country_code><send_data_format> web2</send_data_format><admin_e_mail>[email protected]</admin_e_mail><access_type>a</acc ess_type><application_name>testexempel</application_name></remote><user><organization_id > </organization_id><language_code>sv</language_code></user></statistics></syst em><response%20/></xml> To do the same request but get the response in textformat, change text%2fxml to text%2fplain and full to url_simple. Example of requesting current status with HQF via waybill number, response in XML format: number= &data_list.0.handling_unit_number=&data_list.0.consignor_reference_numb er=&data_list.0.consignor_identification=&request.format.mime=text%2fxml&request.format.type =full&request.service.action=select&request.service.method=waybill&system.statistics.remote.sen d_data_format=web2&system.statistics.user.organization_id= &system.statistics.user. language_code=sv&system.statistics.remote.country_code=se&system.statistics.remote.admin_e [email protected]&system.statistics.remote.access_type=a&system.statistics.remote.applicati on_name=testexempel To do the same request but get the response in textformat, change text%2fxml to text%2fplain and full to url_simple. 3.2 Response Information returned from the service. HQF Add prefix data_list.0. to variables. XML Place nodes under <xml><data_list><data index= 0 >.

9 : Date: Sida 9 av 14 contract_condition_co de <contract_condition_ code> String TSR 4065-PAR 4065-COM 4065-BUD 4065-CLD 4065-DIR 4065-SPC - Product PAR = Parcel, COM = Comfort, BUD = Budget, CLD = Coldsped, DIR = Direct, SPC = Special transport_document_ number departure_place_nam e destination_place_na me <transport_documen t_number> <departure_place_n ame> <destination_place_ name> String RFF 1153-AAS DE 1154 departure_place_x_c oordinate <departure_place_x _coordinate> departure_place_y_c <departure_place_y oordinate _coordinate> destination_place_x_ <destination_place_ coordinate x_coordinate> destination_place_y_ <destination_place_ coordinate y_coordinate> acceptance_date <acceptance_date> Date DTM DE Transport document number of the shipment, ex; waybillnumber or consignment number String TDT DE Departure city, LOC-3224(3227=5). String TDT - Arrival city, LOC-3224(3227=8) DE 3224 Int - Departure city-x-coordinate Int - Departure city -y-coordinate Int - Arrival city-x-coordinate Int - Arrival city -y-coordinate - Day of transport gls_shipment <gls_shipment> String 1 Flag if event outbound Europe exists. status_event_list <status_event_list> Array - An array with transmission events. Example of response in XML format: <?xml version="1.0"?> <xml> <response> <data_list_count>1</data_list_count> <service> <version>3.0</version> <name>trackandtrace_002</name> </service> </response> <system> <error> <message>your+request+was+successfully+processed.</message> <id>0</id> </error> </system> <data_list> <data index="0"> <status_event_list> <status_event index="0"> <status_event_date> </status_event_date> <status_event_time>13.17</status_event_time> <status_event_code>4</status_event_code> <status_event_place>kristianstad</status_event_place> </status_event>

10 : Date: Sida 10 av 14 </status_event_list> <contract_condition_code>%26nbsp%3b</contract_condition_code> <transport_document_number> </transport_document_number> </data> </data_list> <request /> </xml> Example of response in text format: response.data_list_count=1& response.service.version=3.0& response.service.name=trackandtrace_002& system.error.message=your+request+was+successfully+processed.& system.error.id=0&data_list.0.status_event_list.0.status_event_date= & data_list.0.status_event_list.0.status_event_time=13.17& data_list.0.status_event_list.0.status_event_code=4& data_list.0.status_event_list.0.status_event_place=kristianstad& data_list.0.contract_condition_code=%26nbsp%3b& data_list.0.transport_document_number= Consignment events HQF status_event_list is an array with consignment/waybill events with max 16 entries (0-15). Example: If Stockholm is the departure area (first event), it results in the following: data_list.0.status_event_list.0.status_event_place=stockholm XML <status_event_list> contains max 16 <status_event> nodes with index Example: If Göteborg is the departure area (first event), it results in the following: <data_list> <data index= 0 >... <status_event_list> <status_event index= 0 > <status_event_place>g%f6teborg</status_event_place> </status_event>... </status_event_list> </data> </data_list>

11 : Date: Sida 11 av 14 See also chapter 3.4 concerning event codes for status_event_code status_event_code <status_event_code > Int STS DE Code for event. IMPORTANT! Schenker use exclusive codes.. status_event_place status_event_date <status_event_place > <status_event_date > String STS DE 3225 Date status_event_time <status_event_time> String (5) STS DE NAD-3036/3039 (3035=CA) Name of Schenker terminal - Date of event Time of event 3.4 Codes for status_event_code Possible codes for status_event_code Schenker use exclusive codes, which doesn t adhere Edifacts suggested standard. 1 Departed 2 Out for delivery 3 Delivered 4 Arrived 6 Advise 7 Not delivered 8 Collected 13 Picked up by consignee 14 Picked up by consignee 15 Not delivered 17 Delivery attempt unsuccessful 18 Delivery attempt unsuccessful 19 Delivery attempt unsuccessful 27 Advise finished 29 Returned to shipper 30 Delivered to agent 32 Not delivered 36 Not delivered 37 Not delivered 39 epod available 4 Information concerning customer consignments (customer) Recieves client ID and reference and returns an array of waybill numbers, not current status of consignments. 4.1 Request Information being sent to the service. HQF Request on client ID/reference: request.service.method=customer.

12 : Date: Sida 12 av 14 Add prefix data_list.0. to variables. XML Request on client ID/reference:... <request> <service> <method>customer</method> </service> </request>... Place nodes under <xml><data_list><data index= 0 > consignor_identificati on <consignor_identific ation> M String NAD-CZ DE Customer number, 8 digits consignor_reference_ number <consignor_referenc e_number> M String RFF 18 Customer reference Example of search of waybill number with XML, response in XML format: <?xml version="1.0" encoding="iso "?> - <xml> - <request> - <format> <mime>text%2fxml</mime> <type>full</type> </format> - <service> <method>customer</method> <action>select</action> </service> </request> - <data_list> - <data index="0"> <consignor_reference_number>[reference]</consignor_reference_numb er> <consignor_identification>[client ID]</consignor_identification> <handling_unit_number /> <transport_document_number /> </data> </data_list>

13 : Date: Sida 13 av 14 - <system> - <statistics> - <remote> <country_code>se</country_code> <send_data_format>web2</send_data_format> <admin_e_mail>[clients administrators address]</admin_e_mail> <access_type>a</access_type> <application_name>[clients application where from the request is sent]</application_name> </remote> - <user> <organization_id>[clients VAT/org-number]</organization_id> <language_code>sv</language_code> </user> </statistics> </system> <response /> </xml> Example of search of waybill number with HQF, response in XML format: data_list.0.transport_document_number= &data_list.0.handling_unit_number= &data_list.0.consignor_reference_number=[reference] &data_list.0.consignor_identification=[client ID] &request.format.mime=text%2fxml &request.format.type=full &request.service.action=select &request.service.method=customer &system.statistics.remote.send_data_format=web2 &system.statistics.user.organization_id=[clients VAT/org-number] &system.statistics.user.language_code=sv &system.statistics.remote.country_code=se &system.statistics.remote.admin_e_mail=[clients administrators address] &system.statistics.remote.access_type=a &system.statistics.remote.application_name=[clients application where from the request is sent] Change blue text to your own information. To do the same request but get the response in textformat, change text%2fxml to text%2fplain and full to url_simple. Notice that the request must not have space between variables (as example above). 4.2 Response Information returned from the service. HQF Addera prefixet data_list.n. till variablerna, där n är ett index mellan 0-49.

14 : Date: Sida 14 av 14 XML <data> noderna ligger under <xml><data_list>. För varje sänding finns en <data index=? > nod med index 0-49 transport_document_ number <transport_documen t_number> String RFF 1153-AAS DE 1154 acceptance_date <acceptance_date> Date DTM DE Consignment/waybill number 10 digits - Day of transport