idwenyan快递物流轨迹订阅推送接口整理与使用教程说明本文基于公开文档与网上流传的接入写法整理未对每个接口做真实请求实测接口可用性以公开文档为准集成前请自行发请求验证。写在前面做电商、仓储、客服系统时常要盯着几百上千个快递单号的状态变化。最朴素的做法是定时轮询查询接口每隔几分钟把所有单号再查一遍。问题在于——大部分单在两次轮询之间根本没变化请求打了是白打间隔调短费用涨、调长又延迟。「快递订阅推送」就是来解决这件事的你提交一次单号平台在后台监控物流一旦有更新就主动回调你直到签收为止。你不用再主动查而是「物流信息主动来找你」。下面把市面上能找到的几个订阅推送接口整理成可对比的接入写法覆盖批量订阅、按单订阅、带签名的订阅等几种形态。每家的参数、返回示例都按公开文档如实抄录需 key 的会标注清楚。1. 接口总览接口提供方请求地址说明是否需 Key来源类型批量提交订阅单号易源 ShowAPI易源 2650-2 接入点需 appKey每次最多 100 单批量订阅有更新即推送到回调地址直至签收需 appKey第三方平台设置推送回调地址易源 ShowAPI易源 2650-1 接入点需 appKey全局设置订阅推送的回调地址可开启加密需 appKey第三方平台快递信息订阅推送快递100快递100 订阅推送接入点需账号提交单号后台跟踪首次约15分钟监控之后约每2小时需账号第三方平台快递信息订阅按单阿里云市场快递100 按单推送接入点需 AppKey/AppCode输入单号回调地址物流变化主动推送支持细分状态与AI预估时效需 Key云市场快递查询订阅数勋科技阿里云市场快递订阅接入点需 AppKey/AppCodeGET 发起自动识别单号、定时跟踪、主动推送需 Key云市场快递物流轨迹订阅 v2华为云云商店快递订阅推送接入点需 Key按单号收费、自动识别单号、定时跟踪实时返回需 Key云商店易源各接入点的公共字段统一封装在showapi_res_body里其余平台各有自己的响应结构下面分节说明。2. 易源 ShowAPI批量提交订阅单号2650-2一句话定位批量订阅入口——每次最多 100 单一次提交物流轨迹一旦有更新平台就把结果推送到你指定的回调 URL直到签收结束。异步操作带多次重试与容错切换机制。请求参数application/x-www-form-urlencoded需自备 appKey本文按官方文档整理写法未返回真实业务数据参数类型必填说明nu_listString是JSON 数组字符串每次最多 100 个单号。字段见下方callback_urlString否本批单号的推送地址若已通过 2650-1 设置过全局回调可留空两处都设则以当前为准nu_list内每个对象的字段com快递公司编码支持auto自动识别nu快递单号phone手机号后四位顺丰、跨越、中通、壹米滴答、信丰需要out_code你自己定义的唯一业务标识长度50推送时原样携带回来方便关联订单shipping_address/delivery_address寄/收件地址至少到省市区用于轨迹预测format推送格式json或xml默认 json请求示例地址用占位appKey 自行替换POST 你的易源网关地址/2650-2?appKeyYOUR_APPKEY Content-Type: application/x-www-form-urlencoded nu_list [{com:auto,nu:312570517799642,phone:,out_code:my_order_001,format:json}] callback_url 你的回调服务地址返回示例提交结果ret_code0表示成功{ showapi_res_code: 0, showapi_res_body: { ret_code: 0, msg: 调用成功, update_time: 2023-02-09 11:13:25, fail_list: [ { nu: 188731107, com: auto, remark: auto时未查到单号对应的快递公司,请指定快递公司编码, item_code: 6 } ], succ_list: [ { nu: YT6493188731107, com: yuantong, remark: 提交成功, item_code: 0 } ] } }注意事项item_code取值0提交成功、8重复单号订阅记录更新成功重复提交不重复扣费、1单号错、3格式不正确、4快递编码未收录或失效、6auto 未识别到快递公司你的回调服务收到推送时必须返回HTTP 200 且响应体为{success:true}才算收信成功推送失败的自动重试节奏约 2、4、8、16、32 分钟间隔共 5 次全局回调地址走 2650-1 接入点设置需带真实com、nu、phone参数可开启加密并用callback_secret验证推送来源推送里会原样带回你提交时的out_code这是关联业务订单的关键字段3. 快递100快递信息订阅推送一句话定位提交运单后平台跟踪状态变化时回调推送跟踪信息、预计路线、预计送达时间直到运单生命周期结束一般以「已签收」为准。订阅机制官方说明订阅成功后一般约15 分钟内进行第一次监控监控到单号已有轨迹就立即第一次推送否则等下一轮此后一般每 2 小时监控一次并按单号状态动态调整计费规则40 天内同一运单号多次查询不重复扣费查询类套餐订阅请求参数参数类型必填说明numberString是快递单号callbackurlString是推送地址http/https 开头长度不超过 200phoneString否收/寄件人电话只能填一个顺丰、中通等需后 4 位comString否快递公司编码推送数据结构推送到你的 callbackurl{ expressCode: EMS, number: 9796578035309, logisticsStatus: SIGN, logisticsStatusDesc: 已签收, details: [ { time: 1632123146000, logisticsStatus: ACCEPT, desc: 已揽收, areaName: 浙江省,杭州市 }, { time: 1632140994000, logisticsStatus: TRANSPORT, desc: 离开【杭州电商仓配揽投部】,下一站【杭州萧山区东片集散中心】 } ] }注意事项推送是 POST 形式需你的服务正确应答应答体{success:true}details是完整轨迹做前端展示时通常只需取最新一条 签收状态。4. 阿里云市场快递100 按单计费推送cmapi00072132一句话定位快递100 能力通过云市场上架的按单计费版——输入快递单号 回调地址物流变化时主动推送最新节点、预计路线、预计送达时间覆盖 3000 快递公司返回含经纬度等高级状态。适合电商、ERP、OMS、WMS、售后客服系统做订单物流自动跟踪与异常预警。请求参数POST需 AppKey/AppCode 或 AppKey/AppSecret 签名调用参数必填说明number是快递单号callbackurl是回调地址http/https长度 ≤ 200phone否顺丰、快运、中通需后 4 位resultv2否1开通行政区域解析from / to否起止地接入注意云市场走「调用地址 认证方式简单身份认证 AppCode / 签名认证 AppKeyAppSecret」接口文档页里可直接在线调试扣费以 http 200-300 响应为准。5. 阿里云市场数勋科技 快递查询订阅cmapi00066607一句话定位GET 单号订阅——按单号收费、自动识别单号、定时跟踪监控、主动推送覆盖 600 快递公司。请求参数GET参数必填说明no是快递编号code否快递代码tel否顺丰/丰网/跨越/中通需寄件或收件人手机号或后 4 位callbackUrl是接收回调地址需按规范应答套餐参考公开页面信息测试套餐 2 元/50 单19 元/500 单72 元/2000 单340 元/1 万单开票主体杭州数勋科技。6. 华为云云商店快递物流轨迹订阅 v2一句话定位云商店上的订阅推送商品按单号收费、自动识别单号、定时跟踪监控、实时返回物流信息覆盖 600 快递公司开票主体杭州安那其科技。参数结构公开页面写得较简略接入细节需在购买后按商品文档核对。7. 快递鸟带签名的订阅推送网上流传写法一句话定位第三方物流聚合平台用「用户 ID 密钥 数据签名」鉴权订阅推送 2.0 走RequestType1008。下面是一段网上流传的 Java 写法签名算法核心签名算法DataSign UrlEncode( Base64( MD5( RequestData ApiKey ) ) )订阅请求参数参数说明EBusinessID电商用户 IDRequestType1008订阅查询RequestData{Callback:订单号,ShipperCode:快递编码,LogisticCode:运单号}DataSign上式签名结果DataType2JSON注意事项密钥AppKey需向平台申请务必保管Callback传的是你自己系统里的订单号而非快递单号平台签收时会把LogisticsCode推回。横向对比事实对照维度易源批量订阅快递100 订阅云市场按单推送数勋订阅华为云订阅快递鸟带签名是否需 Key需 appKey需账号需 Key/AppCode需 Key/AppCode需 Key需 ID密钥批量提交支持≤100/次按单按单按单按单按单请求方式POST 表单表单/JSONPOSTGET文档简略POST签名返回格式JSON/XMLJSONJSONJSONJSONJSON鉴权强度appKey 查询账号体系签名/AppCode签名/AppCode平台签名MD5 签名来源类型第三方平台第三方平台云市场云市场云商店第三方平台结论几家能力方向一致提交单号 → 平台跟踪 → 回调推送差异集中在「是否支持批量提交」「鉴权方式」「返回里有没有高级状态预计路线/经纬度」「走哪种计费」。没有全能最优按你自己的成本、批量规模、是否需要 AI 时效预估来选。生产环境参考实现多源降级把几个源当成对等的降级节点先按业务顺序发请求拿到有效业务字段就停失败自动切下一个源。下面用 Python 示意各源排序、权重、阈值由你定# 多源降级示例把每家订阅服务当一个对等节点逐个尝试成功即返回 # 所有地址/密钥用占位接入时替换为你自己申请到的真实值 BASE_A 你的易源网关地址 # 易源 2650-2 批量订阅 APPKEY_A YOUR_APPKEY BASE_B 你的快递100网关地址 # 快递100 订阅推送 CALLBACK 你的回调服务地址 def try_showsapi(nu_list, callback_url): # 返回 (ok: bool, data: dict) # 实际用 requests 发 POST 表单注意 appKey 放 query pass def try_kd100(number, callbackurl, phone): pass def subscribe_with_fallback(nu_list, callback_url): for fn, name in [ (lambda: try_showsapi(nu_list, callback_url), 易源), (lambda: try_kd100(nu_list[0], callback_url), 快递100), # 这里继续接数勋 / 华为云 / 快递鸟作为后续降级节点 ]: try: ok, data fn() if ok and _valid(data): # _valid 判断关键字段是否拿到 return data, name except Exception: continue raise RuntimeError(所有订阅源均失败请人工检查) def _valid(data): # 各源结构不同各自判断成功标志如易源 ret_code0、是否拿到 succ_list return bool(data)回调服务端示例各家都要正确应答否则会被判推送失败而触发重试from flask import request, jsonify app.post(/express/callback) def on_push(): # 各源推送到这里先校验来源易源可用 callback_secret 验签 # 快递鸟/云市场按各自签名规则校验再落库 body request.get_json(silentTrue) or request.form.to_dict() handle(body) # 更新订单物流状态 return jsonify({success: True}) # 必须返回 HTTP 200 success:true踩坑清单回调没正确应答 推送被判失败几乎所有源都要求回调端返回HTTP 200 {success:true}。只回个200 OK空体平台会当成失败继续重试浪费资源。回调端务必显式 return success 对象。out_code/Callback别留空这是你把自己业务订单和快递单号关联起来的唯一线索留空了推送回来你不知道是哪单。auto 识别会失败单号让平台自动识别时识别不中会返回item_code6易源之类错误此时要手动指定com重提。隐私号要传完整后四位顺丰、中通、跨越等的phone参数要求完整后 4 位只传 3 位查不到。重复单号不要慌易源item_code8是「重复单号、订阅记录更新成功」不是错误且重复提交不重复扣费。回调地址写死/写错域名订阅是异步的地址错了要很久才发现。上线前先拿测试单号打一次全链路。别把订阅当即时查询快递100 首次监控约 15 分钟、之后约 2 小时一轮需要「马上看到当前轨迹」的场景要配合主动查询接口做兜底。签名源快递鸟密钥泄露AppKey 一旦外泄请求全被打穿务必服务端保管、别写进前端。附录补充说明网上还能搜到一些同类订阅接口如某些「极速数据」「快递助手」聚合页公开写法不完整或需自备 key 才能看全参数本文未逐一收录需要时以对应平台官方文档为准。华为云订阅 v2 的商品页参数写得较简接入细节建议在云商店购买后按附带的接口文档核对。所有源都以「需 Key/账号 未做真实请求实测」为前提。集成前请先用测试单号走通「提交订阅 → 收到推送 → 正确应答」全链路再上生产。常见问题 FAQ问订阅推送和轮询查询到底差在哪差在触发方式轮询是你主动反复查大部分是空跑订阅是你提交一次、平台有变化才主动回调你成本更低、实时性更好。问我的回调服务必须怎么应答才算推送成功返回 HTTP 状态码 200且响应体为{success:true}易源、快递100 等都遵循这个约定否则平台判为失败并进入重试。问易源一次最多能订阅多少个单号2650-2 接入点每次最多提交 100 单超出要分批。问out_code是什么、为什么重要是你自定义的唯一业务标识长度小于 50平台推送时会原样带回用它来关联你自己的订单号。问为什么comauto时会返回item_code6auto 没识别出单号对应的快递公司需要指定具体的com编码重新提交。问重复提交同一个单号会多扣钱吗不会。易源返回item_code8「重复单号订阅记录更新成功」重复提交不重复计费。问订阅成功后多久能收到第一次推送看平台监控节奏快递100 官方说明首次约 15 分钟内监控一次之后约每 2 小时一轮并按状态调整有更新才推。问回调地址可以中途改吗可以。易源通过 2650-1 全局设置或在 2650-2 提交时单独传callback_url两处都设时以当前提交的为准。问能不能只收推送、不主动查建议订阅 主动查询结合订阅负责自动盯主动查询负责前端即时展示和兜底查漏。问顺丰、中通这类要手机号我传全号还是后四位传完整后四位。例隐私号 13xxxxx1-234要传的后四位是 1234。问怎么判断订阅接口可用要看什么字段易源看showapi_res_body.ret_code0 成功与succ_list/fail_list其余平台看各自的响应成功标志本文已按各源字段如实列出。问本文里的接口都实测过吗没有。本文基于公开文档与网上流传的接入写法整理未对每个接口做真实请求实测接口可用性以公开文档为准集成前请自行验证。物流时效查询接口整理与使用教程说明本文基于公开文档与文章整理未对每个接口做真实请求实测接口可用性以公开文档为准集成前请自行验证。写在前面电商、生鲜、跨境订单里经常出现一个诉求发货前想知道从 A 地寄到 B 地大概几天到发货后又想**这个单号预计哪天能签收**。这类需求对应的就是「物流时效查询 / 预估送达时间」接口。先说两点通用提醒市面同类接口数量不少但不少免费接口可能已停止服务、或只返回占位/演示数据集成前请自行发一次请求验证「预估送达时间」本质是基于历史数据的算法预测不是确定性承诺返回的往往是预计 X 小时可达 / 预计 X 月 X 日可达这类带置信度的估计业务上建议把它当参考值而非死承诺本文未做真实请求实测所有参数、返回示例均来自公开文档字段与写法以各家官方文档为准。1. 接口总览接口请求方式说明需要 Key来源类型万维易源ShowAPI物流时效查询POST / GET传起止地址 快递编码返回预计用时小时需自备 appKey第三方平台本文按官方文档整理发货前时效预估按地址POST传始发/目的省市区返回预计时效与送达时间需自备 key第三方平台本文按公开文档整理发货后时效预测按单号POST传快递单号 目的地预测到达时间与线路需自备 key第三方平台本文按公开文档整理百递云智能时效预估POST在物流查询基础上返回预计送达时间 准确率 probability 字段需自备 key第三方平台本文按公开文档整理2. 万维易源ShowAPI物流时效查询定位传「发货地 目的地 快递公司编码」返回预计运输用时小时。属于发货前按地址预估时长这一类返回的是单一数值型时长字段适合做时效档位判断如是否次日达。接入点需自备 appKey本文按官方文档整理接入写法不返回真实业务数据。请求参数参数名类型必填说明from_addressString是发货地省市区地址如云南省昆明市西山区to_addressString是目的地省市区地址如广东省深圳市福田区comString是快递编码如shunfeng请求示例写法示意POST 易源物流时效查询接入点?appKeyYOUR_APPKEY Content-Type: application/x-www-form-urlencoded from_address云南省昆明市西山区to_address广东省深圳市福田区comshunfeng返回示例结构示意{ showapi_res_code: 0, showapi_res_body: { ret_code: 0, pre_cost_hour: 25 } }showapi_res_body.pre_cost_hour为预计用时小时ret_code 0表示查询成功。注意事项快递公司编码com用统一编码如顺丰对应shunfeng传地址时用省市区全称避免深圳福田这类省略写法该接口返回的是时长而非具体送达日期需要某天可达要在本地按时长换算需自备 appKey付费规格本文未做真实请求。3. 发货前时效预估按地址定位未下单前根据始发地与目的地预估某家快递的运输时长用于下单前给用户预计 X 天达。比上一节多返回了预计送达日期、预计送达时段、预估行驶线路。接入点需自备 key本文按公开文档整理不返回真实业务数据。请求参数参数名类型必填说明shipperCodeString是快递公司编码如 STO 申通sendProvince / sendCity / sendAreaString是始发省 / 市 / 区县sendAddressString否始发详细地址receiveProvince / receiveCity / receiveAreaString是目的省 / 市 / 区县receiveAddressString否目的详细地址catchTimeString否揽收时间不传默认取当前时间快递公司编码示例STO申通、YTO圆通、YD韵达、ZTO中通、SF顺丰、JD京东、EMS邮政、DBL德邦、JTSD极兔、CNSD菜鸟速递。返回示例结构示意{ code: 200, msg: 成功, data: { Hour: 24h, DeliveryDate: 2024-11-14, DeliveryTime: 11月14日下午可达, PredictPath: 浙江杭州转运中心-江苏南京转运中心 } }注意事项Hour是预计时效小时级DeliveryTime是某天某时段可达PredictPath是预估走的线路顺丰等部分公司对发货前预估支持有限按文档为准。4. 发货后时效预测按单号定位已发货根据快递单号 目的地预测这个单预计哪天送达并可结合物流轨迹接口查询当前位置。是发货后查询这一类。请求参数在发货前预估参数基础上增加参数名类型必填说明logisticCodeString是快递单号senderPhone / receivePhoneString否寄/收件人后四位手机尾号顺丰时需二者至少传一个返回示例结构示意{ code: 200, data: { LogisticCode: 78854085582018, Hour: 24h, DeliveryDate: 2024-11-14, DeliveryTime: 11月14日下午可达, PredictPath: 浙江杭州转运中心-江苏南京转运中心, LatestStation: xx转运中心 } }注意事项顺丰查详细时效/轨迹常需手机尾号验证LatestStation等最新轨迹字段依赖该单是否已有物流回传刚下单未揽收时可能为空。5. 百递云智能时效预估定位在物流查询接口基础上叠加智能时效预估模型返回预计送达时间并新增probability字段实时返回预测准确率如 90%让用户知道这个估计有多可信。接入方式调用物流查询接口时在请求参数里把智能时效预估开关resultv2字段取值 8打开即可返回结果会新增probability历史接入方案无需改造。返回新增字段{ probability: 90 }注意事项probability是预测置信度百分比不是送达保证底层依赖历史物流数据越临近目的地的单预测越准需自备 key本文未做真实请求。横向对比事实对照维度易源(ShowAPI)发货前预估发货后预测百递云智能预估是否需 key需 appKey需 key需 key需 key是否按单号否按地址否按地址是是查物流返回粒度预计用时(小时)时效日期线路时效日期线路最新轨迹送达时间准确率有置信度字段无无无有(proprobability)各有取舍没有全能最优按你自己的成本、精度与是否要置信度的需求来选。生产环境参考实现多源降级把不同源列为对等节点发请求并落业务字段、失败就切下一源各源排序与优先级交由调用方决定。基地址与 key 用占位常量。import requests, time # 各源接入点与 key 都在这配置BASE 用占位常量不要写死真实网关地址 BASE_EY 你的接口网关地址 # 易源(ShowAPI)物流时效接入点 BASE_PRE 你的接口网关地址 # 发货前预估接入点 BASE_POST 你的接口网关地址 # 发货后预测接入点 API_KEY YOUR_APPKEY # 自备 key def call_ey(from_address, to_address, com): r requests.post(BASE_EY, params{appKey: API_KEY}, data{from_address: from_address, to_address: to_address, com: com}, timeout5) body r.json()[showapi_res_body] assert body.get(ret_code) 0, 易源返回异常 return {pre_cost_hour: body.get(pre_cost_hour)} def call_pre(shipper, sp, sc, sa, rp, rc, ra): r requests.post(BASE_PRE, params{appKey: API_KEY}, data{shipperCode: shipper, sendProvince: sp, sendCity: sc, sendArea: sa, receiveProvince: rp, receiveCity: rc, receiveArea: ra}, timeout5) d r.json()[data] assert d, 发货前预估无数据 return {hour: d.get(Hour), delivery_date: d.get(DeliveryDate), delivery_time: d.get(DeliveryTime), path: d.get(PredictPath)} def estimate_transit(from_address, to_address, com, shipper): # 多源降级依次尝试取第一个成功 for fn in (lambda: call_ey(from_address, to_address, com), lambda: call_pre(shipper, *from_address.split(), *to_address.split())): try: return fn() except Exception: time.sleep(0.2) continue return {pre_cost_hour: None, delivery_date: None}踩坑清单预估 ≠ 承诺所有预计可达 / 预计用时都是算法估计大促双11 等揽收延迟会显著影响准确性别拿它做死 SLA。顺丰要手机尾号发货后预测顺丰单时senderPhone/receivePhone至少传一个否则查不到详细时效。编码别写错com易源与shipperCode按地址类是两套编码别混用顺丰一个是shunfeng、一个是SF。地址要全称起止地址用省市区全称省略写法容易匹配失败。刚下单没轨迹发货后预测依赖物流回传未揽收的单LatestStation等字段可能为空要有兜底。占位数据部分免费源只回演示数据集成前务必真发一次请求核对字段值。附录补充说明网上流传的同类接口还有不少快递100、快递鸟、顺丰开放平台、京东物流开放平台等本文未逐一实测部分需自备 key 或接入写法不完整此处不展开。各接口字段、返回示例均来自公开文档集成前请自行发请求验证并关注是否停服 / 是否收费。常见问题 FAQ问物流时效查询接口和快递单号查询接口有什么区别答时效查询预估还要多久 / 哪天到单号查询返回现在到哪了前者是预测后者是实时轨迹常配合使用。问没发货前能查预计送达时间吗答可以用发货前预估类接口传始发地与目的地 快递编码即可不需要单号。问返回的预计用时是小时还是天答看接口易源返回小时pre_cost_hour按地址类返回时效 具体日期以各家文档字段为准。问顺丰单为什么要传手机尾号答顺丰等公司对详细时效/轨迹有隐私验证senderPhone或receivePhone至少传一个才能查到。问预估送达时间准不准答它是基于历史数据的算法预测非承诺百递云类还返回probability置信度可据此判断可信区间。问为什么大促时预估不准答双11 等场景揽收延迟、爆仓实际发货时间晚于下单时间按当前时间的预估会失真建议结合真实揽收时间catchTime。问需要 appKey / key 吗答本文整理的主要是第三方平台接口需自备 key本文未做真实请求字段以官方文档为准。问com和shipperCode编码一样吗答不一样是两套编码顺丰在易源是shunfeng在按地址类是SF别混用。问地址该写省还是省市区答写省市区全称省略写法如深圳福田容易匹配失败。问发货后预测为什么最新轨迹是空的答刚下单未揽收或该单暂无物流回传LatestStation等字段会为空需做兜底。问能不能只按时长做次日达判断答能取预计用时小时数与 24 小时比较即可但注意它是预测值建议留余量。问本文里的接口都实测过吗答没有。本文基于公开文档与文章整理未对每个接口做真实请求实测集成前请自行验证。