在电商业务中,物流查询体验直接影响用户满意度。本文将详细介绍如何快速集成快递100物流查询API,包括其新升级的智能时效预估能力,帮助开发者打造更专业的电商应用。
一、为什么选择快递100 API?
快递100 作为国内领先的物流数据服务商,其API接口是电商应用的理想选择,主要优势包括:
● 全面覆盖:支持国内外3000+快递公司,包括顺丰、中通、圆通、申通等主流快递商
● 高稳定性:日均查询量突破4亿,吞吐量近100万/秒,轻松应对电商大促高峰
● 功能丰富:提供实时查询、订阅推送、电子面单、智能时效预估等全链路服务
● 开发者友好:接口高度标准化,提供多语言SDK,最快15分钟内即可完成对接
二、准备工作:获取API密钥
1. 注册企业账号
访问快递100API开放平台官方网站注册企业账号。
2. 获取API密钥
在管理后台,查看自己的授权Key 和 Secret,这是调用API的核心凭证,请妥善保存。
3. 了解计费方式
查询类接口的计费规则很友好:40天内同一运单号多次查询不重复扣费,非常适合电商高频查询场景。
三、集成实时查询API
实时查询是电商应用中最常用的功能,让用户能主动查看包裹当前位置。
1. 接口基本信息
● 请求地址:https://poll.kuaidi100.com/poll/query.do
● 请求方式:HTTP POST/GET
● 返回格式:JSON
2. 核心参数说明
| 参数名 | 是否必填 | 说明 |
|---|---|---|
| customer | 是 | 授权码 |
| sign | 是 | 数字签名 |
| param | 是 | JSON字符串,包含查询参数 |
3. 签名生成算法
签名是API调用的安全保障,生成方式如下:
// 签名计算公式
sign = MD5(param + key + customer)
// 加密后字符串转32位大写4. 完整请求示例
// 构建请求参数
String key = "您的key";
String customer = "您的授权码";
String param = "{"com":"yuantong","num":"YT255699866665411","phone":"..."}";
String sign = MD5Util.md5(param + key + customer).toUpperCase();
// 构建请求
Map<String, String> params = new HashMap<>();
params.put("customer", customer);
params.put("sign", sign);
params.put("param", param);
// 发送请求
String result = HttpClientUtil.post("https://poll.kuaidi100.com/poll/query.do", params);5. 响应结果处理
成功响应示例:
{
"message": "ok",
"nu": "YT25569986666541",
"ischeck": "0",
"com": "yuantong",
"status": "200",
"data": [
{
"time": "2025-06-13 15:56:19",
"context": "您的快件离开【安徽省六安市叶集实验区】,已发往【安徽省六安市】",
"ftime": "2025-06-13 15:56:19",
"areaCode": "CN341522000000",
"areaName": "安徽,六安市,霍邱县",
"status": "在途",
"location": "六安市,霍邱县",
"areaCenter": "116.277912,32.353038",
"areaPinYin": "huo qiu xian",
"statusCode": "0"
},
{
"time": "2025-06-13 15:53:52",
"context": "您的快件在【安徽省六安市叶集实验区】已揽收",
"ftime": "2025-06-13 15:53:52",
"areaCode": "CN341522000000",
"areaName": "安徽,六安市,霍邱县",
"status": "揽收",
"location": "六安市,霍邱县",
"areaCenter": "116.277912,32.353038",
"areaPinYin": "huo qiu xian",
"statusCode": "1"
}
],
"state": "0",
"condition": "00",
"routeInfo": {
"from": {
"number": "CN430112000000",
"name": "湖南,长沙市,望城区"
},
"cur": {
"number": "CN341522000000",
"name": "安徽,六安市,霍邱县"
},
"to": {
"number": "CN320583104000",
"name": "江苏,苏州市,昆山市,花桥镇"
}
},
"isLoop": false,
"arrivalTime": "2025-06-14 13",
"totalTime": "0天21小时",
"remainTime": "0天20小时",
"predictedRoute": [
{
"arriveTime": "2025-06-13 15:53:52",
"leaveTime": "2025-06-13 15:56:19",
"province": "安徽",
"city": "六安市",
"district": "叶集区",
"name": "安徽省六安市叶集实验区",
"state": "已经过节点",
"type": "网点"
},
{
"arriveTime": "2025-06-13 19:05:19",
"leaveTime": "2025-06-13 19:59:19",
"province": "安徽",
"city": "六安市",
"district": "金安区",
"name": "安徽省六安市",
"state": "预估途径节点",
"type": "网点"
},
{
"arriveTime": "2025-06-13 23:09:19",
"leaveTime": "2025-06-13 23:16:19",
"province": "安徽",
"city": "合肥市",
"district": "肥东县",
"name": "合肥转运中心",
"state": "预估途径节点",
"type": "转运中心"
},
{
"arriveTime": "2025-06-14 06:58:19",
"leaveTime": "2025-06-14 07:17:19",
"province": "江苏",
"city": "无锡市",
"district": "新吴区",
"name": "苏州转运中心",
"state": "预估途径节点",
"type": "转运中心"
},
{
"arriveTime": "2025-06-14 12:29:19",
"leaveTime": "2025-06-14 13:46:19",
"province": "江苏",
"city": "苏州市",
"district": "昆山市",
"name": "江苏省昆山市城区",
"state": "预估途径节点",
"type": "网点"
}
]
}重要提示:请控制每一单查询频率至少在半小时以上,否则会造成锁单。
四、重磅功能:智能时效预估免费升级
现在使用快递100物流查询接口,可免费升级为额外返回智能时效预估的能力,这是目前行业最前沿的物流预测功能。
1. 什么是智能时效预估?
智能时效预估是快递100基于AI+Data构建的中国首个快递物流网络数智图谱推出的核心能力。用户在调用物流查询API时,除了获取物流轨迹,还可获得:
● 预计送达时间
● 预测准确率
● 途经网点与转运中心路线预测
2. 核心价值:从"查轨迹"到"预见未来"
● 透视数据可信度:probability 字段直接告知该次预估的准确率概率高达90%
● 体验更透明:终端用户获得的不止有物流轨迹信息,还能获得快递预计到达时间
● 接入零门槛:无需额外调整调用逻辑,完美兼容历史接入方案
3. 两种预估模式覆盖全场景
● 全程时效预估(发货前):在商品详情页直接展示预计送达时间,催化消费者决策
● 在途时效预估(发货后):当包裹已发出,系统会实时更新预计送达时间,离收货地越近,预测越准
4. 如何启用智能时效预估?
调用快递100物流查询接口时,在请求参数的 resultv2 字段选择8,即可额外获得智能时效预估数据。
五、小程序集成实战
1. 小程序端实现
在小程序页面中展示物流信息和时效预估:
<!-- logistics.wxml -->
<view class="logistics-container">
<view class="logistics-header">
<text class="company">快递公司:{{companyName}}</text>
<text class="number">运单号:{{expressNumber}}</text>
</view>
<!-- 时效预估信息 -->
<view class="time-estimate" wx:if="{{estimatedTime}}">
<text class="estimate-text">预计送达:{{estimatedTime}}</text>
<text class="probability" wx:if="{{probability}}">准确率:{{probability}}%</text>
</view>
<view class="progress-bar">
<view class="progress-item {{item.status}}" wx:for="{{logisticsList}}" wx:key="time">
<view class="dot"></view>
<view class="content">
<text class="context">{{item.context}}</text>
<text class="time">{{item.ftime}}</text>
</view>
</view>
</view>
</view>2. 服务端API封装
建议在小程序服务端封装快递100接口,避免前端直接暴露API密钥:
// Node.js后端接口示例
const express = require('express');
const router = express.Router();
const md5 = require('md5');
router.post('/logistics/query', async (req, res) => {
try {
const { com, num } = req.body;
const key = process.env.KUAIDI100_KEY;
const customer = process.env.KUAIDI100_CUSTOMER;
const param = JSON.stringify({
com,
num,
resultv2: 8 // 启用智能时效预估
});
// 生成签名
const sign = md5(param + key + customer).toUpperCase();
// 调用快递100接口
const response = await fetch('https://poll.kuaidi100.com/poll/query.do', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
customer,
sign,
param
})
});
const result = await response.json();
// 返回包含智能时效预估的结果
res.json({
logisticsList: result.data,
estimatedTime: result.estimatedTime, // 预计送达时间
probability: result.probability // 预测准确率
});
} catch (error) {
res.status(500).json({ error: '查询失败' });
}
});六、物流跟踪:订阅推送API
对于需要持续追踪快递的场景,订阅推送比实时查询更高效。
1. 工作流程
● 开发者调用订阅接口,设置回调地址
● 当物流状态更新时,快递100会主动向该地址推送最新信息
● 一般会在15分钟左右进行第一次监控
2. 优势
● 及时性:状态变化立即推送,无需等待用户查询
● 节省资源:减少不必要的API调用
● 自动化:可基于推送消息自动更新订单状态
七、常见问题与解决方案
1. 签名验证失败
问题:返回503错误,签名认证失败
解决:检查签名生成算法,确保按 param + key + customer 顺序MD5加密,并转为32位大写
2. 单号不存在
问题:返回500错误,查询无结果
解决:
● 确认单号和快递公司正确
● 刚下单的包裹可能还未录入系统,建议延迟查询
● 检查单号是否存在空格等特殊字符
3. 智能时效预估数据不显示
问题:未返回预估时间和准确率
解决:
● 检查请求参数是否设置 resultv2: 8
九、总结
通过快递100 API,开发者可以快速为电商小程序和App集成专业级物流查询功能,特别是新升级的智能时效预估能力,让您的应用从"查询轨迹"升级到"预见未来"。
现在就开始集成,为您的电商应用赋予更智能的物流查询能力吧!
希望本文对您有所帮助,欢迎在评论区交流讨论!
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。