上海翻譯公司完成平臺接入技術(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
|
Service name |
OrderService |
Batch transaction limiting |
Not supporting |
|
Interface type |
Access |
Protocol type |
WEBSERVICE |
|
Interface method |
public String sfexpressService(String XML); |
|
Dataelement<request> |
Order |
|
|
|
Name of necessary field |
Types（restricted） |
Default value |
Description |
|
orderid |
String(64) |
|
Customers’ order number, suggested as English letters +YYMMDD（date）+serial number,TB1207300000001 |
|
express_type |
String(5) |
Standard express |
Type of express-type products
1 Standard express
2 Shunfeng preference |
|
j_company |
String(100) |
_SYSTEM |
Sender’s company name, “_SYSTEM” means getting from system configuration if not provided. |
|
j_contact |
String(30) |
_SYSTEM |
Sender’s contact personnel, “_SYSTEM” means getting from system configuration if not provided. |
|
j_tel |
String(20) |
_SYSTEM |
Sender’s phone number, “_SYSTEM” means getting from system configuration if not provided. |
|
j_address |
String(150) |
_SYSTEM |
Sender’s detailed address, including prince, city and districts, for example, F10, Wangji Business Mansion, 11th Street, Xinzhou, Futian District, Shenzhen City, Guangdong Province, “_SYSTEM” means getting from system configuration if not provided. |
|
d_company |
String(100) |
|
Receiver’s company name |
|
d_contact |
String(30) |
|
Receiver’s contact personnel |
|
d_tel |
String(20) |
|
Receiver’s telephone number |
|
d_address |
String(150) |
|
Receiver’s detailed address, for example, F10, Wangji Business Mansion, 11th Street, Xinzhou, Futian District, Shenzhen City, Guangdong Province, |
|
parcel_quantity |
Number(5) |
1 |
Package number shall be provided if producing transport order number. A package corresponds to a transporting order number. Data must be correct. |
|
pay_method |
Number(1) |
_SYSTEM |
Type of payment: 1. Paid by sender; 2 Paid by receiver;3 Paid by the third party. The default value is 1. “_SYSTEM” means getting from system configuration if not provided. |
|
j_province |
String(30) |
_SYSTEM |
Filling requirement of the sender’s located province name field must be standard province name, like Guangdong Province |
|
j_city |
String(100) |
_SYSTEM |
Filling requirement of the sender’s located city name field must be standard city name, like Shenzhen City. |
|
d_province |
String(30) |
|
Filling requirement of the receiver’s located province name field must be standard province name, like Guangdong Province. |
|
d_city |
String(100) |
|
Filling requirement of the receiver’s located city name field must be standard city name, like Shenzhen City. |
|
|
|
|
|
Data element
<Response> |
OrderResponse |
|
|
|
Field name |
Type（restricted） |
Not-empty or not |
Description |
|
orderid |
String(64) |
No |
Order number |
|
mailno |
String(20) |
|
Transporting order number may be affiliated with order numbers like, integrated parts and sub-parts,separated by comma. |
|
origincode |
String(10) |
No |
Code for originally-sending place |
|
destcode |
String(10) |
No |
Destination code |
|
filter_result |
Number(2) |
|
Filtering order results: 1. Artificial selection; 2 collectable; 3 Uncollectable |
|
remark |
String(100) |
|
1. Receiver exceeding 2. Sender exceeding 3. Other reasons |
3.1.3 Optional field information
|
Data elements |
Order/OrderOption |
|
|
Field name |
Type（Restricted） |
|
Description |
|
custid |
String(20) |
Monthly card account number SYSTEM configurable |
|
template |
String(30) |
Template selection |
|
j_shippercode |
String(30) |
Sender code |
|
d_deliverycode |
String(30) |
Receiver code |
|
cargo |
String(4000) |
Cargo name; maybe have variant articles; use comma to separate cargo names for variant articles. For example, mobile phone, IPAD, charger. Require producing electronic transporting bill. This field must be delivered. |
|
cargo_count |
String(4000) |
Cargo quantity; be separated with comma for variant cargos, corresponding to the described cargo, for example, 2,1,3. |
|
cargo_unit |
String(4000) |
Cargo unit; be separated with comma for variant articles, corresponding to the described cargo, for example, piece, set, book. |
|
cargo_weight |
String(4000) |
Cargo weight; be separated with comma for variant cargos, corresponding to the described cargo, for example, 1.5,1.0,3.0 |
|
cargo_amount |
String(4000) |
Cargo unit price; be separated with comma for variant cargos, corresponding to the described cargo, for example, 1000,2000,1500 |
|
cargo_total_weight |
Number(10,2) |
Total weight of order cargos, unit KG; if this value is provided, it shall be>0 |
|
sendstarttime |
date |
The starting time of getting cargos, YYYY-MM-DD，HH24:MM:SS; for example: 2012-7-30 09:30:00. Default: system time for receiving order for the system |
|
mailno |
String(4000) |
Mailing transporting order; only one main mailing order for an order; in case of integrated order and sub-order, please be separated by comma; the main order shall be placed at the first position. “755123456789,001123456789,002123456789“ |
|
remark |
String(100) |
Remark |
|
Data element |
OrderOption/AddedService |
|
Field name |
Type（Restricted） |
Description |
|
name（ Defined corresponding relationship ） |
String(20) |
Value-added service, for example, COD, etc. |
|
value |
String(30) |
Value-added service value 1 |
|
Value1 |
String(30) |
Value-added service value 2 |
|
Value2 |
String(30) |
Value-added service value 3 |
|
Value3 |
String(30) |
Value-added service value 4 |
|
Value4 |
String(30) |
Value-added service value 5 |
|
|
|
|
|
Value-added service value description
|
Service |
NAME |
Description |
Remark |
|
Cash on delivery |
COD |
Value: cargo price; value1: customer value |
|
|
Support price |
INSURE |
Value: declared value |
|
|
MSG |
MSG |
Value: mobile phone number |
|
|
Packaging fee |
PKFEE |
Value: packaging fee |
|
|
SMS |
SMS |
Value is the mobile phone number and is the same as the receiver’s mobile phone number.
Value1 is the individualized words. |
|
|
Special support value |
SINSURE |
Value: service charge |
|
Special delivery
Special value-added service value |
SDELIVERY
SADDSERVICE |
value : service charge
value: service charge |
|
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
|
Service name |
OrderConfirmService |
Batch transaction limiting |
Not supporting |
|
Interface type |
Access |
Protocol type |
WEBSERVICE |
|
Interface method |
public String sfexpressService(String XML); |
|
Data element <Request> |
OrderConfirm |
|
|
|
Necessary field name |
Type (restricted) |
Default value |
Description |
|
orderid |
String(64) |
|
Order number |
|
mailno |
String(20) |
|
Mail transporting order number |
|
Data elements <Response > |
OrderConfirmResponse |
|
|
|
Field name |
Type (restricted) |
Non-empty or not |
Description |
|
orderid |
String(64) |
No |
Order number |
|
mailno |
String(20) |
No |
Mail transporting order number |
|
res_status |
Number(1) |
|
Remark: 1. Mismatch between order number and mail transporting order
2. Successful |
3.2.3 Optional field information
|
Data elements |
OrderConfirm/OrderConfirmOption |
|
Field name |
Type (restricted) |
Description |
|
weight |
Number(10,2) |
Order weight, unit: KG
單位 KG |
|
volume |
String(100) |
Length, width and height of delivered cargo shall be separated by comma; unit, CM, correct to 0.1. |
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
|
Service name |
OrderFilterService |
Batch transaction limit |
<=5 |
|
Interface type |
Access |
Protocol type |
WEBSERVICE |
|
Interface method |
public String sfexpressService(String XML); |
|
Data element <Request> |
OrderFilter |
|
|
|
Necessary field name |
Type (restricted) |
Default value |
Description |
|
filter_type |
Number(1) |
1 |
filtering type：1-automatic filtering (System judges according to the address base and returns the results); 2.- artificial filtering (System judges according to the address base. If it cannot judge whether the cargo is received or delivered, the system will produce the task of artificial judgment. The later work will be finished artificially. After completing the treating process, Shunfeng may automatically push to the customer system). |
|
orderid |
String(64) |
If
filter_type=2， it must be provided. |
Customer order number |
|
|
|
|
|
d_address |
String(150) |
|
Receiver’s detailed address includes prince, city and district. F10, Wangji Business Mansion, 11th Street, Xinzhou, Futian District, Shenzhen City, Guangdong Province, |
|
Data elements <Response > |
OrderFilterResponse |
|
|
|
Field name |
Type (restricted) |
Non-empty or not |
Description |
|
orderid |
String(64) |
|
Order number; if the artificial filtering order shall be provided by Shunfeng. This order value shall be provided. |
|
filter_result |
Number(2) |
Not |
Filtering order results: 1. Artificial selection; 2 collectable; 3 Uncollectable |
|
origincode |
String(10) |
|
Code for originally-sending place |
|
destcode |
String(10) |
|
Destination code; if it is can be received and delivered, this item cannot be empty. |
|
remark |
String(100) |
|
1. Receiver exceeding 2. Sender exceeding 3. Other reasons |
3.3.3 Optional field information
|
Data elements |
OrderFilter/OrderFilterOption |
|
Field name |
Type (restricted) |
Default value |
Description |
|
j_tel |
String(20) |
|
Sender’s telephone number |
|
country |
String (50) |
CN |
Sender’s country |
province |
String (30) |
|
Sender’s located province must be standard province name, for example Guangdong Province (“Province” cannot be omitted.) |
|
city |
String (100) |
|
Sender’s located city must be standard city name, for example “Shenzhen City”(“City” cannot be omitted.) |
county |
String (30) |
|
Sender’s located county/district must be standard county/district name, for example “Futian District”(“District” cannot be omitted.) |
|
d_country |
String(50) |
CN |
Receiver’s country |
d_province |
String (30) |
|
Receiver’s located province must be standard province name, for example Guangdong Province (“Province” cannot be omitted.) |
d_city |
String (100) |
|
Receiver’s located city must be standard city name, for example “Shenzhen City”(“City” cannot be omitted.) |
d_county |
String (30) |
|
Receiver’s located county/district must be standard county/district name, for example “Futian District”(“District” cannot be omitted.) |
j_address |
String(150) |
|
Sender’s detailed address, for example, F10, Wangji Business Mansion, 11th Street, Xinzhou, Futian District, Shenzhen City, Guangdong Province, |
|
d_tel |
String(23) |
|
Receiver’s telephone number |
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
|
Service name |
OrderFilterPushService |
Batch transaction limit |
<=5 |
|
Interface type |
Push |
Protocol type |
HTTP |
|
Interface method |
None |
|
Data element <Request> |
OrderFilterResult |
|
|
|
Necessary field name |
Type (restricted) |
Default value |
Description |
|
orderid |
String(64) |
|
Order number; if the artificial filtering order shall be provided by Shunfeng. This order value shall be provided. |
|
filter_result |
Number(2) |
No |
Filtering order results: 1. Artificial selection; 2 collectable; 3 Uncollectable |
|
origincode |
String(10) |
|
Code for originally-sending place |
|
destcode |
String(10) |
|
Destination code; if it is can be received and delivered, this item cannot be empty. |
|
remark |
String(100) |
|
1. Receiver exceeding 2. Sender exceeding 3. Other reasons |
|
mailno |
String(30) |
|
Mail transporting order number |
|
Data elements <Response > |
OrderFilterResultResponse |
|
Field name |
Type (restricted) |
Non-empty or not |
Description |
|
orderid |
String(4000) |
No |
Successfully received artificial filtering order number, in case of variant order number, they shall be separated by comma, for example”123,124” |
|
orderid_error |
String(4000) |
|
Unsuccessfully received artificial filtering order number, in case of variant order number, they shall be separated by comma, for example”123,124”Order number. The filtered data of this part will be regularly be-sent by Shunfeng.
|
|
|
|
|
|
|
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
|
Service name |
RouteService |
Batch transaction limit |
<=10 |
|
Interface type |
Access |
Protocol type |
WEBSERVICE |
|
Interface method |
public String sfexpressService(String xml); |
|
Data element <Request> |
RouteRequest |
|
|
|
Necessary field name |
Type (restricted) |
Default value |
Description |
|
tracking_type |
Number(2) |
1 |
Description of tracking types, tracking_type field：1-Track according to mail transporting order number, track_number in order nodes will be treated as per mail transporting order number; 2-Track according to order number and the track number shall in order points shall be treated as order number. |
|
tracking_number |
String(4000) |
|
Tracking number, if tracking_type=1, then the value shall be Mail transporting order number. If tracking_type=2, then the value shall be order number ; if variant order numbers exist, they shall be separated by comma, life “123,124,125” |
|
Data elements <Response > |
RouteResponse |
|
|
|
Field name |
Type (restricted) |
Non-empty or not |
Description |
|
mailno |
String(20) |
No |
Mail transporting order number |
|
orderid |
String(64) |
|
Order number |
|
Data elements <Response > |
RouteResponse/Route |
|
|
|
Field name |
Type (restricted) |
Non-empty or not |
Description |
|
accept_time |
Date |
No |
Route accepting time |
|
accept_address |
String(100) |
No |
Route accepting address |
|
remark |
String(150) |
No |
Specific Description |
|
opcode |
String(20) |
|
Operation code |
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
|
Service name |
RoutePushService |
Batch transaction limit |
<=10 |
|
Interface type |
Push |
Protocol type |
HTTP |
|
Interface method |
None |
|
Data element <Request> |
WaybillRoute |
|
|
|
Necessary field name |
Type (restricted) |
Default value |
Description |
|
id |
Number(15) |
|
Route number, each id stands for a different route. |
|
mailno |
String(20) |
No |
Mail transporting order number |
|
orderid |
String(64) |
|
Order number |
|
accept_time |
Date |
No |
Route accepting time |
|
accept_address |
String(100) |
No |
Route accepting city |
|
remark |
String(300) |
No |
Route description |
|
opcode |
String(20) |
|
Operation code |
|
Data elements <Response > |
WaybillRouteResponse |
|
|
|
Field name |
Type (restricted) |
Non-empty or not |
Description |
|
id |
String(4000) |
No |
Successfully received route number, variant route numbers shall be separated by comma, like “123,124,125“ |
|
id_error |
String(4000) |
No |
Unsuccessfully received route number, variant route numbers shall be separated by comma, like “123,124,125“. Shunefeng will regularly send these route number. |
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
|
Reason code |
Description |
Classification |
|
|
61** |
|
Short of necessary parameters |
|
|
6101 |
Short of request data: indispensible items |
Short of necessary parameters |
|
|
6102 |
Sender’s company name: empty |
Illegal verification in key field |
|
|
6103 |
Sender’s contact personnel : empty |
|
|
|
6104 |
Sender’s province : empty |
|
|
|
6105 |
Sender’s city : empty |
|
|
|
6106 |
Sender’s detailed information : empty |
|
|
|
6107 |
Receiver’s company name: empty |
|
|
|
6108 |
Receiver’s contact personnel : empty |
|
|
|
6109 |
Receiver’s province : empty |
|
|
|
6110 |
Receiver’s city : empty |
|
|
|
6111 |
Receiver’s address : empty |
|
|
|
6112 |
Receiver’s country: can’t be empty |
|
|
|
6113 |
Receiver’s prince: can’t be empty |
|
|
|
6114 |
Customer’s order number must be provided. |
|
|
|
6115 |
Receiver’s located city name: can’t be empty |
|
|
|
6116 |
Receiver’s located county/district: can’t be empty |
|
|
|
6117 |
Receiver’s detailed address : can’t be empty |
|
|
6118 |
Order number : can’t be empty |
|
|
6119 |
Receiver’s contact telephone number: can’t be empty |
|
|
6120 |
Express type : can’t be empty |
|
|
6121 |
Sender’s contact telephone number: can’t be empty |
|
|
6122 |
Illegal filtering type |
|
|
6123 |
Mail transporting order number : can’t be empty |
|
|
6124 |
Terms of payment: can’t be empty |
|
|
6125 |
Producing electronic mail transporting order; cargo name can’t be empty |
|
|
6126 |
Illegal monthly settlement account |
|
|
6127 |
Value-added service name: can’t be empty |
|
|
6128 |
Illegal value-added value service |
|
|
8*** |
|
Function verification |
|
8000 |
Illegal message parameters |
Invalid parameters |
|
8001 |
Unauthorized IP |
Invalid parameters |
|
8002 |
Unauthorized service (function ) |
|
|
8003 |
Inquiring order number exceeds the maximum limit |
|
|
8004 |
Route inquiring number exceeds the limit. |
|
|
8005 |
Inquiring number exceeds the limit. |
|
|
8006 |
An order has been placed. Order-confirming request cannot be received |
|
|
8007 |
This order is confirmed. Order-confirming request cannot be received |
|
|
8008 |
The artificial filtering order of the order has not been confirmed. Order-confirming request cannot be received |
|
|
8009 |
This order cannot be received and delivered. Order-confirming request cannot be received |
|
|
8010 |
This order has not been filtered. Order-confirming request cannot be received |
|
|
8011 |
Binding relationship between the customer card number and the mail transporting order number is not established. |
|
|
8012 |
Binding relationship between the customer card number and the order number is not established. |
|
|
8013 |
Inquiring order number is not uploaded. |
|
|
8014 |
Incorrect check code |
|
|
8015 |
Mail transporting order number is not uploaded. |
|
|
8016 |
Repeated order placing |
|
|
8017 |
Unmatched order number and mail transporting order number |
|
|
8018 |
Unobtained order message |
|
|
8019 |
Conformed order |
|
|
8020 |
Binding relationship between the order and mail transporting order does not exist. |
|
|
8021 |
Customer card number: empty |
|
|
|
8022 |
Check number: empty |
|
|
8023 |
Service name: empty |
|
|
8024 |
An order has not been placed. |
|
|
8025 |
The service is not provided or does not exist. |
|
|
8026 |
Nonexistent customers |
|
|
8027 |
Nonexistent business template |
|
|
8028 |
Customers fail to configure the business. |
|
|
8029 |
Customers fail to configure default template. |
|
|
8030 |
The legal template of this time is not found. |
|
|
8031 |
Data error. Template is not found. |
|
|
8032 |
Data error. Business configuration is not found. |
|
|
8033 |
Data error. Business property is not found. |
|
|
8034 |
Repeatedly register artificial filtering result pushing. |
|
|
8035 |
Produce electronic mail transporting order. The mail transporting order number must be existent. |
|
|
8036 |
Registry of route pushing must have mail transporting number. |
|
|
|
|
|
|
4*** |
|
System verification |
|
4001 |
System has data error or running exception. |
|
|
4002 |
Message analysis error |
|
世聯(lián)翻譯-讓世界自由溝通！專業(yè)的全球語言翻譯供應(yīng)商，
上海翻譯公司專業(yè)品牌。絲路沿線56種語言一站式翻譯與技術(shù)解決方案，專業(yè)
英語翻譯、
日語翻譯等文檔翻譯、同傳口譯、視頻翻譯、出國外派服務(wù)，加速您的全球交付。
世聯(lián)
翻譯公司在北京、上海、深圳等國際交往城市設(shè)有翻譯基地，業(yè)務(wù)覆蓋全國城市。每天有近百萬字節(jié)的信息和貿(mào)易通過世聯(lián)走向全球！積累了大量政商用戶數(shù)據(jù)，翻譯人才庫數(shù)據(jù)，多語種語料庫大數(shù)據(jù)。世聯(lián)品牌和服務(wù)品質(zhì)已得到政務(wù)防務(wù)和國際組織、跨國公司和大中型企業(yè)等近萬用戶的認(rèn)可。
