Sorting support Interface documentation. Version 1.0

Transcription

1 Sorting support Interface documentation Version 1.0

2 : Date: Page 2 av 14 Revision history Version Date Comments created

3 : Date: Page 3 av 14 TABLE OF CONTENTS REVISION HISTORY SORTING SUPPORT REQUEST WITH HQF... FEL! BOKMÄRKET ÄR INTE DEFINIERAT. 2.1 General variables... Fel! Bokmärket är inte definierat address by zip number Office number by zip number REQUEST WITH XML... FEL! BOKMÄRKET ÄR INTE DEFINIERAT. 3.1 General variables... Fel! Bokmärket är inte definierat address via zip number... Fel! Bokmärket är inte definierat. 3.3 Office number via zip number... Fel! Bokmärket är inte definierat. 4 ERROR CODES TABLE OF OFFICE NUMBERS... 14

4 : Date: Page 4 av 14 1 Sorting support The service gives external customers the possibility to connect to Schenker s system and with a zip code get address or office number to the district office who is responsible for the specified zip code. The interface supports two methods: Searching for address by zip code and searching for office number by zip code. 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:

5 : Date: Page 5 av 14 2 General variables/nodes The general variables exist to administrate the communication and are joint for all communication. The general variables are: request, response and system. The variable data_list is a vector of information with the message itself and 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 contain one top node and se we enclose the above 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 sent to the service. The request can be done in two ways. Either searching for address by zip code ( ) or searching for office number by zip code (office). Add prefix request. to the variables if using HQF or place the nodes under <xml><request> if using XML. Name hqf Name - xml O Type Standard Explanation service.action <action> O String WDR Value select service.method <method> O String WDR Value or office Specifies request format.mime <format><mime> O String WDR Value text/xml or text/plain desired response format 2.2 Response Contains information received from the service. Is found after prefix response. If using HQF or under <xml><response> if using XML. Name - hqf Name - xml O Type Standard Explanation service.name <name> O String WDR Value MailFormManager Name of the service. service.version <version> O String WDR Version nummer (2.0) data_list_count <data_list_count> O Int WDR Number of items in the data_list

6 : Date: Page 6 av 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. Name hqf Name - xml O Type Standard Explanation error.id <error><id> O Int WDR Error code error.id = 0 means OK error.message <error><message> String WDR Error message statistics.remote.country _code statistics.remote.send_d ata_format statistics.remote.access _type statistics.remote.admin_ e_mail statistics.remote.applicat ion_name statistics.user.organizati on_id statistics.user.language_ code <statistics><remote><count ry_code> <statistics><remote><send _data_format> <statistics><remote><acce ss_type> <statistics><remote><admi n_e_mail> <statistics><remote><appli cation_name> <statistics><user><organiz ation_id> <statistics><user><languag e_code> String WDR Country code 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) String WDR address to the clients administrator String WDR Clients page or module which sends the request String WDR Clients VAT-number or Organisation number String WDR Languagecode for client, ex. sv_se

7 : Date: Page 7 av address by zip number This service returns address to customer services from office connected to specified zip number. 3.1 Request Contains information sent to the service. HQF Request on request.service.method= Add prefix data_list.0. to variable. XML Request on ... <request> <method> </method> </request>... Place the node under <xml><data_list><data index= 0 >. Name hqf Name - xml O Type Standard Explanation consignee_zip_number <consignee_zip_number> O String NAD CN DE 3251 Zip number search refer to. Example URL for search of address by zip number with HQF, response in XML: uest.service.method= &system.statistics.remote.country_code=se&system.statistics.remote.s end_data_format=text/xml&system.statistics.remote.access_type=a&system.statistics.remote.ad [email protected]&system.statistics.remote.application_name=web2&system.statistics. user.organization_id= &system.statistics.user.language_code=sv_se&data_list.0.consi gnee_zip_number=43430&request.format.mime=text/xml Example URL for search of address by zip number with HQF, response in text: uest.service.method= &system.statistics.remote.country_code=se&system.statistics.remote.s end_data_format=text/xml&system.statistics.remote.access_type=a&system.statistics.remote.ad [email protected]&system.statistics.remote.application_name=web2&system.statistics. user.organization_id= &system.statistics.user.language_code=sv_se&data_list.0.consi gnee_zip_number=43430&request.format.mime=text/plain Example URL search of address by zip number with XML, response in XML format:

8 : Date: Page 8 av 14 <?xml version="1.0" encoding="iso "?> <xml> <request> <format> <mime>text%2fxml</mime> </format> <action>select</action> <method> </method> </request> <system> <statistics> <remote> <country_code>se</country_code> <send_data_format>text%2fxml</send_data_format> <admin_e_mail>[email protected]</admin_e_mail> <access_type>a</access_type> <application_name>web2</application_name> </remote> <user> <organization_id> </organization_id> <language_code>se</language_code> </user> </statistics> </system> <data_list> <data index="0"> <consignee_zip_number>40010</consignee_zip_number> </data> </data_list> </xml> Example URL search of address by zip number with XML, response in text format: <?xml version="1.0" encoding="iso "?> <xml> <request> <format> <mime>text%2fplain</mime> </format> <action>select</action> <method> </method> </request> <system> <statistics> <remote> <country_code>se</country_code> <send_data_format>text%2fxml</send_data_format> <admin_e_mail>[email protected]</admin_e_mail> <access_type>a</access_type> <application_name>web2</application_name>

9 : Date: Page 9 av 14 </remote> <user> <organization_id> </organization_id> <language_code>se</language_code> </user> </statistics> </system> <data_list> <data index="0"> <consignee_zip_number>40010</consignee_zip_number> </data> </data_list> </xml> 3.2 Response Contains information received from the service. HQF Add prefix data_list.0. to variables. XML Place nodes under <xml><data_list><data index= 0 >. Name hqf Name -xml O Type Standard Explanation < > String address to customer services Exemple response in XML format: <?xml version="1.0" encoding="iso "?> <xml> <data_list> <data index="0"> < > [email protected]</ > </data> </data_list> <response> <name>mailformmanager</name> <version>2.0</version> <api_version>1.0</api_version> <data_list_count>1</data_list_count> </response> <system> <error> <id>0</id> </error> </system> <page_name /> </xml> Example response in text format: system.error.id=0& response.service.version=2.0&

10 : Date: Page 10 av 14 response.service.name=mailformmanager& response.data_list_count=1& response.service.api_version=1.0& data_list.0. = test%40test.test 4 Office number by zip number This service returns office number from specified zip number. 4.1 Request Contains information sent to the service. HQF Request on office: request.service.method=office. Add prefix data_list.0. to variables. XML Request on office:... <request> <method>office</method> </request>... Place nodes under <xml><data_list><data index= 0 > Name - hqf Name xml O Type Standard Explanation consignee_zip_number <consignee_zip_number> O String NAD CN DE 3251 Zip number search refer to. Example URL search of office number by zip number with HQF, response in XML format: uest.service.method=office&statistics.remote.country_code=se&statistics.remote.send_data_form at=text/xml&statistics.remote.access_type=a&[email protected]&st atistics.remote.application_name=web2&statistics.user.organization_id= &statistics.use r.language_code=sv_se&data_list.0.consignee_zip_number=43430&request.format.mime=text/x ml Example URL search of office number by zip number with HQF, response in text format: uest.service.method=office&statistics.remote.country_code=se&statistics.remote.send_data_form at=text/plain&statistics.remote.access_type=a&[email protected]&s tatistics.remote.application_name=web2&statistics.user.organization_id= &statistics.us

11 : Date: Page 11 av 14 er.language_code=sv_se&data_list.0.consignee_zip_number=43430&request.format.mime=text/p lain Example URL search of office number by zip number with XML, response in XML format: <?xml version="1.0" encoding="iso "?> <xml> <request> <format> <mime>text%2fxml</mime> </format> <action>select</action> <method>office</method> </request> <system> <statistics> <remote> <country_code>se</country_code> <send_data_format>text%2fxml</send_data_format> <access_type>a</access_type> <application_name>web2</application_name> </remote> <user> <organization_id> </organization_id> <language_code>se</language_code> </user> </statistics> </system> <data_list> <data index="0"> <consignee_zip_number>43430</consignee_zip_number> </data> </data_list> </xml> Example URL search of office number by zip number with XML, response in text format: <?xml version="1.0" encoding="iso "?> <xml> <request> <format> <mime>text%2fxml</mime> </format> <action>select</action> <method>office</method> </request> <system> <statistics> <remote> <country_code>se</country_code>

12 : Date: Page 12 av 14 <send_data_format>text%2fplain</send_data_format> <access_type>a</access_type> <application_name>web2</application_name> </remote> <user> <organization_id> </organization_id> <language_code>se</language_code> </user> </statistics> </system> <data_list> <data index="0"> <consignee_zip_number>43430</consignee_zip_number> </data> </data_list> </xml> 4.2 Response Information returned from the service. HQF Addera prefixet data_list.n. till variablerna, där n är ett index mellan XML <data> noderna ligger under <xml><data_list>. För varje sänding finns en <data index=? > nod med index 0-49 Name - hqf Name - xml O Type Standard Explanation office <office> String Office number Example of response in XML format: <?xml version="1.0" encoding="iso "?> <xml> <data_list> <data index="0"> <office>158</office> </data> </data_list> <response> <name>mailformmanager</name> <version>2.0</version> <api_version>1.0</api_version> <data_list_count>1</data_list_count> </response> <system> <error>

13 : Date: Page 13 av 14 <id>0</id> </error> </system> <page_name /> </xml> Example of response in text format: system.error.id=0& response.service.version=2.0& response.service.name=mailformmanager& response.data_list_count=1& response.service.api_version=1.0& data_list.0.office= 158

14 : Date: Page 14 av 14 5 Error codes The following error codes exist in the service: Error code Description Explanation 210 Invalid data Value not supported entered. 302 Illegal value Invalid value entered. 304 Mandatory information is missing Mandatory in data missing. 507 Internal server error Miscellaneous errors. E.g. database connection could not been established. 6 Table of office numbers 430 Borlänge 356 Linköping 448 Vänersborg 190 Borås 513 Luleå 604 Värnamo 455 Gävle 174 Malmö 638 Västerås 158 Göteborg 281 Nybro 653 Växjö 3848 Halmstad 679 Skara 422 Örebro 224 Helsingborg 372 Skellefteå 745 Örnsköldsvik 463 Hultsfred 125 Stockholm 661 Östersund 3426 Jönköping 943 Stockholm Coldsped 4770 Karlshamn 380 Sundsvall 315 Karlstad 414 Umeå 4721 Kristianstad 596 Visby