快递物流查询：按次查询与按单查询两种接口的技术解析

快递物流查询接口面向电商、零售、生活服务、ERP 与小程序等场景，提供对国内外 1500 多家快递物流公司运单轨迹的标准化查询能力，覆盖顺丰、韵达、中通、申通、圆通、邮政、DHL、UPS、京东、EMS 等主流承运商。同一套单号识别能力，在接入层暴露为两种形态——快递按次查询与快递按单查询 V2，二者在扣减口径、参数设计、时效预估上存在系统性差异。本文以技术视角拆解两套接口的请求参数、返回结构、调用示例与适用边界，并给出工程选型思路，供系统服务商、开发者与 ERP/小程序团队参考。

一、按次查询与按单查询的核心区别

两套接口解决的是同一个问题——"根据快递单号返回物流轨迹"，区别在于计次口径与能力边界。

一句话概括：按次查询以"调用次数"为计次口径与能力单元，每一次请求都独立返回当前轨迹快照；按单查询 V2 以"运单"为单元，30 天内同一单号的多次查询共享一次计次，并在此之上叠加时效预估能力。

二、选型思路

选择哪种形态，取决于业务查询频率与是否需要时效预估，而非"哪个更好"。

• 低频、按需查询：用户主动点"查物流"、售后人工核单等场景，查询量与用户行为一一对应，选按次查询即可，逻辑简单、接入成本低。
• 高频、系统轮询：电商订单系统定时批量刷新在途包裹状态，同一单号一天可能被查多次。此时按单查询 V2的去重计次口径更贴合"按运单跟踪"的业务语义。
• 需要时效预估：要在下单后给用户展示"预计送达时间"，或做逆向时效预警，需要按单查询 V2 的 delivery_address / shipping_address 反算能力。

三者可共存：同一业务里"用户查物流"走按次，"订单系统批量刷新"走按单，按触发方各自选型。

三、能力概览

两套接口共用同一组承运商识别基础，能力差异体现在参数与返回上：

四、适用场景

• 电商订单履约：下单后跟踪在途包裹，用户端展示物流节点；高频刷新场景用按单 V2 去重计次。
• 售后核单：人工查询单个运单，按需、低频，用按次查询即可。
• 时效承诺与逆向预警：需在发货前给用户展示"预计送达时间"，或对超时单做提醒，用按单 V2 的时效预估字段。
• 小程序 / APP / ERP 集成：把轨迹查询与时效预估封装成内部服务，多端共用；按单 V2 更适合"按运单跟踪"的长期态。

五、接入流程

接入分四步，按次与按单流程一致，差异仅在调用时填写的参数。

1. 开通服务：在阿里云云市场开通对应的接口资源包，获取 AppCode（网关也可采用签名认证方式）。
2. 获取调用地址：两套接口均为 GET 请求，调用地址见各自控制台配置，返回体为 JSON。
3. 组装参数：
   • 按次查询：com、nu、phone（可选）、callback_url（可选，异步订阅）。
   • 按单查询 V2：com、nu、phone（可选）、delivery_address（可选）、shipping_address（可选）。
4. 鉴权调用：请求头携带 Authorization: APPCODE <appcode>，或按签名方式携带 AppKey / AppSecret。仅当 HTTP 响应状态码为 200 时计次。

六、请求参数设计

6.1 快递按次查询（cmapi010996）

6.2 快递按单查询 V2（cmapi00064202）

七、调用示例

鉴权统一为 Authorization: APPCODE <appcode>。以下示例中的 appcode、单号、地址均为占位，替换为你的真实凭据与业务数据。

7.1 按次查询（Python）

import requests

def query_once(appcode, nu, com="auto", phone=None):
    url = "YOUR_EXPRESS_ONCE_ENDPOINT"  # 按次查询调用地址，见控制台
    params = {
   "com": com, "nu": nu}
    if phone:
        params["phone"] = phone
    resp = requests.get(url, params=params,
                        headers={
   "Authorization": f"APPCODE {appcode}"},
                        timeout=10)
    return resp.status_code, resp.json()

7.2 按单查询 V2（Java）

public static JSONObject queryByOrder(String appcode, String nu,
                                       String deliveryAddress) throws Exception {
   
    String url = "YOUR_EXPRESS_ORDER_ENDPOINT" + "?com=auto&nu="
        + URLEncoder.encode(nu, "UTF-8");
    if (deliveryAddress != null) {
   
        url += "&delivery_address=" + URLEncoder.encode(deliveryAddress, "UTF-8");
    }
    HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
    conn.setRequestMethod("GET");
    conn.setRequestProperty("Authorization", "APPCODE " + appcode);
    int code = conn.getResponseCode();
    try (BufferedReader br = new BufferedReader(
            new InputStreamReader(conn.getInputStream(), "UTF-8"))) {
   
        StringBuilder sb = new StringBuilder();
        String line;
        while ((line = br.readLine()) != null) sb.append(line);
        return new JSONObject(sb.toString());
    }
}

八、返回结构

两套接口均返回 JSON，核心字段一致：ret_code（结果码，0 为成功）、msg（提示文案）、nu（单号）、data（轨迹节点数组，含 context 与 time）、query_num / fee_num（查询次数与计次）。按单 V2 额外返回 possible_exp_list（可能的承运商列表）与时效预估相关字段。

8.1 按次查询返回示例

{
   
  "ret_code": 0,
  "msg": "查询成功",
  "nu": "YT6493188734653",
  "expSpellName": "yuantong",
  "expTextName": "圆通速递",
  "updateStr": "2026-09-14 10:06:56",
  "data": [
    {
   "context": "快件已到达【义乌新科】", "time": "2026-09-13 18:22:10"},
    {
   "context": "快件已发往【昆明中转】", "time": "2026-09-13 17:09:49"}
  ]
}

8.2 按单查询 V2 返回示例

{
   
  "ret_code": 0,
  "msg": "查询成功",
  "nu": "JT0020720459904",
  "com": "auto",
  "query_num": 3,
  "fee_num": 1,
  "possible_exp_list": [],
  "data": [
    {
   "context": "收件人已取走邮件", "time": "2026-09-14 16:47:43"},
    {
   "context": "邮件投递到驿站", "time": "2026-09-14 14:27:08"},
    {
   "context": "【中心支局】已收寄", "time": "2026-09-14 18:28:36"}
  ]
}

注意示例中 query_num 为 3 而 fee_num 为 1，体现"30 天内同单号多次查询仅计 1 次"的去重口径。

九、在线调试实录

以按单查询 V2 为例，走一次"自动识别承运商 + 时效预估"的调试流程。

场景：一张京东快递单号 JT0020720459904，用户只知道寄件地址 山西省运城市河津市，希望同时拿到最新轨迹与预计送达时间。

调试步骤与观察点：

调试要点：auto 识别基于历史单号特征，存在误差，正式环境建议传入准确承运商编码；phone 对顺丰、跨越、中通为必填，缺失时相关承运商的轨迹会不完整。

十、调用限制与规范

具体 QPS 上限、每日配额与并发数以控制台实时配置为准，接入前在控制台核对。工程规范建议：

• 前置校验：单号非空、格式校验、承运商编码白名单校验，避免无效请求浪费配额。
• 幂等：同一单号查询是幂等的，重试不会改变轨迹结果；配合 fee_num 去重口径可放心重试。
• 重试策略：对 5xx 与超时做指数退避重试；对 ret_code != 0 的确定性错误不盲目重试。
• 频控与去重：高频轮询场景用按单 V2 的去重口径，避免同一单号一天多次计次。
• 结果缓存：轨迹节点有明确 time 时间戳，可对无更新的轨迹做本地缓存，减少重复调用。
• 合规：phone 仅传尾号 4 位，不传完整手机号；隐私号按规则传完整后 4 位。

十一、能力边界与免责

十二、错误码排查指南

十三、技术 FAQ

问：按次查询和按单查询 V2 能同时接入吗？
答：可以，二者相互独立，同一业务里可按触发方分别调用——用户主动查物流走按次，系统批量刷新走按单 V2。

问：什么时候必须传 phone？
答：查询顺丰、跨越、中通时 phone 为必填；隐私号需传完整后 4 位。其他承运商可选。

问：auto 自动识别的准确性如何？
答：基于历史单号特征分析，覆盖大多数主流承运商，但无法保证 100% 命中。生产环境建议传准确承运商编码，auto 仅作兜底。

问：如何判断轨迹是否有新节点？
答：对比返回体中最新 data 节点的 time 与本地缓存时间戳，有变化才更新，避免无效写库。

问：按单 V2 的 30 天去重是从什么时候算起？
答：自该单号首次成功查询起 30 天内，重复查询共享一次计次；超过 30 天后再次查询将重新计次。

问：适用哪些系统形态？
答：电商 Web、小程序、APP、ERP、零售 SaaS 均可接入；需具备可接收 POST 回调的地址（启用异步时）。

十四、内容小结

本文以技术视角对比了两套快递查询接口：

• 按次查询（cmapi010996）：以调用次数为单元，com/nu/phone/callback_url 四参，适合低频、按需、单次查询。
• 按单查询 V2（cmapi00064202）：以运单为单元，同单号 30 天内去重计次，叠加 delivery_address/shipping_address 时效预估，适合高频跟踪与时效承诺。
• 选型原则：按查询频率与是否需要时效预估选择，而非"哪个更好"，两者可共存。

工程落地上，注意前置校验、幂等重试、结果缓存、phone 最小化采集与 auto 兜底策略，并在控制台实时核对 QPS 与配额。两套接口均遵循"仅 200 响应才计次"的口径，便于做重试与频控设计。