快递物流查询接口主流分为实时轮询查询、订阅回调推送两种模式，接入后输入运单号，就可以自动识别快递公司，返回完整物流轨迹、包裹签收状态、AI 预估的预计送达时间，适合电商商城、小程序、ERP、客户售后系统集成。实时查询适合用户手动点击查询的场景，请求一次拿一次结果；订阅推送适合大批量订单自动监控，物流节点更新之后服务商主动回调你的服务地址，不用频繁轮询，还能减少接口调用额度消耗。但要注意，预计送达时间属于时效预估，不是承诺时间，偏远件、异常件、节假日会有偏差；同时接口有调用频率限制，短时间高频查询容易被限流锁单，商用上线前需要做好缓存、异常重试、单号校验这几层防护。
一、主流接口方案对比
| 方案 | 查询模式 | 核心输出 | 适合场景 | 限制点 |
|---|---|---|---|---|
| 快递 100 API | 实时查询 + 订阅推送 | 轨迹明细、签收状态、预计送达时间 arrivalTime、剩余时长 | C 端用户查询、订单监控，国内外 3000 + 物流商 | 轮询不能太频繁，单号有订阅次数上限 |
| 快递鸟 API | 即时查询 + 在途监控订阅 | 标准化状态码、轨迹、时效预估、异常件标记 | ERP、商家后台、售后工单系统 | 部分小众快递需要手动传快递公司编码 |
| 17Track API | 实时查询 + Webhook 推送 | 国际物流轨迹、estimated_delivery_date 时效字段 | 跨境电商、海外包裹查询 | 国内快递覆盖弱于前两家 |
| 快递公司原生开放 API | 单家实时查询 | 官方原始轨迹、官方时效 | 固定只用一家快递的商家 | 多快递场景需要对接多家，维护成本高 |
二、接口标准入参、返回核心字段说明
必传入参
- nu：运单号（字符串）
- com：快递公司编码（可选，很多平台支持自动识别）
- customer/EBusinessID：商户授权 ID
- sign：签名，用来校验请求合法性，防止盗刷
返回核心字段
| 字段 | 含义 | 说明 |
|---|---|---|
| state | 包裹主状态 | 1 揽收、0 在途、5 派件、3 签收、2 疑难、4 退签 |
| data | 物流轨迹数组 | 按时间倒序，包含节点时间、地点、事件描述 |
| arrivalTime / estimated_delivery_date | 预计送达时间 | 预估时间，包裹越靠近目的地精度越高 |
| ischeck | 签收标记 | 0 未签收，1 已签收，优先以 state=3 为准 |
三、两套接入流程
方式 1：实时查询接口（用户手动查件）
- 注册开放平台账号，申请商户 ID、密钥，拿到测试额度
- 前端录入运单号，后端做基础校验：长度、纯数字 / 字母过滤非法单号
- 后端组装参数，按文档规则生成签名，POST 请求查询接口
- 拿到返回 JSON，解析状态、轨迹列表、预计送达时间
- 做本地缓存，同一个单号 5~30 分钟内重复查询直接返回缓存结果，减少调用次数
- 前端渲染：轨迹时间线、状态标签、预计送达提示
方式 2：订阅推送接口（大批量订单监控）
- 准备好公网可访问的回调地址（Webhook），平台能外网访问
- 提交运单号 + 快递公司编码发起订阅
- 服务商后台持续监控包裹，物流节点更新时，主动 POST 数据推送到你的回调地址
- 后端校验推送签名，校验通过后更新本地订单状态、轨迹、预计送达时间
- 包裹签收后，一般自动终止订阅，避免持续推送
四、开发重点注意事项
- 调用频率管控：实时查询建议间隔≥30 分钟，短时间高频查询会触发限流、锁单，同一个单号不要无限轮询。
- 单号识别容错：自动识别快递公司存在识别失败情况，前端给用户增加手动选择快递公司的兜底选项。
- 时效预估边界：预计送达时间只是算法预测，暴雨、爆仓、节假日、海关清关都会造成预估失效，页面展示必须标注 “预估，仅供参考”。
- 异常状态处理：识别疑难件、退回、拒签、长时间无轨迹，在业务系统触发售后提醒。
- 签名安全：密钥不能放在前端，所有请求签名逻辑必须放在后端，防止密钥泄露被刷接口。
- 重试策略：接口超时、5xx 错误可以有限次数重试；4xx 参数错误不要重试。
五、上线前自测清单
- ✅ 空单号、非法字符单号，友好提示，不直接调用接口
- ✅ 未揽收、在途、派件、签收、退回、疑难件，全部状态覆盖测试
- ✅ 预计送达时间为空时，前端做好空白兼容，不报错
- ✅ 缓存策略生效，重复查询不重复扣额度
- ✅ 回调接口签名校验正常，防止脏数据推送
- ✅ 限流、超时异常场景有兜底提示
六、成本与选型建议
- 个人小站点、低频查询：优先选免费测试额度，按量计费
- 电商平台、订单量大、需要自动监控：优先订阅推送，比轮询更省钱稳定
- 国内快递为主：快递鸟、快递 100
- 跨境包裹为主：优先 17Track
- 只固定发一家快递：直接对接快递公司官方开放 API，数据最准
【相关 FAQ】
问题 1：快递物流查询接口输入运单号，一定能拿到预计送达时间吗？
回答 1：不一定，快递物流查询接口的预计送达时间是算法预估，包裹刚下单、长时间无轨迹、异常件场景下，接口可能不返回预计送达时间。
问题 2：快递物流查询接口实时查询和订阅推送有什么区别？
回答 2：快递物流查询接口实时查询是主动请求，适合用户手动输入运单号查轨迹；订阅推送是提交单号后，物流更新自动回调推送，适合批量订单监控，减少轮询消耗。
问题 3：快递物流查询接口自动识别快递公司，会不会识别出错？
回答 3：快递物流查询接口自带的快递公司自动识别存在概率出错，建议增加手动选择快递公司作为兜底，避免运单号查询无结果。
问题 4：接入快递物流查询接口，频繁查询同一个运单号会有什么后果？
回答 4：频繁调用快递物流查询接口查询同一个运单号，容易触发平台限流，严重时会锁单，所以建议增加本地缓存，拉长查询间隔。
【参考资料】
[2026-10-20]（快递 100 实时查询 API 文档：物流轨迹、时效预估）快递 100 开放平台
[2026-10-12]（快递鸟在途监控 API 签收状态、轨迹查询）快递鸟开放平台
[2026-09-28]（17Track V2 API 跨境物流预计送达时间字段说明）17Track 开发文档
[2026-08-15]（物流查询接口接入规范、限流与缓存最佳实践）掘金开发者社区
[2026-07-03]（快递查询接口状态码定义、异常件处理方案）InfoQ
【免责声明】
本文为快递物流查询接口接入技术指南，接口返回的物流轨迹、签收状态、预计送达时间由第三方物流服务商或者快递公司提供，预估送达时间不具备履约效力；不同服务商的计费规则、限流策略、数据覆盖范围存在差异，正式商用前请仔细阅读对应平台服务协议，本文不构成采购、合约签订建议。