之前笔者介绍了快递查询API接口，主要是需要输入快递单号主动查询，无论物流状态有无变化，都需要主动查询，有可能多次查询的结果是没有变化的。这种方式有一定的不足：
- 实时性不高，需要每次查询方能知道最新状态。
- 通常按次计费，无论物流状态有无变化，只要发起查询就计费，增加了查询成本。
有没有实时性更高的，当物流状态发生变化时，主动通知我的API接口呢？答案是有的，即“快递订阅推送API接口”。与主动查询相比，它有以下优点：
- 提交一次单号，无需频繁手动查询快递状态，提高了获取物流信息的效率和便捷性。
- 减少查询成本（按单计费），提升系统效率不再需要反复请求接口获取最新状态。
与快递查询接口类似，快递订阅推送API，同样支持1500+快递公司，与官网同步数据更新。
下面来介绍快递订阅推送API接口的使用
快递订阅主要分两步：
- 先调用订阅接口，提交单号，发起订阅
- 订阅成功后，当物流状态发生变动时，由接口提供者将当前物流状态推送给使用者
详细参阅这里
订阅说明
请求参数
| 名称 | 类型 | 必须 | 说明 |
|---|---|---|---|
| expressCode | String | 否 | 快递公司编号 |
| number | String | 是 | 运单编号 |
| mobile | String | 否 | 顺丰速运、中通、跨越速运需要传入收/寄件人手机号或后四位手机号 |
| callBackUrl | String | 是 | 物流轨迹推送地址，以https/http协议开头，长度不能大于200 |
推送说明
当物流状态发生变动时，接口提供者将当前物流状态数据推送至接入者提供地址为callBackUrl的接口
数据结构
{
"expressCode":"EMS", // 快递公司编号 详见：快递公司编码对照表
"number":"9796578035309",// 运单编号
"logisticsStatus":"SIGN", // 当前最新物流状态 详见：物流状态编码对照表
"logisticsStatusDesc":"已签收", // 当前最新物流状态描述
"details":[ // 完整的物流轨迹
{
"time":1632123146000, // 物流变更时间
"logisticsStatus":"ACCEPT", // 物流状态 详见：物流状态编码对照表
"subLogisticsStatus":"ACCEPT", // 物流子状态 详见：物流状态编码对照表
"desc":"", //物流路由信息描述内容
"areaCode":"CN330100000000", // 路由节点所在地区行政编码
"areaName":"浙江省,杭州市" // 路由节路由节点所在地区
},
{
"time":1632140994000,
"logisticsStatus":"TRANSPORT",
"subLogisticsStatus":"TRANSPORT",
"desc":"离开【杭州电商仓配揽投部】,下一站【杭州萧山区东片集散中心】",
"areaCode":"CN330100000000",
"areaName":"浙江省,杭州市"
},
...
]
}
请求格式
- application/json
返回接收结果
- 使用者需要返回接收处理结果返回给接口提供者
- 如果是接收失败，接口提供者会再次推送，最多推送3次
//接收成功
{
"success":true
}
// 接收失败
{
"success":false,
"msg": "接收失败"
}
接收示例(java)
@PostMapping("callbackUrl")
public Map<String,Object> receive(@RequestBody String data, HttpServletRequest request) {
log.info("接收到快递物流推送数据: {}", data);
... // 处理自己的业务逻辑
Map<String, Object> result = new HashMap()
if (处理成功) {
result.put("success",true);
} else {
result.put("success",false);
result.put("msg","接收失败, xxx");
}
return result;
}
