kuaidi100-skill-快递100物流查询

核心用法

快递100技能提供一站式物流信息查询服务，支持五大核心功能：

| 功能 | 用途 | 典型场景 |

|:---|:---|:---|

| `query_trace` | 查物流轨迹 | "我的快递到哪了" |

| `auto_number` | 识别快递公司 | "这是什么快递" |

| `estimate_price` | 估算运费 | "寄到XX多少钱" |

| `estimate_time` | 预估寄件时效 | "几天能到" |

| `estimate_time_with_logistic` | 预估在途剩余时间 | "还要多久到" |

调用方式：通过 curl 直连 api.kuaidi100.com/stdio，支持30+主流快递公司（顺丰、京东、中通、圆通、韵达、EMS、德邦等）。

关键特性：

• 顺丰、中通等需手机号验证，自动处理参数透传
• 智能识别快递公司编码，无需用户手动填写
• 支持复杂地址解析与重量运费计算

显著优点

1. 官方数据源：快递100为行业头部物流信息平台，接口覆盖国内绝大多数快递企业
2. 功能闭环：从"查单号→认快递→估运费→预测时效"形成完整决策链
3. 零配置门槛：未设置 KUAIDI100_API_KEY 时自动使用免费额度，开箱即用

潜在局限

| 问题 | 说明 |

|:---|:---|

| **免费额度限制** | 每日免费调用次数有限，耗尽后需自行注册获取 API Key |

| **数据实时性** | 物流轨迹依赖快递公司回传，极端情况下存在 1-6 小时延迟 |

| **国际件支持弱** | 仅支持 EMS-国际件、国际包裹等少数国际线路，海外快递覆盖不足 |

| **企业版功能缺失** | 批量查询、电子面单、签收图片等企业级功能未开放 |

适合人群

• 个人用户：日常查快递、比价寄件、追踪包裹
• 小微商家：发货前运费估算、时效承诺参考
• 开发者：快速集成物流查询能力的原型项目

常规风险

• 隐私合规：查询顺丰等需手机号，存在个人信息透传风险
• 额度中断：高峰期免费额度易耗尽，生产环境建议配置专属 Key
• 地址解析误差：模糊地址（如"高新区"）可能导致运费/时效计算偏差

---

> 使用建议：日常查询完全够用；高频调用或商业场景务必前往 快递100开放平台 申请独立 API Key。

核心用法

快递100 API技能是一套完整的物流信息查询解决方案，通过curl调用快递100官方接口实现五大核心功能：查询快递物流轨迹(query_trace)、识别快递公司(auto_number)、估算运费(estimate_price)、预估寄件送达时间(estimate_time)以及预估在途快递剩余时间(estimate_time_with_logistic)。使用时只需配置可选的环境变量KUAIDI100_API_KEY，即可通过标准HTTP GET请求获取Markdown格式的返回结果，无需额外处理直接呈现给用户。

典型使用场景遵循"识别→查询→预测"的流水线模式：当用户询问某单号归属时，先调用auto_number识别快递公司；当用户关心包裹位置时，调用query_trace获取完整轨迹；当用户追问"还要多久到"时，则结合已有轨迹数据调用estimate_time_with_logistic进行精准时效预测。对于寄件前的决策支持，estimate_price和estimate_time分别解决"多少钱"和"多久到"的痛点问题。

显著优点

数据权威性是最大亮点。快递100作为中国快递物流信息服务的标杆企业，接入顺丰、京东、中通、圆通等20余家主流快递公司的官方数据通道，信息实时性和准确性远超第三方聚合平台。

功能完整性覆盖物流全生命周期：从寄件前的比价决策、时效预估，到在途中的实时追踪、智能预测，再到异常情况的主动识别，形成闭环服务体验。特别是estimate_time_with_logistic接口，通过结合历史轨迹数据进行机器学习预测，能给出比传统ETA更精准的剩余时间估算。

接入便捷性体现在零依赖设计上。纯Markdown文档型技能无需安装任何运行时或第三方库，标准curl调用兼容所有支持Bash的环境，响应结果已格式化为Markdown，真正实现开箱即用。

潜在缺点与局限性

额度约束是首要考量。免费调用额度耗尽后需用户自行注册获取API Key，这对企业级高频使用场景构成成本门槛，且文档未提供额度监控机制，存在服务突然中断的风险。

功能边界方面，当前版本仅支持查询和预测类只读操作，不包含下单、取消、改派等物流履约功能；国际件支持有限，EMS-国际件等少数线路的时效预测准确性可能弱于国内件；手机号必填限制（顺丰、中通等）在保护隐私与获取完整信息之间存在张力。

技术局限体现在：curl调用未内置重试机制，网络波动时可能失败；缺乏输入参数预校验（如单号格式校验），无效请求消耗额度；API响应结构变化时Skill可能产生解析偏差。

适合的目标群体

电商运营人员是核心用户群，需批量监控发货物流、处理异常订单、回复客户咨询；个人消费者适合偶尔查询自用包裹，免费额度通常可满足；企业服务集成场景中，客服系统、ERP、WMS等可通过该技能快速补齐物流信息能力；物流 researchers可利用历史轨迹数据做时效分析研究。不适合需要物流履约操作（如下单、预约取件）或超大规模并发查询（>万次/日）的场景。

使用风险

服务可用性风险：完全依赖快递100官方API，若其服务降级或调整接口，Skill功能将受影响，建议关注官方公告。

数据隐私风险：查询顺丰、中通等需提交手机号，地址信息在运费/时效预估中明文传输，虽经HTTPS加密，但用户需知悉数据流向第三方平台。

成本控制风险：高频使用易触发额度上限，建议生产环境配置专属API Key并建立额度监控；免费额度耗尽后的降级提示依赖字符串匹配，若官方文案调整可能导致提示失效。

预测准确性风险：estimate_time_with_logistic基于历史轨迹推算，受天气、交通、网点操作等不可控因素影响，预测结果仅供参考，不宜作为承诺依据。