上海翻譯公司完成平臺(tái)接入技術(shù)英文翻譯
時(shí)間:2018-09-18 09:30 來源:未知 作者:dl 點(diǎn)擊:次
上海翻譯公司完成平臺(tái)接入技術(shù)英文翻譯
1 Foreword The purpose of this file aims to define the general external service interface of BSP enterprise service platform, quickly integrate the big customers’ proprietary system, connect the information flow between big customers and Shunfeng System, and realize the integration of the integral logistics supply chain, so as to reach the win-win results for Shunfeng and customers. 2 Description of interface specification Unify using UTF-8 coded XML message through external service interface; interface communication protocol supports WEBSERVICE, HTTP/POST and FTP; currently WEBSERVICE protocol is used mainly. General external service interfaces are classified as active access interface and external push interface. The external push interface based on FTP protocol does not need corresponding response message. Other protocols require correspond requests and corresponding messages. The following text defines the format and rules to be observed by the general external service interface message. ² Request message <Request service="service name" lang="zh-CN"> <Head>customer ID card number, check code</Head> <Body>Request data XML</Body> </Request> Key rules a) Service property and HEAD element predefined the service name, customer card number and check code. Combining with the customer IP address on request can satisfy the verification of system functional jurisdiction only by analyzing HEAD elements. The condition without functional jurisdiction needs no further analysis of internal Body data, which greatly improves the performance of blocking illegal access. b) Customer ID card number and check code shall be unified by the allocation of Shunfeng. c) long property is used for support the international request with the default value of zh-CN. ² Response message： <Response service="service name"> <Head>OK|ERR</HEAD> <BODY>Normal response message XML</BODY> <ERROR code="NNNN">Wrong detailed message </ERROR> </Response> Key rules a) Head element value is OK or ERR; OK represents normal transaction and ERR represents system or business exception; as for batch transaction settings, partial transaction exception must return OK value; exception transaction records must be indicated in returning BODY to avoid the next complete resending. b) Return to BODY element while Head element value is OK; return to ERROR element while Head value is ERR; BODY and ERROR elements cannot coexist together. c) “Code property value” in ERROR element is four-digit number. The description of error code refers to the last part of the reference files. ² Recording number of batch transaction is limited under 20 (referring to Shunfeng Website). Special business may define the limit not supporting the batch transaction or batch recorded number less than 20 itself. ² The definition of data elements of request or normal response data XML shall abide by the principle of separating defining necessary fields (including default value field), optional fields and extended fields. Meanwhile, fields shall be defined through the element property with the field value limited under 200 characters (less than 50 Chinese characters); necessary fields shall be defined through the element property; optional fields shall be defined “data element name +Option” element through the property under the data element; extended fields shall be defined by reserving the property of element <Extra> under the data element; the number of necessary fields shall be controlled under 10 as possible. <Order id="XXXX" …> <OrderOption payment="XXXX" …/> <Extra e1="XXXX" …/> </Order> The element property of OrderOption and value are defined by the specific business data. Extra element supports 20 properties to the utmost; property names are e1,…,e20, only supporting character string value. ² Try the utmost to reduce the field amount required for delivery in interface message through individualization service configuration of customers. For example, add the code of goods-delivering points in order message, allocate the monthly account and other data in the way of backstage-based customer + code of goods-delivery point, thus avoid delivering the affiliated monthly account in interface message. ² Request and response message elements shall be named by word order headed by capital letters, like “OrderResponse”; property name shall use small letters wholly, like “orderid”; subelements shall be expressed by using “/” path in the defined table, like “outeTrackingResponse/Route”. General external service interface has defined the express-type service interface presently; the reference address refers to the following. Http://bsp-oip/sf-express.com/bsp-ois/ws/expressService 3 Express-type service interface 3.1 Oder-placing (including filtering) 3.1.1 Function description Order-placing interface may provide the following three functions according to the customers’ requirements. 1） Customer system places order to Shunfeng in a unified way. 2） Allocate transport number for order number. 3） Filtering order 3.1.2 vDefinition of dominant message at interfaces
3.1.3 Optional field information
3.1.4 Extended field information Follow the extended field specification 3.1.5 Application scenario XML example ² Scenario 1 Scenario description ：customer placing order RequestXML： <Request service=”OrderService” lang="zh-CN"> <Head>j_custid（customer card number ）,checkwork（check code ）</Head> <Body> <Order orderid=”Order number” express_type=”express type ”j_company=”Sender’s company name ” j_contact=”sender’s contact personnel ”j_tel=”Contact telephone number”j_address=”Delivery address”d_company=”Receiver’s company name ”d_contact=”Receiver’s contact person ”d_tel=”Contact telephone number”d_address=”Receiver’s address” parcel_quantity=”Package number”pay_method=”Terms of payment ”> <OrderOption custid=”Monthly settlement card account ”j_shippercode=”Sender’s code”d_deliverycode=”Receiver’s code”cargo=”Cargo name ”cargo_total_weight=”Total weight ”insurance_amount=”Declaration value ”sendstarttime=”Time inquiring getting cargo ” mailno=”Mail transporting order number ” remark=”Remark ”> <AddedService name=”value-added service 1” value=”Value 1” value1=”Value 2” value2=”Value 3” value3=”Value 4” value4=”Value 5”/> <!-- ...// <AddedService>May be variant --> </OrderOption> <Extra e1=”extended field ” e2=”extended field ” e3=”extended field ” e4=”extended field ” e5=”extended field ” e6=”extended field ” e7=”extended field ” e8=”extended field ” e9=”extended field ” e10=”extended field ” e11=”extended field ” e12=”extended field ” e13=”extended field ” e14=”extended field ” e15=”extended field ” e16=”extended field ” e17=”extended field ” e18=”extended field ” e19=”extended field ” e20=”extended field ”/> </Order> </Body> </Request> Response XML： Successfully treated order ： <Response service=”OrderService”> <Head>OK</Head> <Body> <OrderResponse orderid=”Order number” mailno=”Main order,Sub-order 1,Sub-order 2,…,Sub-order n” originCode=”Original delivered place code” destCode=”Destination code ” filter_result=”Filtering results ” remark=”Remark ”/> </Body> </Response> Failed order treating： <Response service=”OrderService”> <Head>ERR</Head> <ERROR code="NNNN">Detailed wrong message </ERROR> </Response> 3.2 Confirming for order cargo delivery 3.2.1 Function description This interface is used for customers to deliver the important information, like express weight, posting time, etc. through this interface to Shunfeng after delivering the cargos to Shunfeng Consignment 3.2.2 Definition of main message at interface
3.2.3 Optional field information
3.2.4 Extended field information Follow the extended field specification 3.2.5 Application scenario XML example ² Scenario 1 Scenario description ： Request XML： <Request service=”OrderConfirmService” lang="zh-CN"> <Head>custid（customer card number ）,checkwork（check code ）</Head> <Body> <OrderConfirm orderid=”Order number” mailno=”Mail transporting order number ”> <OrderConfirmOption weight=”Express weight ” volume=”Lengh, width and height of delivered cargos ”/> <Extra e1=”extended field ” e2=”extended field ” e3=”extended field ” e4=”extended field ” e5=”extended field ” e6=”extended field ” e7=”extended field ” e8=”extended field ” e9=”extended field ” e10=”extended field ” e11=”extended field ” e12=”extended field ” e13=”extended field ” e14=”extended field ” e15=”extended field ” e16=”extended field ” e17=”extended field ” e18=”extended field ” e19=”extended field ” e20=”extended field ”/> </OrderConfirm> </Body> </Request> Response XML： Successfully confirmed order ： <Response service=”OrderConfirmService”> <Head>OK</Head> <Body> <OrderConfirmResponse orderid=”Order number” mailno=”Mail transporting order number ” remark=”Remark ”/> </Body> </Response> Failed confirmed order ： <Response service=”OrderConfirmService”> <Head>ERR</Head> <ERROR code="NNNN">Detailed wrong message </ERROR> </Response> 3.3 Order filtering 3.3.1 Function description Customer system sends the automatic filtering application through this interface to Shunfeng enterprise service platform, used for judging whether the sending and delivery address fall into the delivery scope of Shunfeng. The system can automatically judge whether the delivery address fall into the delivery scope of Shunfeng according to the addresses. If the receiver’s address falls into the scope, the mail can be delivered; otherwise, it cannot be delivered. 3.3.2 Definition of main messages at interface
3.3.3 Optional field information
3.3.4 Extended field message None. 3.3.5 Application scenario XML example ² Scenario 1 Scenario description ： RequestXML： <Request service=”OrderFilterService” lang="zh-CN"> <Head>j_custid（customer card number ）,checkwork（check code ）</Head> <Body> <OrderFilter filter_type=”filtering type” orderid=”Order number” d_address=”Receiver’s address”> <OrderFilterOption j_tel=”Sender’s telephonen number” j_address=”Sender’s address” d_tel=”Receiver’s telephone number”/> </OrderFilter> <!--...//including 5 as the maximum <OrderFiler>--> </Body> </Request> Response XML： Successfully treated filtering order： <Response service=”OrderFilterService”> <Head>OK</Head> <Body> <OrderFilterResponse orderid=”Order number” filter_result=”Whether it can be received or delivered ” origincode=”originally-delivering place code” destcode=”Destination code ” remark=”Remark ”/> ... </Body> </Response> Failed treated filtering order： <Response service=”OrderFilterService”> <Head>ERR</Head> <ERROR code="NNN">Detailed wrong message </ERROR> </Response> 3.4 Artificial filtering results push 3.4.1 Functional description If the customer gets the feedback results of: “3-to be confirmed” through the order-filtering interface, order number is provided and apply_type=2 when filtering order, then Shunfeng system will push the artificial filtering results to customer system when completing the artificial filtering order. Customer system shall provide a HTTURL meeting the following specification s, so as to benefit Shunfeng to push the artificial filtering data to the customer system. 1) Shufeng pushes data to the customer system in the way of HTTP POST; 2) Encoding format of applying method: “application/x-www-form-urlencoded; charset=UTF-8” 3) The pushed filtering results are sent to the customer system in XML format though the way of POST; 4) A POST method can push 5 filtering data at the utmost; 5) Encode XRL for the xml contents (The character set shall be UTF-8); 6) After customer system receives the requires, it shall firstly decode the received contents in URL and get the corresponding XML value. Then it obtains the corresponding filtering data. 7) After the customer system correctly processes XML information, it responds information to Shunfeng. Considering the processing efficiency, listing order push shows the success or failure of batch. 3.4.2 Definition of main messages at interface
3.4.3 Optional field message None 3.4.4 Extended field message None 3.4.5 Application scenario XML example ² Scenario 1 Scenario description ： Request XML： <Request service=”OrderFilterPushService”> <Head>OK</Head> <Body> <OrderFilterResult orderid=”Order number” filter_result=”Whether it can be received or delivered ” origincode=”Original delivered place code”destCode=”Destination code ” remark=”Remark ”/> <!--...//including 5 as the maximum <OrderFilterResult> --> </Body> </Request> Response XML： Successful Response ： <Response service=”OrderFilterPushService”> <Head>OK</Head> </Response> Failed Response ： <Response service=”OrderFilterPushService”> <Head>ERR</Head> <ERROR code="NNNN">Detailed wrong message </ERROR> </Response> 3.5 Route inquiry 3.5.1 Function description Provide the customer system with the function of inquiring mail order route of the Shunfeng through interface. Support the requiring functions of single or batch route. In the batch requiring, 10 mail transporting order numbers shall not be exceeded in the batch requiring. For a same batch, only a same language mail transporting route shall be allowed. Route requiring interface supports two requiring methods. 1) Requiring according to mail transpiring order number: provide the customer card number and mail transpiring order number in the inquiry request; the system only verifies the affiliation relationship of customers’ card number and all request mail transporting order number and the system only returns the mail order route information with correct affiliation relationship. 2) Requiring according to mail transpiring order number: provide the customer card number and mail transpiring order number in the inquiry request; the system only verifies the affiliation relationship of customers’ card number. As for the order number with correct affiliation relationship, find out the corresponding mail transporting order number and then return the route information of order corresponding to mail transporting order number. It is suitable for the customers placing orders through enterprise service platform. 3.5.2 Definition of main messages at interface
3.5.3 Optional field message None 3.5.4 Extended field message None 3.5.5 Application scenario XML example ² Scenario 1 Scenario description: inquire according to mail transporting order number Request XML： <Request service=”RouteService” lang="zh-CN"> <Head>custid（customer card number ）,checkwork（check code ）</Head> <Body> <RouteRequest tracking_type=”tracking type ” tracking_number=”order number 1,order number 2,…,order number n”/> </Body> </Request> Response XML： Successfully inquired route： <Response service=”RouteService”> <Head>OK</Head> <Body> <RouteResponse mailno=”Mail transporting order number ” orderid=”Order number”> <Route accept_time=”Route accepting time” accept_address=”Route accepting address” remark=”detailed description” opCode=”Operation code”/> <!--...//May including variant <Route>--> </RouteResponse> <!--...//Include 10 at the utmost <RouteResponse>--> </Body> </Response> Failed route inquiry <Response service=”RouteService”> <Head>ERR</Head> <ERROR code="NNNN">Detailed wrong message </ERROR> </Response> Failed response ： <Response service=”RouteService”> <Head>ERR</Head> <ERROR code="NNNN">Detailed wrong message </ERROR> </Response> 3.6 Route push 3.6.1 Functional description This interface is used to push the route information of mail transporting order regularly to the customer’s system. The customer system is required to provide an HTTP URL meeting the following specification so as to benefit Shunfeng to push route data to the customer system. The pushing method shall be increment pushing. The route of a same mail transporting order shall not be repeatedly pushed. 1) Shufeng pushes data to the customer system in the way of HTTP POST; 2) Encoding format of applying method: “application/x-www-form-urlencoded; charset=UTF-8” 3) The pushed filtering results are sent to the customer system in XML format though the way of POST; 4) A POST method can push 10 filtering data at the utmost; 5) Encode XRL for the xml contents (The character set shall be UTF-8); 6) After customer system receives the inquiry, it shall firstly decode the received contents in URL and get the corresponding XML value. Then it obtains the corresponding filtering data. 7) After the customer system correctly processes XML information, it responds information to Shunfeng. Considering the processing efficiency, route push shows the success or failure of batch. 3.6.2 Definition of main messages at interface
3.6.3 Optional field message None 3.6.4 Extended field message None 3.6.5 Application scenario XML example ² Scenario 1 Scenario description ： Request XML： <Request service=”RoutePushService” lang="zh-CN"> <Head>custid（customer card number ）,checkwork（check code ）</Head> <Body> <WaybillRoute id=”Route number” mailno=”Mail transporting order number ” orderid=”Order number” accept_time=”Route accepting time” accept_address=”Route accepting address” remark=”Detailed description” opcode=”Operation code”/> <!--//... 10 as the maximum value <WaybillRoute>--> </Body> </Request> Response XML： <Response service=”RoutePushService”> <Head>OK</Head> </Response> 4 Appendix 4.1 Reason code table
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
