首页 新闻动态 知识

快递查询API怎么接入自动识别手机号补参与物流状态如何处理

发布时间：2026-08-12 20:20 点击：6358次

接入快递查询 API 时，应在同一请求中提交运单号，并用 type=auto 尝试识别快递公司；特定公司还需补手机号。业务端要分别建模物流状态和轨迹列表，并区分无信息、识别失败与鉴权异常。

快递查询接口解决什么问题

快递查询接口把“快递公司 + 运单号”转换为结构化物流结果，适合订单详情、售后客服、物流提醒和内部履约看板。它解决的是查询与展示问题，不负责下单、取消快递、修改收件信息，也不等同于快递公司的官方售后渠道。

极速数据当前的快递查询 API 文档提供两个端点：

  • /express/query：查询指定运单的物流状态与轨迹。
  • /express/type：获取快递公司名称、代号等信息。

查询端点支持 GET 和 POST，请求需要 appkey、type 和 number。其中 type 可填写具体快递公司代号，也可填写 auto 让接口尝试自动识别。公司列表端点使用 GET，可用于建立平台内部的快递代号映射。

自动识别和指定快递公司怎么选

用户只提供运单号时，可优先使用 type=auto；订单系统已经保存承运商时，直接传对应代号更便于控制和排错。

自动识别适合搜索框、客服工具等输入信息不完整的场景，但识别失败不能直接解释为运单号无效。错误码表将“快递公司不存在”“快递公司识别失败”“快递单号错误”和“单号没有信息”分成不同状态，业务系统也应保留这种差异。

指定快递公司时，不建议把页面显示名称直接当作 type。可以定期读取 /express/type，把返回的 name 与 type 分别保存为展示名称和请求代号。这样即使前端显示“顺丰”“中通”等中文名称，服务端仍使用文档规定的代号发起请求。

一个实用的订单字段结构可以包括：

字段 用途
carrier_name 面向用户展示的快递公司名称
carrier_type 调用接口时使用的快递代号
tracking_number 运单号，日志中应脱敏
mobile_suffix 确需补参时保存的手机号后四位，避免保存完整号码副本
delivery_status 归一化后的物流状态
last_trace_time 最近一条轨迹的业务时间
last_checked_at 本系统最近查询时间

哪些情况需要手机号参数

极速数据产品页提示，顺丰、中通和跨越速运查询可能需要收件人或寄件人手机号后四位；请求参数表中的可选字段名为 mobile。因此，系统不应对所有运单强制收集手机号，而应在业务确有需要时再补充。

这里要注意文档粒度：当前错误码 220 的说明只明确写出“需要收件人/寄件人手机号（顺丰）”，而产品页总说明还提到中通和跨越速运。接入时不要把 220 自行扩展成所有公司的固定行为；其他公司的补参提示应按实际响应和最新文档处理。

手机号属于个人信息。前端可只要求用户输入必要的后四位，服务端不要把完整手机号拼入普通访问日志，也不要把带有 appkey、运单号和手机号的完整请求 URL 写入监控平台。

最小请求应该怎样写

下面是根据当前文档整理的结构模板，使用明显占位符，不代表已经发起请求：

curl --get "https://api.jisuapi.com/express/query" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "type=auto" \
  --data-urlencode "number=YOUR_TRACKING_NUMBER"

当接口或快递公司明确要求手机号信息时，再增加：

--data-urlencode "mobile=LAST_FOUR_DIGITS"

APPKEY 应只保存在服务端环境变量或密钥管理服务中。浏览器、小程序和客户端不应直接持有长期有效的 APPKEY，可由自有后端校验用户权限、限制调用频率后代理查询。

返回结果怎样落库和展示

当前文档列出的主要结果包括快递公司 type、运单号 number、物流状态 deliverystatus，以及由 time 和 status 构成的轨迹列表。页面还说明 issign 已弃用，应改用 deliverystatus。

deliverystatus 当前定义为：1 在途中、2 派件中、3 已签收、4 派送失败。建议数据库保留原始值，同时映射为内部枚举，不要只保存“已签收/未签收”两个状态。否则派件中、运输中和派送失败会被压成同一类，后续无法做准确提醒。

轨迹列表与汇总状态应分开处理：

  1. 汇总状态用于订单列表筛选和通知条件。
  2. 轨迹列表用于详情页时间线，按返回顺序展示前应先确认排序方向。
  3. time 是物流事件时间，last_checked_at 是系统查询时间，两者不能覆盖。
  4. 重复拉取时，可用“运单号 + 事件时间 + 状态文本”的组合做候选去重键，但这只是实现建议，不是接口提供的事件 ID。

错误码应该怎样分层处理

快递查询不能只判断 HTTP 是否成功，还要检查 JSON 顶层业务状态。当前文档列出的业务错误包括：

  • 201：快递单号为空，应回到输入校验。
  • 202：快递公司为空，应补充 type。
  • 203：快递公司不存在，应刷新或核对公司代号。
  • 204：快递公司识别失败，可让用户手动选择公司。
  • 205、208、209：均与无信息有关，但文档对是否扣次数的说明不同，业务上应分别记录，不要合并为“系统故障”。
  • 206：快递单号错误，应提示用户核对输入。
  • 220：当前错误码说明指向顺丰手机号补参，应引导补充必要信息。

101 至 108 属于 APPKEY、权限、次数、IP 或接口状态等系统错误，应交给服务端监控和运维处理。网络超时、DNS 失败和非 JSON 响应则属于传输层问题，不能伪装成“暂无物流”。

重试策略也应分层：参数错误和明确无信息不适合立即循环重试；网络超时可做有限次数的退避重试；已签收订单可降低查询频率或停止定时更新。具体缓存和轮询间隔由业务时效要求、权限与当前套餐共同决定，文档未规定的固定间隔不应写死为平台规则。

快递查询结果有哪些边界

接口结果适合在业务系统中展示物流信息，但查询成功不等于快件一定按时送达，轨迹暂时没有更新也不能单独证明快件丢失。发生地址修改、拒收、理赔、催派等问题时，仍应引导用户联系承运商或订单平台处理。

截至 2026 年 8 月 12 日，极速数据快递查询文档仍提供公司列表、自动识别、轨迹列表和物流状态字段。快递公司支持范围、手机号补参规则、权限和套餐属于动态信息，上线前应重新查看精确产品页。

总结

快递查询 API 的接入重点是把公司识别、手机号补参、物流状态、轨迹事件和错误状态拆开处理。先维护快递代号映射，再用服务端 APPKEY 查询，最后按业务状态决定提示、补参或重试，才能避免把“暂无信息”误判为系统故障。