电商订单发货后,用户最常问的不是“用的哪家快递”,而是“我的包裹到哪儿了”。
但企业做一个快递单号查询功能,手里不一定有完整的信息。有的订单保存了快递公司和运单号,有的只留下单号;即使查到了物流记录,还得考虑怎样把揽件、运输、派送、签收这些状态展示给用户。
只有快递单号,能不能查?
可以。探数 API 的智能快递查询 API支持在物流查询时不填写快递公司编码,由接口尝试识别承运商;也提供单独的快递公司识别接口。不过,顺丰、中通、跨越快递还需要收件人或寄件人手机号后四位,并不是所有运单都只填一个单号就够了。
把这个条件提前考虑进去,查件页面才不会出现“用户明明输入了单号,为什么还是查不出来”的尴尬。
智能快递查询API分为四个字接口

先分清楚一件事:识别快递公司和查询物流轨迹是两种需求,不一定要先后调用两个接口。
如果订单后台缺少承运商信息,只想补全“这张单号属于哪家公司”,可以使用单号识别快递公司接口。
输入运单号,返回快递公司名称、编码及联系方式等信息。比如识别出中通快递,系统就可以记录对应的公司编码 zto。
如果目的就是查物流,快递查询接口 V1、V2 都支持 com 留空。接口会尝试根据运单号识别快递公司并查询轨迹;订单中已经有准确公司编码的,也可以直接传入。
这里有两个容易混淆的参数:
| 参数 | 用途 | 填写要求 |
|---|---|---|
no |
快递单号 | 必填 |
com |
快递公司编码 | 可选;已知时建议填写 |
phone |
收件人或寄件人手机号后四位 | 顺丰、中通、跨越快递需要填写 |
智能快递查询 API 支持国内外 2000 多家快递公司的物流跟踪。四个子接口不是四道固定步骤,企业可以根据订单系统已经掌握的信息来选。
| 子接口 | 主要解决什么问题 | 适合什么需求 |
|---|---|---|
| 快递公司查询 | 获取快递公司名称、编码、联系方式等 | 订单系统需要承运商列表 |
| 单号识别快递公司 | 通过快递单号识别承运商 | 订单中只有单号、缺少快递公司信息 |
| 快递查询接口 V1 | 查询当前状态与文字物流轨迹 | 订单页展示物流进度和文字时间线 |
| 快递查询接口 V2 | 查询物流状态、轨迹及更细的地区和子状态信息 | 需要展示更详细的物流节点信息 |
其中,快递公司查询比较适合有承运商选择列表的系统:它可以提供公司编码、名称、官网、客服电话等信息。
真正面向用户展示“包裹到哪里了”,主要还是使用 V1 或 V2 物流查询接口。
快递查询 API 返回的内容,不只是一个“已签收”。
以V2 示例为例,返回结果里有当前签收状态,也有多条物流轨迹:包裹什么时候揽收、什么时候离开转运中心、何时到达派送网点,以及最终签收的时间。
如果把这些内容放到电商订单页,可以分成两层展示:
① 先让用户看到当前状态。 比如“运输中”“派送中”“已签收”,不需要用户翻完整个轨迹列表才找到结果。
② 再按时间展示物流记录。 例如包裹到达哪个网点、何时离开转运中心、什么时候完成签收。
这也是企业选择 V1 和 V2 时最直接的区别。

V1 返回快递公司、当前物流状态、签收状态文案,以及物流节点时间 datetime 和描述 remark。
如果订单页只需要一条文字物流时间线,V1 的这些字段就可以用于展示包裹进度。

V2 除了物流状态和轨迹描述,还提供更详细的信息:
| 字段 | 对订单页有什么用 |
|---|---|
tracks_count |
展示轨迹记录条数 |
sub_status_detail |
细分物流状态 |
list.time / list.context |
展示节点时间和事件 |
list.area_name |
展示节点所在地区 |
list.area_location |
获取节点地区坐标(GCJ-02) |
例如,某条记录写着“快件到达南京转运中心”,V2 的地区字段可以让页面把“江苏省、南京市”单独展示出来。对于需要按城市查看物流节点的管理后台,这比把所有信息挤在一行文字里更方便。
V2 提供的是物流节点地区坐标,不是包裹的连续 GPS 定位。 做页面时,把它用来标注已返回的节点就够了。
买家下单后通常只想快速知道:包裹发出了吗?正在派送吗?有没有签收?
电商平台可以把快递查询接口返回的状态放在订单顶部,再把历史物流节点放在下面。用户不必离开订单页,逐个打开不同快递公司的查询网站。
订单只有运单号时,也可以使用自动识别能力;需要手机号后四位的承运商,则提供相应的输入项。
同一套后台里可能同时存在顺丰、中通、京东、圆通等不同承运商的订单。
运营人员往往不需要点开每张运单才知道大概进度。把当前状态放进订单列表,打开详情后再看完整轨迹,就能把不同快递公司的查询结果集中在一个界面里。
如果后台需要按物流节点地区查看记录,可以进一步使用 V2 的地区字段。
自助查件入口最怕让用户填一堆信息。
如果只需要识别承运商,用单号识别接口;如果要显示包裹进度,直接使用 V1 或 V2 查询。把不同需求区分开,查询页面就不必同时展示所有功能。
物流查询还有一种情况:接口没有给出预期中的轨迹。
这时,不要把所有失败结果都写成“查询失败”。产品中的服务级错误码已经区分了不同情形:
| 返回码 | 含义 | 页面提示示例 |
|---|---|---|
206801 |
快递公司识别失败 | 暂时无法识别快递公司 |
206802 |
运单号错误 | 请核对快递单号 |
206803 |
查询失败 | 查询未成功,请稍后再试 |
206804 |
暂无物流轨迹信息(计次) | 暂无物流轨迹 |
其中,206802 和 206804 尤其不能混为一谈。
一个表示单号错误,另一个表示当前暂无物流轨迹。用户看到的提示不同,接下来要做的事也不同。
还有一个容易漏掉的地方:206804 标注为计次。企业统计查询量、核算接口使用成本时,不能把“没有查到轨迹”直接当成“没有产生调用次数”。
如果只想给订单补全快递公司,用单号识别快递公司接口。
如果订单页主要展示当前进度和历史文字轨迹,优先了解 V1。
如果需要更细的物流子状态、节点地区或地区坐标,可以考虑 V2。
而快递公司查询接口,适合需要维护承运商列表、编码和联系方式的系统。
四个子接口可以按需使用,不必每张运单都走一遍全部流程。对于企业来说,先看订单系统里已经有哪些信息、用户实际想在页面上看到什么,就更容易选出合适的快递查询 API。
🔗 产品详情及接口文档:探数 API|智能快递查询