物流状态码详解：12 种统一快递状态与状态流转

2026-07-26 · 阅读约 6 分钟

每家快递公司的原始快递状态描述都不一样：同样是签收，有的写「已妥投」，有的写「本人签收」，还有「派件已签收」「代收点签收」。如果直接拿这些原文做业务判断，代码里就得堆一大串字符串匹配。本接口把所有快递公司的状态归一成 12 个统一物流状态码，程序里只认这一套 statusCode 就够了。本文把 12 个状态码逐一讲清楚，再说明它们之间的正常流转和异常分支。

一、12 种统一状态码

查询返回的 deliveryStatus（运单当前状态）以及每条轨迹里的 statusCode，取值都来自下面这张表。deliveryStatusText 是对应的中文名称，可直接展示给用户。

状态码	中文名	含义	典型出现时点
`PENDING`	待揽收	已下单，但快递员尚未取件	下单后、揽收前
`REGISTERED`	已受理	快递系统已受理订单、生成运单	揽收前的受理环节
`PICKUP_READY`	揽收准备中	网点已安排揽收，快递员即将上门	揽收前
`PICKED_UP`	已揽收	快递员已取件，包裹进入快递网络	揽收完成的第一步
`IN_TRANSIT`	运输中	包裹在网点、干线之间运输、中转	运输主阶段（占轨迹最长）
`OUT_FOR_DELIVERY`	派送中	包裹已到末端网点，正在派送	签收前最后一段
`DELIVERED`	已签收	收件人已签收，正常终态	流程结束
`FAILED`	派送失败	本次派送未成功（无人签收、地址问题等）	派送环节异常
`RETURNED`	已退回	包裹退回寄件方	异常终态
`CANCELLED`	已取消	运单被取消	下单后任意阶段取消
`HOLD`	暂存中	包裹暂存网点或驿站，等待自取或再派	派送前后
`UNKNOWN`	状态未知	无法归类到上述任何状态的兜底值	少见，作为保险

二、为什么用统一状态码

最直接的好处是分支逻辑收敛。不做归一时，判断「是否已签收」要匹配十几种原文；做了归一后，只需 statusCode === 'DELIVERED' 一种判断。新接一家快递公司时，它的原始状态会被映射到同一套码值，你的业务代码一行都不用改。

原始描述并没有丢：每条轨迹里 status 是归一后的简洁中文， description（如有）保留承运商原文， location 是发生地点。想展示细节就用原文，想做逻辑判断就用 statusCode。

三、状态之间怎么流转

一票普通快件的正常流转是一条主线，异常时会分出几条支线：

正常主线：
PENDING/REGISTERED → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED

异常分支：
OUT_FOR_DELIVERY → FAILED → （重新派送）→ DELIVERED
                └→ HOLD（暂存驿站，等待自取或再派）
IN_TRANSIT / OUT_FOR_DELIVERY → RETURNED（退回寄件方，终态）
任意阶段 → CANCELLED（运单被取消）

几个要点：FAILED 不是终态，后面常跟着「重新派送」并最终 DELIVERED； HOLD 在驿站自取场景很常见，别把它当异常报警；真正的终态只有三个 —— DELIVERED、RETURNED、CANCELLED。

四、用 isDelivered 判断是否完成

判断「这单是否已经收货」不用自己比对状态码，返回里有现成的布尔字段 isDelivered。它为 true 就代表已签收，可以停止轮询、归档订单：

function fenlei(r) {
  if (!r.success) return '查询失败';
  const d = r.data;
  // isDelivered 为 true 即终态，优先判断
  if (d.isDelivered) return '已完成';
  switch (d.deliveryStatus) {
    case 'OUT_FOR_DELIVERY': return '派送中';
    case 'IN_TRANSIT':       return '运输中';
    case 'FAILED':
    case 'RETURNED':         return '需要关注';
    default:                 return '处理中';
  }
}

另外两个时间字段也常用：dateDelivered 是签收时间（未签收时为空）， dateLastProgress 是最新一条轨迹的时间，可用来判断这单「多久没动了」。

五、小结

业务逻辑一律基于 statusCode / deliveryStatus，不要匹配原始文案。
是否完成直接看 isDelivered，终态只有签收、退回、取消三种。
FAILED 和 HOLD 都可能后续恢复，展示时以最新一条轨迹为准。

完整字段与错误码见接口文档；想先跑一遍，首页的在线演示用测试密钥即可，或直接注册账号拿自己的密钥。批量查询时如何逐条处理这些状态与错误，见快递批量查询与错误处理。