企业官网建设流程全解析

id="wenyan">

快递物流轨迹订阅推送接口整理与使用教程

说明：本文基于公开文档与网上流传的接入写法整理，未对每个接口做真实请求实测，接口可用性以公开文档为准，集成前请自行发请求验证。

写在前面

做电商、仓储、客服系统时，常要盯着几百上千个快递单号的状态变化。最朴素的做法是定时轮询查询接口：每隔几分钟把所有单号再查一遍。问题在于——大部分单在两次轮询之间根本没变化，请求打了是白打；间隔调短费用涨、调长又延迟。

「快递订阅推送」就是来解决这件事的：你提交一次单号，平台在后台监控物流，一旦有更新就主动回调你，直到签收为止。你不用再主动查，而是「物流信息主动来找你」。

下面把市面上能找到的几个订阅推送接口整理成可对比的接入写法，覆盖批量订阅、按单订阅、带签名的订阅等几种形态。每家的参数、返回示例都按公开文档如实抄录，需 key 的会标注清楚。

1. 接口总览

易源各接入点的公共字段统一封装在showapi_res_body里，其余平台各有自己的响应结构，下面分节说明。

2. 易源 ShowAPI：批量提交订阅单号（2650-2）

一句话定位：批量订阅入口——每次最多 100 单一次提交，物流轨迹一旦有更新，平台就把结果推送到你指定的回调 URL，直到签收结束。异步操作，带多次重试与容错切换机制。

请求参数（application/x-www-form-urlencoded，需自备 appKey，本文按官方文档整理写法，未返回真实业务数据）：

nu_list内每个对象的字段：

• com：快递公司编码，支持auto自动识别
• nu：快递单号
• phone：手机号后四位，顺丰、跨越、中通、壹米滴答、信丰需要
• out_code：你自己定义的唯一业务标识（长度<50），推送时原样携带回来，方便关联订单
• shipping_address/delivery_address：寄/收件地址，至少到省市区，用于轨迹预测
• format：推送格式json或xml，默认 json

请求示例（地址用占位，appKey 自行替换）：

POST 你的易源网关地址/2650-2?appKey=YOUR_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_code=0表示成功）：

{ "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 天内同一运单号多次查询不重复扣费（查询类套餐）

订阅请求参数：

推送数据结构（推送到你的 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 签名调用）：

接入注意：云市场走「调用地址 + 认证方式（简单身份认证 AppCode / 签名认证 AppKey&AppSecret）」，接口文档页里可直接在线调试；扣费以 http 200-300 响应为准。

5. 阿里云市场：数勋科技 快递查询订阅（cmapi00066607）

一句话定位：GET 单号订阅——按单号收费、自动识别单号、定时跟踪监控、主动推送，覆盖 600+ 快递公司。

请求参数（GET）：

套餐参考（公开页面信息）：测试套餐 2 元/50 单，19 元/500 单，72 元/2000 单，340 元/1 万单（开票主体：杭州数勋科技）。

6. 华为云云商店：快递物流轨迹订阅 v2

一句话定位：云商店上的订阅推送商品，按单号收费、自动识别单号、定时跟踪监控、实时返回物流信息，覆盖 600+ 快递公司（开票主体：杭州安那其科技）。参数结构公开页面写得较简略，接入细节需在购买后按商品文档核对。

7. 快递鸟：带签名的订阅推送（网上流传写法）

一句话定位：第三方物流聚合平台，用「用户 ID + 密钥 + 数据签名」鉴权，订阅推送 2.0 走RequestType=1008。下面是一段网上流传的 Java 写法（签名算法核心）：

签名算法：

DataSign = UrlEncode( Base64( MD5( RequestData + ApiKey ) ) )

订阅请求参数：

注意事项：密钥（AppKey）需向平台申请，务必保管；Callback传的是你自己系统里的订单号而非快递单号，平台签收时会把LogisticsCode推回。

横向对比（事实对照）

结论：几家能力方向一致（提交单号 → 平台跟踪 → 回调推送），差异集中在「是否支持批量提交」「鉴权方式」「返回里有没有高级状态（预计路线/经纬度）」「走哪种计费」。没有全能最优，按你自己的成本、批量规模、是否需要 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_code==0、是否拿到 succ_list） return bool(data)

回调服务端示例（各家都要正确应答，否则会被判推送失败而触发重试）：

from flask import request, jsonify @app.post("/express/callback") def on_push(): # 各源推送到这里：先校验来源（易源可用 callback_secret 验签， # 快递鸟/云市场按各自签名规则校验），再落库 body = request.get_json(silent=True) or request.form.to_dict() handle(body) # 更新订单物流状态 return jsonify({"success": True}) # 必须返回 HTTP 200 + success:true

踩坑清单

1. 回调没正确应答 = 推送被判失败：几乎所有源都要求回调端返回HTTP 200 + {"success":true}。只回个200 OK空体，平台会当成失败继续重试，浪费资源。回调端务必显式 return success 对象。
2. out_code/Callback别留空：这是你把自己业务订单和快递单号关联起来的唯一线索，留空了推送回来你不知道是哪单。
3. auto 识别会失败：单号让平台自动识别时，识别不中会返回item_code=6（易源）之类错误，此时要手动指定com重提。
4. 隐私号要传完整后四位：顺丰、中通、跨越等的phone参数要求完整后 4 位，只传 3 位查不到。
5. 重复单号不要慌：易源item_code=8是「重复单号、订阅记录更新成功」，不是错误，且重复提交不重复扣费。
6. 回调地址写死/写错域名：订阅是异步的，地址错了要很久才发现。上线前先拿测试单号打一次全链路。
7. 别把订阅当即时查询：快递100 首次监控约 15 分钟、之后约 2 小时一轮，需要「马上看到当前轨迹」的场景要配合主动查询接口做兜底。
8. 签名源（快递鸟）密钥泄露：AppKey 一旦外泄请求全被打穿，务必服务端保管、别写进前端。

附录：补充说明

• 网上还能搜到一些同类订阅接口（如某些「极速数据」「快递助手」聚合页），公开写法不完整或需自备 key 才能看全参数，本文未逐一收录，需要时以对应平台官方文档为准。
• 华为云订阅 v2 的商品页参数写得较简，接入细节建议在云商店购买后按附带的接口文档核对。
• 所有源都以「需 Key/账号 + 未做真实请求实测」为前提。集成前请先用测试单号走通「提交订阅 → 收到推送 → 正确应答」全链路，再上生产。

常见问题 FAQ

问：订阅推送和轮询查询到底差在哪？差在触发方式：轮询是你主动反复查（大部分是空跑），订阅是你提交一次、平台有变化才主动回调你，成本更低、实时性更好。

问：我的回调服务必须怎么应答才算推送成功？返回 HTTP 状态码 200，且响应体为{"success":true}（易源、快递100 等都遵循这个约定），否则平台判为失败并进入重试。

问：易源一次最多能订阅多少个单号？2650-2 接入点每次最多提交 100 单，超出要分批。

问：out_code是什么、为什么重要？是你自定义的唯一业务标识（长度小于 50），平台推送时会原样带回，用它来关联你自己的订单号。

问：为什么com=auto时会返回item_code=6？auto 没识别出单号对应的快递公司，需要指定具体的com编码重新提交。

问：重复提交同一个单号会多扣钱吗？不会。易源返回item_code=8「重复单号订阅记录更新成功」，重复提交不重复计费。

问：订阅成功后多久能收到第一次推送？看平台监控节奏，快递100 官方说明首次约 15 分钟内监控一次，之后约每 2 小时一轮并按状态调整；有更新才推。

问：回调地址可以中途改吗？可以。易源通过 2650-1 全局设置，或在 2650-2 提交时单独传callback_url；两处都设时以当前提交的为准。

问：能不能只收推送、不主动查？建议订阅 + 主动查询结合：订阅负责自动盯，主动查询负责前端即时展示和兜底查漏。

问：顺丰、中通这类要手机号，我传全号还是后四位？传完整后四位。例：隐私号 13xxxxx1-234，要传的后四位是 1234。

问：怎么判断订阅接口可用？要看什么字段？易源看showapi_res_body.ret_code（0 成功）与succ_list/fail_list；其余平台看各自的响应成功标志，本文已按各源字段如实列出。

问：本文里的接口都实测过吗？没有。本文基于公开文档与网上流传的接入写法整理，未对每个接口做真实请求实测，接口可用性以公开文档为准，集成前请自行验证。

物流时效查询接口整理与使用教程

说明：本文基于公开文档与文章整理，未对每个接口做真实请求实测，接口可用性以公开文档为准，集成前请自行验证。

写在前面

电商、生鲜、跨境订单里经常出现一个诉求：发货前想知道"从 A 地寄到 B 地大概几天到"，发货后又想**"这个单号预计哪天能签收"**。这类需求对应的就是「物流时效查询 / 预估送达时间」接口。

先说两点通用提醒：

• 市面同类接口数量不少，但不少免费接口可能已停止服务、或只返回占位/演示数据，集成前请自行发一次请求验证；
• 「预估送达时间」本质是基于历史数据的算法预测，不是确定性承诺，返回的往往是"预计 X 小时可达 / 预计 X 月 X 日可达"这类带置信度的估计，业务上建议把它当参考值而非死承诺；
• 本文未做真实请求实测，所有参数、返回示例均来自公开文档，字段与写法以各家官方文档为准。

1. 接口总览

2. 万维易源（ShowAPI）物流时效查询

定位：传「发货地 + 目的地 + 快递公司编码」，返回预计运输用时（小时）。属于"发货前按地址预估时长"这一类，返回的是单一数值型时长字段，适合做时效档位判断（如"是否次日达"）。

接入点（需自备 appKey）：本文按官方文档整理接入写法，不返回真实业务数据。

请求参数：

请求示例（写法示意）：

POST 易源物流时效查询接入点?appKey=YOUR_APPKEY Content-Type: application/x-www-form-urlencoded from_address=云南省昆明市西山区&to_address=广东省深圳市福田区&com=shunfeng

返回示例（结构示意）：

{ "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）：本文按公开文档整理，不返回真实业务数据。

请求参数：

快递公司编码示例：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. 发货后时效预测（按单号）

定位：已发货，根据快递单号 + 目的地预测这个单预计哪天送达，并可结合物流轨迹接口查询当前位置。是"发货后查询"这一类。

请求参数：在"发货前预估"参数基础上增加：

返回示例（结构示意）：

{ "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，本文未做真实请求。

横向对比（事实对照）

各有取舍，没有全能最优，按你自己的成本、精度与是否要"置信度"的需求来选。

生产环境参考实现（多源降级）

把不同源列为对等节点，"发请求并落业务字段、失败就切下一源"；各源排序与优先级交由调用方决定。基地址与 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}, timeout=5) 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}, timeout=5) 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 小时比较即可；但注意它是预测值，建议留余量。

问：本文里的接口都实测过吗？答：没有。本文基于公开文档与文章整理，未对每个接口做真实请求实测，集成前请自行验证。