Express 100 – express information query subscription push / tracking API interface case code

Time:2021-8-7

1、 Subscription interface

1.1 subscription request address

<p>https://poll.kuaidi100.com/poll</p>

1.2 subscription request type

post

1.3 subscription input parameters

Request parameters (header)

name type Default value
Content-Type string application/x-www-form-urlencoded

Request parameters (body)

name type Required Example value describe
schema String yes json Returned data format
Θparam param yes Spliced by other fields
company String yes ems The code of the subscribed express company shall be in lowercase letters
└ number String yes 1136281381675 The maximum length of the subscribed express order number is 32 characters<u> Download encoding table < / u >
└ from String no Nanshan District, Shenzhen City, Guangdong Province City of departure, province city district, not required, filled in to help improve the accuracy of judgment of signing status, please provide as much as possible
└ to String no Chaoyang District of Beijing City Destination city, province city district, not required. It is filled in to improve the accuracy of judgment of signing status, and the monitoring frequency will be increased after reaching the destination. Please provide it as much as possible
└ key String yes Authorization code, pleaseApply for Enterprise Editionobtain
Θparameters parameters yes Additional parameter information
└- callbackurl String yes Address of callback interface
└- salt String no XXXXXXXXXX Random string for signature
└- resultv2 String no 1 Adding this field opens the administrative region resolution function
└- autoCom String no 1 Adding this field and setting this value to 1 means that the function of intelligently judging the company of the document number starts. After it is turned on, the company field can be blank, that is, only the shipping document number (number field). After we receive it, we will judge the express company (company field) according to the document number. It is recommended to enable this function only when the express company corresponding to the document number (i.e. the value of company) cannot be known
└- interCom String no 1 Adding this field means opening the international version. After opening, if the subscription doc No. (i.e. the number field) belongs to the international doc No., the tracking information of the country of departure and the country of destination will be returned. This function temporarily only supports the express companies in the postal system (international postal parcels and EMS). If the doc No. is identified as a non international doc, even if this field is added, The destresult element group is also not returned
└- departureCountry String no CN Departure country code
└- departureCom String no ems Code of the express company from
└- destinationCountry String no JP Destination country code
└- destinationCom String no japanposten Code of the express company of the destination
└- phone String no 13488888888 The telephone numbers of the receiver and sender (both mobile phone and fixed phone), and only one can be filled in. SF order number is required, and other express companies can fill in it. If the landline number has an extension number, the extension number does not need to be uploaded.)

1.4 example of subscription request parameters

schema = json
    param = {
        "company": "ems",
        "number": "1136281381675",
        "From": "Nanshan District, Shenzhen City, Guangdong Province",
        "To": "Chaoyang District, Beijing",
        "key": "XXX ",
        "parameters": {
            "Callback URL": "the address of your callback interface, such as http://www. Your domain name. COM / kuaidi? Callbackid =... ",
            "salt": "XXXXXXXXXX",
            "resultv2": "1",
            "autoCom": "1",
            "interCom": "1",
            "departureCountry": "CN",
            "departureCom": "ems",
            "destinationCountry": "JP",
            "destinationCom": "japanposten"
        }
    }

1.5 meaning of subscription return information code

Result: true indicates success and false indicates failure

Information code Information content description Causes and suggested treatment
200 Submitted successfully Subscription submitted successfully
500 Server error The server of express 100 has a gap or temporary exception. Sometimes, if the request is not submitted according to the specification, such as the wrong parameter of the express company, this error will also be reported
501 Duplicate subscription This order has been subscribed successfully and is still in the process of tracking. To submit multiple subscriptions, please submit the subscription every half an hour after receiving the status = abort or shutdown of the order number
502 The submitted content contains sensitive keywords and is blocked by security protection The callback address and submitted content contain sensitive words. Please contact the express 100 staff
600 You are not a legal subscriber (i.e. authorization key error) There is no single quantity available for the account, so it needs to be recharged
601 Poll: the key has expired There is no single quantity available for the account, so it needs to be recharged
700 Unsupported express company For express companies that refuse to subscribe, check whether the express company code is wrong
701 The subscriber’s subscription data has errors (e.g. unsupported express companies, blank doc No., super long doc No., etc.) or wrong callback address Please check the express company code, check the parameters against the technical documents, and test the callback address in the background debugging tool
702 Poll: the express company corresponding to this doc No. is not recognized The code of the express company is wrong or there is no available order quantity, which needs to be recharged

1.6 subscription return example (JSON format)

{
    "result": true,
    "returnCode": "200",
    "Message": "submitted successfully"
}

2、 Push interface

2.1 push request address

Provided by your company through the callback URL field in the subscription request

2.2 push request type

post

2.3 push input parameters

Request parameters (header)

name type Default value
Content-Type string application/x-www-form-urlencoded

Request parameters (body)

name type Example value describe
sign String When the salt value of the subscription parameter is not empty, the push data will contain the encrypted signature. Encryption method: MD5 (param + salt)
Θparam Spliced by other fields
└ status String polling Monitoring status: Polling: monitoring, shutdown: end, abort: abort, updateall: push again. Among them, when the express order is signed in, status = shutdown, and when the message is “no record in 3 days” or “no change in 60 days” status = abort, additional processing logic needs to be added for the status of status = abort
└ billstatus String got It includes got, sending and check. It has been discarded because it is of little significance. Please ignore it
└ message String Monitoring status related messages, such as no record in 3 days and no change in 60 days
└ autoCheck String 1 Whether the express company code is wrong. 0 is the original express company code submitted by your company, and 1 is the new express company code corrected by us. If we can’t find the results for 3 consecutive days, we will (1) judge whether the express company code submitted by your company is correct. If it is correct, push the information with the following fields to your callback interface (callback URL): autocheck = 0, comold and comnew are empty( 2) If the express company code submitted by your company is wrong, we will help re submit the subscription with the correct express company code + the original waybill number and turn on the monitoring (subsequently, if the number is monitored to be updated, push the information with the following fields to your callback interface (callback URL): autocheck = 1, comold = the original company code, comnew = the new company code); And push a message containing the following fields to your callback interface (callback URL): status = abort, autocheck = 0, comold is empty, comnew = corrected express company code.
└ comOld String yuantong The original express company code submitted by your company. See the description after autocheck for details. If the international version is enabled (that is, add the field intercom = 1 in the subscription request), this field is not available in the callback request
└ comNew String ems The new express company code corrected by our company. See the description after autocheck for details. If the international version is enabled (that is, add the field intercom = 1 in the subscription request), this field is not available in the callback request
ΘlastResult lastResult For the latest query result, if the international version is opened through the intercom field in the subscription message, this lastresult represents the query result of the country of departure, in full quantity and reverse order (i.e. the latest time is at the top)
└- message String Message body, please ignore
└- state String 0 The current status of express order includes 13 statuses: 0 in transit, 1 receiving, 2 difficult, 3 signing in, 4 returning, 5 sending, 6 returning, 7 document transfer, 10 pending customs clearance, 11 clearing, 12 cleared, 13 abnormal customs clearance, 14 recipient refusing to sign, etc
└- status String 200 Communication status, please ignore
└- condition String F00 Express order details status flag, not implemented yet, please ignore
└- ischeck String 0 Sign in flag
└- com String yuantong Express company code, all in lowercase letters
└- nu String V030344422 Odd Numbers
└- data Object Array, which contains multiple objects, and the field of each object is shown in the expansion
└– context String Shanghai Distribution Center / loading in vehicle scanning content
└– time String 2012-08-28 16:33:19 Time, original format
└– ftime String 2012-08-28 16:33:19 Time after formatting
└– status String On the way The sign in status corresponding to this data element. It will not appear until the resultv2 = 1 field is submitted in the subscription interface
└– areaCode String 310000000000 The code of the administrative region corresponding to this data element will not appear until the resultv2 = 1 field is submitted in the subscription interface
└– areaName String Shanghai The name of the administrative region corresponding to this data element will not appear until the resultv2 = 1 field is submitted in the subscription interface
Θ destResult destResult Indicates the latest query result of the destination country. This data element will be displayed only when the international version is opened through the intercom = 1 field in the subscription message, in full and reverse order (i.e. the latest time is at the top)
└- message String Message body, please ignore
└- state String 0 The current status of the express order includes 8 statuses: 0 in transit, 1 receiving, 2 difficult, 3 signing in, 4 returning, 5 sending, 6 returning, etc
└- status String 200 Communication status, please ignore
└- condition String F00 Express order details status flag, not implemented yet, please ignore
└- ischeck String 0 Sign in flag
└- com String yuantong Express company code, all in lowercase letters
└- nu String V030344422 Odd Numbers
Θ data data Array, which contains multiple objects, and the field of each object is shown in the expansion
└– context String Shanghai Distribution Center / loading in vehicle scanning content
└– time String 2012-08-28 16:33:19 Time, original format
└– ftime String 2012-08-28 16:33:19 Time after formatting
└– status String On the way The sign in status corresponding to this data element will not appear until the resultv2 = 1 field is submitted in the subscription interface
└– areaCode String 310000000000 The code of the administrative region corresponding to this data element will not appear until the resultv2 = 1 field is submitted in the subscription interface
└– areaName String Shanghai The name of the administrative region corresponding to this data element will not appear until the resultv2 = 1 field is submitted in the subscription interface

2.4 example of push input parameters

param = {
    "status": "polling",
    "billstatus": "got",
    "message": "",
    "autoCheck": "1",
    "comOld": "yuantong",
    "comNew": "ems",
    "lastResult": {
        "message": "ok",
        "state": "0",
        "status": "200",
        "condition": "F00",
        "ischeck": "0",
        "com": "yuantong",
        "nu": "V030344422",
        "data": [
        {
"Context": "Shanghai Distribution Center / loading in vehicle scanning",
                "time": "2012-08-28 16:33:19",
                "ftime": "2012-08-28 16:33:19",
"Status": "in transit",
                "areaCode": "310000000000",
"Areaname": "Shanghai"
            },
            {
"Context": "Shanghai Distribution Center / exit scanning",
                "time": "2012-08-27 23:22:42",
                "ftime": "2012-08-27 23:22:42",
"Status": "in transit",
                "areaCode": "310000000000",
"Areaname": "Shanghai"
            }
        ]
    },
    "destResult": {
        "message": "ok",
        "state": "0",
        "status": "200",
        "condition": "F00",
        "ischeck": "0"     ,
        "com": "speedpost",
        "nu": "EX015142583SG",
        "data": [
        {
                "context": "[01000]Final delivery Delivered to: SLOVESNOV",
                "time": "2016-05-24 14:00:00",
                "ftime": "2016-05-24 14:00:00",
"Status": "sign in",
                "areaCode": null,
                "areaName": null
            }
        ]
    }
}

2.5 service description of Waybill signing status

Status value name meaning
0 On the way Express is in transit
1 Collect The express has been collected by the express company
2 difficult The state that the express 100 cannot resolve or requires manual intervention, such as the recipient’s telephone error.
3 Sign for Normal sign in
4 Withdrawal Return the goods to the consignor and sign for receipt
5 Dispatch The goods are being dispatched
6 return The goods are on their way back to the shipper
7 Switch The goods are forwarded to other express companies for mailing
10 Pending customs clearance Goods waiting for customs clearance
11 Customs clearance in progress The goods are in the process of customs clearance
12 Cleared The goods have completed the customs clearance process
13 Customs clearance exception The goods are abnormal during customs clearance
14 deny sb. a visa Explicitly rejected by the addressee

2.6 push response message and error code interpretation

Field name Field meaning
result True indicates success and false indicates failure. If the address of the callback interface fails to be submitted, call back again after 30 minutes. If it still fails for 3 times, it will be automatically abandoned
returnCode 200: submitted successfully 500: server error other errors please define yourself
message Prompt returned

2.7 push return example

When we call your callback URL, you need to save the data submitted by us to your database first, and then return the response message and code whether it has been successfully received to us, that is, your company directly fills in the following contents in the response of the address of the callback interface:

{
    "result":true,
    "returnCode":"200",
    "Message": "success"
}

Note: for the express order with status = abort (the message contains “no record in 3 days” or “no change in 60 days”), it is also necessary to return the successfully received response message and code.

3、 Express company code

<u> Download form < / u >

4、 Demo download

<u> Java sample code < / u >    <u> PHP sample code < / u >    <u> Python sample code < / u >    <u> . net sample code < / u >

1、 Express information push API product introduction

The express 100 information push service provides the functions of Waybill query and tracking, which is used by enterprises to track the sent goods.

The information push service is that the enterprise submits the express bill number, and the express 100 will track these waybills after receiving them. When the status of the waybill changes, the express 100 will push the tracking information of the waybill to your company by calling the callback interface until the end of the life cycle of these waybill numbers (generally subject to “signed in”). For a doc No., after you correctly submit the subscription, we will generally conduct the first monitoring after about 15 minutes. If we monitor that the doc No. itself has tracking information, we will push it for the first time, otherwise we will wait for the next monitoring. After that, we generally monitor every 4 hours and make adjustments according to the status of the order number and other factors.

2、 Application scenario of express information push API

  1. After customers log in to your website, app and applet, they can see the logistics status of the order directly on the “my order” page.
  2. It can develop automatic and batch check function, automatically screen out the number of “signed in” and “difficult parts” to reduce the pressure of documentary personnel.
  3. Change the status and transaction process of the order. For example, as long as the waybill number changes to “signed in”, the order can be changed to confirm return and replacement.
  4. Write off the salesperson. The salesperson’s performance can be calculated according to the number of “signed in” waybills.
  5. Evaluation and selection of express companies can obtain the actual in transit time of express, evaluate the timeliness of express companies and optimize express selection;
  6. Assist in freight settlement, find out the “signed in” documents and signing time, and you can easily deal with the settlement and reconciliation of cash on delivery.

3、 System structure and process

<img src=”https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/129503f13de14bf68893fc7527827a89~tplv-k3u1fbpfcp-zoom-1.image” alt=”img” style=”zoom: 67%;” />

4、 Express information push API expense settlement

1. Charging method

The express information push interface is a query interface. After registering the express 100 account, the enterprise can view the query interface package in the enterprise management backgroundView query class interface packageAnd buy.

2. Charge price

Query interface pre recharge charging package: it can be opened and used without contract process.

Price / yuan Single quantity Gift / order Unit price / yuan
2000 20000 5000 0.08
1000 10000 2000 About 0.083
500 5000 500 About 0.09

The query interface charges by order. The same waybill can only be queried once in a natural month.

Official source documents:

https://api.kuaidi100.com/document/5f0ffa7f2977d50a94e1023b.html

https://api.kuaidi100.com/document/5eb9f79186b0df4188313a0d.html

https://api.kuaidi100.com/document/5f0ffa8f2977d50a94e1023c.html