Tracking Subscription Query API Interface Technical Documentation
1. Subscription Interface
By submitting tracking numbers through the subscription interface, the system will monitor these shipments. When the status of the shipment changes, the system will push the tracking information to your company via the callback interface until the lifecycle of these tracking numbers ends (generally considered as "delivered").
Note: For the same courier company and tracking number, the maximum subscription is 4 times per month. Submitting more than 4 subscriptions will result in a duplicate subscription error.
1.1 Subscription Request URL
https://poll.kuaidi100.com/poll
1.2 Subscription Request Method
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 | Description |
| schema | String | No | json | Format of the returned data, json (default) or xml |
| param | param | Yes | Composed of other fields | |
| └ company | String | Yes | ems | Code of the subscribed courier company, use lowercase letters, download the code table |
| └ number | String | Yes | 1136281381675 | Tracking number, minimum length 6 characters, maximum length 32 characters |
| └ from | String | No | Guangdong Province, Shenzhen | Origin city, province-city-district, optional but recommended for accurate delivery status judgment |
| └ to | String | No | Beijing, Chaoyang District | Destination city, province-city-district, optional but recommended for increasing monitoring frequency |
| └ key | String | Yes | Authorization code, please apply for enterprise version to obtain | |
| parameters | parameters | Yes | Additional parameter information | |
| └ callbackurl | String | Yes | Callback URL, supports http by default, contact Kuaidi100 technicians for https compatibility | |
| └ salt | String | No | XXXXXXXXXX | Random string for signature |
| └ resultv2 | String | No | 1 | Adds this field to enable administrative region parsing. Empty: disable (default), 1: enable |
| └ autoCom | String | No | 1 | Adds this field and sets it to 1 to enable intelligent company detection |
| └ interCom | String | No | 1 | Adds this field to enable international version |
| └ departureCountry | String | No | CN | Departure country code |
| └ departureCom | String | No | ems | Departure courier company code |
| └ destinationCountry | String | No | JP | Destination country code |
| └ destinationCom | String | No | japanposten | Destination courier company code |
| └ phone | String | No | 13488888888 | Recipient's or sender's phone number (mobile or landline, only one can be provided. Mandatory for SF Express and SF Freight, optional for other courier companies. If it is a landline with an extension, the extension number does not need to be uploaded. If it is an e-commerce virtual number, provide the last four digits after the "-". See details.) |
1.4 Subscription Request Example
schema = json
param = {
"company": "yuantong",
"number": "YT6186594166532",
"key": "XXX ",
"parameters": {
"callbackurl": "您的回调接口的地址，如http://www.您的域名.com/kuaidi?callbackid=...",
"salt": "XXXXXXXXXX",
"phone": "13868688888",
"resultv2": "4"
}
}
1.5 Subscription Response Codes
result: true indicates success, false indicates failure
| Code | Description | Explanation |
| 200 | Submission successful | Subscription submitted successfully |
| 500 | Server error | Temporary issue with Kuaidi100 server or non-compliant request |
| 501 | Duplicate subscription | The tracking number is already subscribed to and currently being monitored. Retry after status changes |
| 502 | Sensitive content in submission intercepted | Callback URL or content contains sensitive words, contact Kuaidi100 support |
| 600 | Unauthorized subscriber (invalid key) | Account has no available subscriptions, needs recharge |
| 601 | POLL: KEY expired | Account has no available subscriptions, needs recharge |
| 700 | Unsupported courier company | Check the courier company code for errors |
| 701 | Error in subscription data or callback URL | Check courier company code, parameters, and test callback URL |
| 702 | POLL: Courier company for the number not identified | Courier company code error or no available subscriptions, needs recharge |
1.6 Subscription Response Example (JSON Format)
{
"result": true,
"returnCode": "200",
"message": "提交成功"
}
2. Push Notifications Interface
2.1 Push Notifications Request URL
Provided by your company via the ‘callbackurl’ field in the subscription request
2.2 Push Notifications Request Method
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 | Description |
| sign | String | Subscription parameter. When the salt value is not null, the push data will include this encrypted signature, encrypted by: md5(param+salt). Note that the encrypted string must be converted to 32-bit uppercase. Note: When the salt value is an empty string, the pushed data will still include the sign. | |
| Θparam | Concatenation of other fields | ||
| └ status | String | polling | Monitoring status: polling: monitoring, shutdown: ended, abort: aborted, updateall: re-push. When the parcel is signed for, status=shutdown. When the message is "3 days no record" or "60 days no change", status=abort. For status=abort, additional processing logic is required. |
| └ billstatus | String | got | Includes got, sending, check three statuses. Due to their insignificance, they are deprecated and can be ignored. |
| └ message | String | Monitoring status related message, such as: 3 days no record, 60 days no change. | |
| └ autoCheck | String | 1 | Whether the courier company code is incorrect, 0 means the pushed information corresponds to the original courier company code submitted by your company, 1 means the pushed information corresponds to the new corrected courier company code from our side. If we cannot find the result for three consecutive days, we will (1) check the correctness of the courier company code submitted by your company. If correct, we will push the information with fields: autoCheck=0, comOld and comNew are empty to your callback interface (callbackurl); (2) If the courier company code submitted by your company is incorrect, we will use the correct courier company code and the original tracking number to resubmit the subscription and start monitoring (if there are updates on the tracking number later, we will push the information with fields: autoCheck=1, comOld=original company code, comNew=new company code to your callback interface). We will also push a message to your callback interface containing the fields: status=abort, autoCheck=0, comOld=empty, comNew=corrected courier company code. |
| └ comOld | String | yuantong | The original courier company code submitted by your company. For more details, see the autoCheck description above. If the international version is enabled (i.e., the interCom=1 field is added in the subscription request), this field will not be included in the callback request. |
| └ comNew | String | ems | The new corrected courier company code from our side. For more details, see the autoCheck description above. If the international version is enabled (i.e., the interCom=1 field is added in the subscription request), this field will not be included in the callback request. |
| ΘlastResult | lastResult | The latest query result. If the international version is enabled via the interCom field in the subscription message, this lastResult represents the query result of the country of departure, in full, in reverse order (i.e., the latest time is first). | |
| └- message | String | Message body, can be ignored. | |
| └- state | String | 0 | Current status of the parcel, default is 0 in transit, 1 collected, 2 difficult, 3 signed, 4 return signed, 5 dispatched, 8 customs clearance, 14 refused, etc. There are 10 basic logistics statuses. For advanced logistics status, refer to the resultv2 field. |
| └- status | String | 200 | Communication status, can be ignored. |
| └- condition | String | F00 | Detailed status tag of the parcel, not yet implemented, can be ignored. |
| └- ischeck | String | 0 | Signed mark, 0 not signed, 1 signed. |
| └- com | String | yuantong | Courier company code, all in lowercase letters. |
| └- nu | String | V030344422 | Tracking number. |
| └- data | Object | Array containing multiple objects, each object field is as shown below. | |
| └-- context | String | Shanghai Sorting Center/Package Scanned into Car | Content. |
| └-- time | String | 2012-08-28 16:33:19 | Time, original format. |
| └-- ftime | String | 2012-08-28 16:33:19 | Formatted time. |
| └-- status | String | In transit | Logistics status name or advanced status name, only appears if resultv2=1 or resultv2=4 is marked. |
| └-- statusCode | String | 1002 | Corresponding advanced logistics status value, only appears if resultv2=4 is marked. |
| └-- areaCode | String | 310000000000 | Corresponding administrative area code, only appears if resultv2=1 or resultv2=4 is marked. |
| └-- areaName | String | Shanghai | Corresponding administrative area name, only appears if resultv2=1 or resultv2=4 is marked. |
| └-- areaCenter | String | 17.200983,39.084158 | Corresponding administrative area coordinates, only appears if resultv2=4 is marked. |
| └-- location | String | Shenzhen Center | Current location of the package, only appears if resultv2=4 is marked. |
| └-- areaPinYin | String | tianjin | Corresponding administrative area pinyin, only appears if resultv2=4 is marked. |
2.4 Example of Push Input Parameters
sign = ******
param = {
"status": "polling",
"billstatus": "got",
"message": "寄件",
"lastResult": {
"message": "ok",
"nu": "YT6186594166532",
"ischeck": "0",
"com": "yuantong",
"status": "200",
"data": [{
"time": "2021-12-15 20:15:14",
"context": "【苏州转运中心】 已发出 下一站 【无锡转运中心公司】",
"ftime": "2021-12-15 20:15:14",
"areaCode": "CN320500000000",
"areaName": "江苏,苏州市",
"status": "干线",
"location": "",
"areaCenter": "120.585315,31.298886",
"areaPinYin": "su zhou shi",
"statusCode": "1002"
},
{
"time": "2021-12-15 20:11:25",
"context": "【苏州转运中心公司】 已收入",
"ftime": "2021-12-15 20:11:25",
"areaCode": "CN320500000000",
"areaName": "江苏,苏州市",
"status": "干线",
"location": "",
"areaCenter": "120.585315,31.298886",
"areaPinYin": "su zhou shi",
"statusCode": "1002"
},
{
"time": "2021-12-15 19:18:27",
"context": "【江苏省无锡市锡新开发区公司】 已收入",
"ftime": "2021-12-15 19:18:27",
"areaCode": "CN320200000000",
"areaName": "江苏,无锡市",
"status": "在途",
"location": "",
"areaCenter": "120.31191,31.491169",
"areaPinYin": "wu xi shi",
"statusCode": "0"
},
{
"time": "2021-12-15 17:10:09",
"context": "【江苏省苏州市北桥公司】 已揽收",
"ftime": "2021-12-15 17:10:09",
"areaCode": "CN320507004000",
"areaName": "江苏,苏州市,相城区,北桥",
"status": "揽收",
"location": "",
"areaCenter": "120.606531,31.505825",
"areaPinYin": "bei qiao jie dao",
"statusCode": "1"
}
],
"state": "0",
"condition": "F00",
"routeInfo": {
"from": {
"number": "CN320507004000",
"name": "江苏,苏州市,相城区,北桥"
},
"cur": {
"number": "CN320200000000",
"name": "江苏,无锡市"
},
"to": null
},
"isLoop": false
}
}
2.5 Explanation of Shipment Delivery Status (state)
| Logistics Status Value | Logistics Status Name | Advanced Logistics Status Value | Advanced Logistics Status Name | Meaning |
| 1 | Collected | 1 | Collected | Parcel collected |
| 101 | Ordered | Order placed for the parcel | ||
| 102 | Awaiting Collection | Awaiting courier collection | ||
| 103 | Collected | Courier has collected the parcel | ||
| 0 | In Transit | 0 | In Transit | Parcel is in transit |
| 1001 | Arrived at Dispatch City | Parcel has arrived in the recipient's city | ||
| 1002 | Trunk Line | Parcel is in the process of transportation | ||
| 1003 | Redirected | Parcel has been forwarded to a new delivery address | ||
| 5 | Dispatching | 5 | Dispatching | Parcel is being dispatched |
| 501 | Delivered to Locker or parcel station | Parcel has been delivered to a locker or parcel station | ||
| 3 | Delivered | 3 | Delivered | Parcel has been delivered |
| 301 | Signed by Recipient | Recipient has signed for the parcel | ||
| 302 | Delivered after Dispatch Exception | Parcel showed dispatch exception but was subsequently delivered | ||
| 303 | Signed by Proxy | Parcel has been signed for by a proxy | ||
| 304 | Signed from Locker or Station | Parcel has been picked up from locker or station | ||
| 6 | Returning | 6 | Returning | Parcel is being returned to the sender |
| 4 | Returned | 4 | Returned | This parcel has been returned |
| 401 | Cancelled | This parcel has been cancelled | ||
| 14 | Refused | Recipient refused to accept the parcel | ||
| 7 | Redirected | 7 | Redirected | Parcel transferred to another courier company |
| 2 | Problem | 2 | Problem | Parcel has encountered a problem |
| 201 | Timeout Undelivered | Parcel not delivered after a long dispatch time | ||
| 202 | Timeout No Update | Parcel not dispatched or delivered for a long time | ||
| 203 | Refused by Recipient | Recipient initiated refusal, awaiting sender's confirmation | ||
| 204 | Dispatch Exception | Exception encountered during dispatch | ||
| 205 | Timeout in Locker or Station | Parcel not picked up from locker or station for a long time | ||
| 206 | Unable to Contact | Unable to contact the recipient | ||
| 207 | Out of Service Area | Out of the courier company's service area | ||
| 208 | Stagnant | Parcel stagnant at a node, not dispatched | ||
| 209 | Damaged | Parcel is damaged | ||
| 210 | Cancelled by Sender | Sender applied to cancel the parcel | ||
| 8 | Customs Clearance | 8 | Customs Clearance | Parcel is clearing customs |
| 10 | Awaiting Customs Clearance | Parcel waiting for customs clearance | ||
| 11 | In Customs Clearance | Parcel is in the customs clearance process | ||
| 12 | Customs Cleared | Parcel has completed customs clearance | ||
| 13 | Customs Clearance Exception | Exception occurred during customs clearance | ||
| 14 | Refused | \ | \ | Recipient refused the parcel |
Note: If you need advanced logistics status names and status values, the resultv2 parameter must be set to "4" to return.
2.6 Push Response Message and Error Code Explanation
| Field Name | Field Meaning |
| result | True indicates success, false indicates failure. If submitting the callback interface address fails, it will retry after 30 minutes. If it fails three times, it will automatically give up. |
| returnCode | 200: Submission successful; 500: Server error; Other errors please define yourself |
| message | Return prompt message |
2.7 Example of Push Response
When we call your callback interface (callbackurl), you need to first save the data we submitted to your database, and then return a response message and code indicating whether the reception was successful. Your company should fill in the response at the callback interface address as follows:
{
"result":true,
"returnCode":"200",
"message":"成功"
}
Note: For status=abort (where the message contains "no records for 3 days" or "no changes for 60 days"), you also need to return a response message and code indicating successful reception.
3.Courier Company Codes
If the company you need is not on this list, please contact online customer service to add it.
4. Demo Downloads
JAVA Example Code | PHP Example Code | PYTHON Example | PYTHON Example |
5. Real-Time Monitoring of Push Status
Appendix1:
Appendix2: See details:
When querying SF Express logistics information, the error "message": "Courier company parameter error: verification code error" may occur due to the following reasons and suggested handling methods:
1. The Kuaidi100 query interface requires the sender's or recipient's phone number reserved when placing the order with the courier company. For SF Express, this field is mandatory, while for other couriers, it is optional.
2. If the phone number is a landline with an extension, do not include the extension number. If the number is a virtual e-commerce number, include the last four digits after the "-".
3. If the correct phone number is not provided or an incorrect number is submitted, any returned logistics tracking information might be cached data verified by other users. This data is not guaranteed by the query service. The interface requires the phone number to be correctly provided.
4. The correctness of the phone number can be verified through the WeChat Mini Program "SF Express+" on the "Track Express" page.
Example:
- For the number 0755-81234567, any of 075581234567, 81234567, or 4567 can be submitted.
- For the number 13801380000, either 13801380000 or 8000 can be submitted.
- For the number 13801380000-1234, either 13801380001234 or 1234 can be submitted.
SF Express+ Query Example:
