快递物流推送-快递订阅API接口的运用

原创

聚美智数

修改于 2026-01-31 11:46:59

910

之前笔者介绍了快递查询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;
}

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

api-gateway