Express 100 Express query interface (API) interface specification document - detailed version

Courier 100 Logistics query interface Now support 1200 Daily Express and logistics company order number query 、 Express outlets telephone inquiries 、 Express price inquiry 、 Express online mail service . Recent Express 100 The logistics query interface is launched for some B2C Shopping malls and mobile phone applications need express order number query interface, and developed a free express order number query interface service , The daily data transmission volume is nearly 25G, The amount of data storage is nearly 65G, Near throughput 40 Ten thousand / second , Strong technical foundation ！

One 、 Interface selection guide

Two 、 Courier 100 Information push interface

2.1 System structure and process

The express information push service is provided by Subscription interface 、 Tracking system and Callback interface form ： Your company adopts the chapter of this document 2.2.1、2.2.2 The subscription interface will be queried by the specification of 、 Tracked waybill number （ also called “ courier number ”、“ Odd Numbers ”, The same below ） Submit to express 100, At the same time, according to the chapter 2.3.1、2.3.2 To develop a callback interface , And pass the address of the callback interface through the chapter 2.2.1 Of callbackurl Field submitted to the courier 100. Courier 100 After receiving these waybills, they will be tracked （ also called “ monitor ”、“ Inquire about ”, The same below ）, When the waybill status changes , Courier 100 Then, the tracking information of the waybill is retrieved by calling the callback interface （ also called “ Query results ” The same below ） Push to your company , Until the end of the life cycle of these waybill numbers （ General with “ Signed for ” Subject to ）.

1. We have defined the subscription interface protocol , Simply follow the instructions to submit the request , See below. 2.2;
2. The callback interface needs to be developed by your company according to our agreement , The agreement is detailed below 2.3.
3. 2.5 All express company codes are attached , If the company you need is not on the list , Please contact us directly to add .

2.2 Subscription interface protocol

2.2.1 Subscription request

notes ： A subscription request is a request for web request , It is used to state that your company needs our help to track a waybill number of an express company , A single order can be subscribed successfully once , Courier 100 After receiving the subscription, the order number will be monitored and pushed . A subscription is equivalent to a form request, That is, a program is used to simulate http Page form request , for example ：

<form method="post" name="" action=" http://poll.kuaidi100.com/poll">

<input type="text" name="schema" value="json" />

<input type="text" name="param" value="{"company":"yuantong","number":"12345678","from":" Nanshan District, Shenzhen City, Guangdong Province ","to":" Chaoyang District of Beijing City ","key":"XXX","parameters":{"callbackurl":" The address of your callback interface , Such as http://www. Your domain name .com/kuaidi?callbackid=...", "salt":"XXXXXXXXXX","resultv2":"1"}}" >

</form>

explain ：

• company It's company code , Please refer to the end of the document （ All in lowercase , Strict and consistent requirements ）.
• number It's the express order number , Not longer than 32 A combination of digits and letters , allow “-” character , Other characters will cause the subscription to fail .
• from It is the correct place name in Chinese , It is suggested that , We don't offer , If provided, it must be correct , Otherwise, the express order status will be misjudged . The format is readable and recognizable in Chinese province - City - District that will do , Courier 100 The program will perform intelligent matching .
• to It is the correct place name in Chinese , It is suggested that , We don't offer , This content can improve the accuracy of signing in status judgment , Help to distinguish “ Sign for ” And “ Withdrawal of signature ”; in addition , After the express order arrives at the destination, the monitoring times will be increased , If not, there is no such service . The format is readable and recognizable in Chinese province - City - District that will do , Courier 100 The program will perform intelligent matching .
• key By express 100 Identification mark of the initiator provided , No mistake （ Pay attention to case ）, Please send it by express 100 Business contacts ask for .
• parameters Is a customizable HashMap.

1. callbackurl： The address of the callback interface , Provided by your company , It is used to receive the tracking information of the waybill pushed by us , The specification convention of the callback interface is shown in 2.3 explain . Must be a public network accessible address , If the development phase cannot provide , Express delivery is available 100 The background test page is combined with the local html Page mode simulation .
2. salt： Random string for signature （ Optional ）, After adding this paragraph, we will use this string to add a signature when pushing data to you , You will verify it upon receipt . No spaces or invisible characters , It is recommended to repeat the subscription for each express order salt identical , Avoid inconsistent signatures caused by multiple subscriptions to express orders . For our use of signatures, see 2.3.1 explain .
3. resultv2： Advanced push results , The administrative division address is resolved for you on each line of the express message , code , And the status of this line .

• This interface can only submit one request and one document number at a time , If the quantity is very large , Consider moderate concurrent commit .

2.2.2 Subscription response message and error code explanation

After we receive your subscription request , The document number will be saved to our server first , Then return the message and code of whether the subscription was successful to your company , You need to save these codes to the log , For reconciliation , , The specific message and code are described as follows ：

explain ：

• result: true It means success ,false It means failure
• returnCode:

   200: Submit successfully

   701: Express companies that refuse to subscribe

   700: There is an error in the subscriber's subscription data （ Such as unsupported express companies 、 The order No. is blank 、 The order number is too long ） Or wrong callback address

   702: POLL: The express company corresponding to this document number cannot be identified

   600: You are not a legal subscriber （ That is, authorization Key error ）

601: POLL:KEY Has expired

   500: Server error （ Express delivery 100 There is a gap or temporary exception on the server , Sometimes if the request is not submitted according to the specification , For example, the parameters of the express company are misspelled , This error will also be reported ）

501: Duplicate subscription （ Please pay special attention to ,501 It means that this order has been subscribed successfully and is still in the process of tracking （ That is, the number of the order status=polling）, Courier 100 Your server will ignore your latest subscription request , To return to 501. One waybill number only needs to submit one subscription , To submit multiple subscriptions , Please wait until you receive the order No status=abort or shutdown Then submit the subscription every half an hour , See section of this document for details 13 page “ Important reminder ” Partial description ）

2.3 Callback interface protocol

2.3.1 Callback request

notes ： Callback request （ Also known as “ push ”） Means by express delivery 100 Send a request to your callback interface , It is used to submit the logistics tracking information of the waybill to your company . The callback is also equivalent to a form request, Express delivery 100 Simulate the following http Page form request , for example ：

<form method="post" name="" action="[callbackurl]">

<input type="text" name="param" value="{XXX}" >

<input type="text" name="sign" value=" Signature string " />

</form>

explain ：

• salt: That is, you submitted by means of a subscription request salt The content of , See 2.2.1 Explanation .
• status：

1、 When the express order is still under monitoring , be status=polling;

2、 When the express bill itself has been signed ,status=shutdown, That is, the monitoring is over , Indicates that the life cycle of this order has ended ;

3、 If the order number continues from the submission of subscription 3 I can't find the tracking information for days , Or the doc No. will not be updated from a node and will continue 30 God , We will stop tracking this order , And give your callback interface （callbackurl） push message by “3 Days query without record ” or “60 When the sky doesn't change ”、status= abort Reminder , Monitoring aborts .

4、 After a waybill is submitted to us , If we keep checking 3 I can't find the result for days , We will

（1） Judge whether the express company code submitted by your company is correct , If correct , Callback interface for your company （callbackurl） Push the following information ：

{"message":"3 Days query without record ","status":"abort","autoCheck":"0","comOld":"","comNew":"","lastResult":{"message":" The parameters of the express company are abnormal ： The order No. does not exist or has expired ","state":"0","data":[],"status":"201","com":"XXXXX","nu":"XXXXXXXX","ischeck":"0","condition":""},"billstatus":""}

（2） If we judge that the express company code submitted by your company is wrong , We'll help with 【 Correct express company code 】+【 The original waybill number 】 Resubmit the subscription and turn on monitoring （ Subsequently, if the doc No. is monitored to be updated, it will be sent to your callback interface （callbackurl） Push information with the following fields ：autoCheck=1、comOld= The original company code 、comNew= New company code ）; And give your callback interface （callbackurl） Push a message with the following fields ：status=abort、autoCheck=0、comOld It's empty 、comNew= Corrected express company code ：

{"message":"3 Days query without record ","status":"abort","autoCheck":"0","comOld":"","comNew":"ems（ Here is a demonstration ）","lastResult":{"message":" The parameters of the express company are abnormal ： The order No. does not exist or has expired ","state":"0","data":[],"status":"201","com":"XXXXX","nu":"XXXXXXXX","ischeck":"0","condition":""},"billstatus":""}

therefore ：

1、 If it is judged that status=abort And comNew It's empty , Then press the following 【 Important reminder 】 Resubmit the subscription as shown in ;

Important reminder ：

about status= abort and message Contained in the “3 God ” Keywords and comNew It's empty Express order for , The following processing logic needs to be added ：

1. If there are special staff , Sure : List the express list to the staff , It is up to the staff to judge whether this form is false ： If this order is a real one , Then send this order to express again 100 Submit once ; If this order is false , Then this order will be marked as false , And this order will not be submitted to the express 100. If there is no dedicated staff , Please directly use the second method below ;
2. If there is no dedicated staff , Sure ： Upon receipt of status=abort and message Contained in the “3 God ” Keywords and comNew Empty prompt 10 Minutes later , Send this express bill to express again 100 Submit subscription , If you still receive... After resubmission status= abort, Then send it to the express again 100 Submit , such , stay If it is submitted repeatedly in the same month 3~4 I still receive it every time status= abort, Then this order is false , It is no longer necessary to submit this order to express 100.

  For the express bill repeatedly submitted in the same natural month , Only one charge will be made at the time of settlement , For settlement documents submitted repeatedly over two natural months , Settle the expenses twice .

2、 If it is judged that status=abort And comNew Not empty , You do not need to resubmit your subscription , And the original express company code of your company is changed to comNew After the value of , Or add an express company code in your company's database as comNew+ The original waybill ;

3、 If it is judged that status=polling And autoCheck=1, This is the tracking information after correcting the company code , Should be kept .

• About data： Every time we push is complete 、 Full Express query results , Not part of the latest 、 Incremental status . The data source of the query result of the same express order may change , The results vary slightly between different data sources , It is recommended to write new data after deleting old data .
• It is suggested that the time should be ftime Subject to , Do not use time,time Is only available for compatibility .

2.3.2 Callback response message and error code explanation

When we call your callback interface （callbackurl） when , You need to save the data submitted by us to your database first , Then return to us whether the response message and code have been successfully received , That is, the address of your company directly at the callback interface response Fill in the following ：

explain ：

• Please click on the attached document 《 Self test tutorial 》 To test , Only after passing the test can it go online , Otherwise, the push fails . If you do not follow the above operation and the push fails , We will not assume any responsibility ！
• result: "true" It means success ,false It means failure
• returnCode:

   200: Submit successfully

   500: Server error

Please define other errors by yourself

result：true Indicates successful callback ,false It means failure , If the address of the callback interface fails to be submitted ,30 Call back after minutes ,3 Times still failed , Give up automatically .

Other information express 100 Will ignore .

2.3.3 Waybill signing status （ Signed for 、 Return, etc ） Value added service description

  By default , During push, we provide ischeck Field indicates whether the express document is signed in （ Including normal receipt , There are two cases of return and receipt ）, adopt state Field Provide the specific status of sign in ,state As follows ：

The sign in status service can accurately determine the status of most express orders in the market .

if state=0, be condition The following values represent the following states ：

2.4 matters needing attention

1. You Must be strictly in accordance with 2.3.1、2.3.2 Write your callback interface according to the specification of , In especial 2.3.2 Callback response in , And through additional attachment documents 《 Self test tutorial 》 To test , Only after passing the test can we go online , Otherwise, the push fails . If you do not follow the above operation and the push fails , We will not assume any responsibility ！
2. To distribute query pressure , Try not to submit centrally , It is recommended to submit the express bill to the express when it is generated 100, Or submit regularly in batches .
3. The system will query the data of the express company in the morning 8 spot ~ On the evening of 22 Between points , There is not much change in the express list in the early morning , The state changes during this time in the morning 7~8 Point unified synchronization .
4. Because some express companies' information is not updated in time , There will be large time deviation in some orders , Overall control deviation time >4 Hour data is less than 10%.
5. Because the express company has 1% The data will be out of time （ A few months from the current time or 1 Years or even decades ）, There are also some data with wrong order of results , Therefore, there are a few abnormal parts that need manual attention , In the push message abort Need human attention （abort scene ：3 There is no such order in Tiancha ,60 There is no change in the state of the day ）.
6. 3 If no such order is found every day, it will be suspended （abort） explain ： When you submit the courier number , We keep track of 3 No tracking information can be found every day , We think it may be that the package corresponding to the order number has not been sent out by the courier 、 The order number is expired or wrong , And then it will （1） Judge whether the express company code submitted by your company is correct , If correct , Callback interface for your company （callbackurl） Returns information with the following fields ：autoCheck=0、comOld And comNew All is empty ;（2） If the express company code submitted by your company is wrong , We will help to use the correct express company code + The original waybill number resubmits the subscription and starts monitoring （ Subsequently, if the doc No. is monitored to be updated, it will be sent to your callback interface （callbackurl） Push information with the following fields ：autoCheck=1、comOld= The original company code 、comNew= New company code ）; And give your callback interface （callbackurl） Push a message with the following fields ：status=abort、autoCheck=0、comOld It's empty 、comNew= Corrected express company code . therefore , If it is judged that status=abort And comNew It's empty , Then press see 2.3.1 The last one is about status Under the field 【 Important reminder 】 Resubmit your subscription as described in ; If it is found that status=abort And comNew Not empty , You do not need to resubmit your subscription , And the original express company code of your company is changed to comNew After the value of , Or add an express company code in your company's database as comNew+ The original waybill ; If it is judged that status=polling And autoCheck=1, This is the tracking information after correcting the company code , Should be kept
7. 60 The state of the day has not changed and it is suspended （abort） explain ： The express order number submitted to your company for subscription , We will keep track of it after receiving it , If the express starts with tracking information , But continuous from a node 10 After the state of the day does not change , The system automatically calls back to query once a day , Until the first 60 God , At this time, the callback interface will be initiated status=abort、message contain “60 God ” Push of , Tell you that this order is abnormal , After the push is sent , We will stop tracking this order . If you think our judgment is wrong , Available upon receipt of status=abort After that, submit the subscription form to us every half an hour for tracking （ See 1.3.1 Section last “ Important reminder ” Prompt at ）.
8. If your company needs other parameters for callback , Please enter the address of the callback interface （callbackurl Field ） Add by yourself on .
9. If your company is in the process of monitoring the express order （ I.e. Order No status=polling when ） Resubmit and subscribe to this express order No , We will do the weight removal , Immediate report returnCode=501 The fault of .
10. For an update push , If the push fails due to network problems , We will push it again every half an hour , Try pushing 3 Time , If 3 This update push will be abandoned if it fails , Until the next update push .
11. If it cannot be pushed for a long time due to major accidents or other reasons , please 48 Contact us within hours , We can re push historical data for you .
12. For a document number , When you submit your subscription correctly , We are usually in 15 The first monitoring will be carried out in about minutes , If it is monitored that the document number itself has tracking information , That is, the first push , Otherwise, wait for the next monitoring . After that, we usually 4 Monitor every hour , And it will be adjusted according to the status of the order number and other factors ..

2.5 Express company code

notes ： Please strictly use lowercase characters for company code

If the company you need is not in this list , Please contact express 100 Business contact add .

** Please strictly use lowercase characters for company code

See the attachment 《 Courier 100 Express company code .xlsx》, Or log in to the enterprise account and download the latest forms in the background .

3、 ... and 、 Courier 100 Real time express query interface

3.1 Query interface protocol

3.1.1 Query request

The query request is equivalent to a form request, That is, a program is used to simulate http Page form request , for example ：

<form method="post" name="" action=" http://poll.kuaidi100.com/poll/query.do ">

<input type="text" name=" customer " value="xxxxxxxxxxxx" />

<input type="text" name="sign" value="adfjslfjhasdfwofnwofwoeueerf" >

<input type="text" name="param" value="xxx" >

</form>

3.1.2 Query returns

（1） Query results

（2） Error message code

Return the correct contents as above （1） Shown , If you fail , The following information is returned ：

returnCode:

400: Incomplete data submitted , Or your company does not authorize

   500: Indicates that the query failed , Or not POST Submit

   501: Server error , Courier 100 The server is under too much pressure or needs to be upgraded , Temporarily Out of Service

   502: Server busy , For details, see 2.2《 Query interface concurrency protocol 》

   503: Failed to verify signature .

3.1.3 Waybill sign in status service description

State value Means ：

The sign in status service can accurately determine the status of most express orders in the market .

3.2 Query interface concurrency protocol

Due to the limited pressure bearing capacity of the express company system, etc , For the time being, we can only provide 1 single / second Number of query concurrent threads , If your company's query to us exceeds the agreed limit , We will report an over concurrency error , as follows ：

Hyper concurrency prompt code ：

If your company needs to increase the query concurrency because of the large business volume , Please consult with our business contact to adjust .

3.3 Express company code

notes ： Please strictly use lowercase characters for company code

If the company you need is not in this list , Please contact express 100 Business contact add .

** Please strictly use lowercase characters for company code

See the attachment 《 Courier 100 Company code .xlsx》

Four 、 Courier 100 Intelligent judgment interface of the company to which the doc No. belongs

4.1 effect

Submit the waybill number to us through our interface , We return the list of possible express companies corresponding to the waybill number . Your company can be used to judge in advance the express company to which the express order number entered by the user or merchant belongs , To improve the merchant entry experience , Or it can be used to submit and compare the information entered by the merchant , In order to reduce the input errors of merchants .

4.2 Expenses and rights and responsibilities

Because the rules of waybill number are constantly changing and there is no standard for each express company 、 Uniform rules , Our existing mechanism is to intelligently analyze the massive data we have accumulated to obtain relevant rules and update them every day , So we can't guarantee the accuracy of judgment 100%. So , This interface is provided to your company for free , meanwhile , We will not be concerned about the accuracy of this interface 、 Effectiveness, etc. provide legal commitments . Of course , This interface is also used by our official website , So we will try our best to maintain . If your company provides this service to end users , It is recommended that your company add the following prompt when presenting it to users ：

（1） Add a sentence after the judgment “ By express 100 guess ” Such as belt “ guess ” A description of the words ;

（2） The selected company can be manually modified by the user ;

（3） Prompt after judging the result “ This result is for reference only ” And so on .

4.3 Intelligent judgment interface of the company to which the doc No. belongs How to use

4.3.1 Request address and parameters

http://www.kuaidi100.com/autonumber/auto?num=[ Odd Numbers ]&key=[key]

demonstration ：

http://www.kuaidi100.com/autonumber/auto?num=906919164534&key=XDSFDFDSF

4.3.2 Return results

demonstration ：

explain ：

every last ｛｝ Indicates the company outcome of a guess ,comCode Indicates the guessed company code , Refer to attachment for company code 《 Courier 100 Company code 》.