KEY="${KUAIDI100_API_KEY:-null}"
RESULT=$(curl -s "https://api.kuaidi100.com/stdio/autoNumber?key=${KEY}&kuaidiNum=${快递单号}")
echo "$RESULT"

KEY="${KUAIDI100_API_KEY:-null}"
RESULT=$(curl -s --get "https://api.kuaidi100.com/stdio/estimatePrice" \
  --data-urlencode "key=${KEY}" \
  --data-urlencode "kuaidicom=${快递公司编码}" \
  --data-urlencode "recAddr=${收件地址}" \
  --data-urlencode "sendAddr=${寄件地址}" \
  --data-urlencode "weight=${重量}")
echo "$RESULT"

KEY="${KUAIDI100_API_KEY:-null}"
RESULT=$(curl -s --get "https://api.kuaidi100.com/stdio/estimateTime" \
  --data-urlencode "key=${KEY}" \
  --data-urlencode "kuaidicom=${快递公司编码}" \
  --data-urlencode "from=${出发地}" \
  --data-urlencode "to=${目的地}" \
  --data-urlencode "orderTime=${下单时间}" \
  --data-urlencode "logistic=${物流轨迹JSON}")
echo "$RESULT"

快递100 API 技能

通过 curl 调用快递100 API 接口，实现快递物流查询相关功能。

环境变量

• - KUAIDI100APIKEY：快递100 API Key（可选，未设置时使用免费额度）

API 基础地址

https://api.kuaidi100.com/stdio

Key 处理规则

• - 若环境变量 KUAIDI100APIKEY 已设置且不为空，则使用该值作为 key 参数
• 否则将 key 参数设为 null（字符串）

bash
KEY=${KUAIDI100APIKEY:-null}

额度耗尽处理

若接口返回内容包含免费调用额度已耗尽、今日免费、额度不足等字样，需告知用户：

今日免费调用额度已耗尽。您可前往 快递100 API 开放平台 注册账号并获取专属 API Key，然后将 Key 更新到环境变量 KUAIDI100API_KEY 中即可继续使用。

---

工具列表

1. query_trace — 查询快递物流轨迹

触发场景：用户询问某快递单号的物流状态、快递到哪了、轨迹查询等。

参数：

• - kuaidiNum（必填）：快递单号
• phone（可选）：手机号，顺丰速运、顺丰快运、中通快递必填

curl 调用：
bash
KEY=${KUAIDI100APIKEY:-null}
RESULT=$(curl -s https://api.kuaidi100.com/stdio/queryTrace?key=${KEY}&kuaidiNum=${快递单号}&phone=${手机号})
echo $RESULT

若手机号为空则省略 phone 参数：
bash
RESULT=$(curl -s https://api.kuaidi100.com/stdio/queryTrace?key=${KEY}&kuaidiNum=${快递单号})

---

2. auto_number — 识别快递公司

触发场景：用户想知道某快递单号属于哪家快递公司，或需要在调用其他接口前识别快递公司编码。

参数：

• - kuaidiNum（必填）：快递单号

curl 调用：
bash
KEY=${KUAIDI100APIKEY:-null}
RESULT=$(curl -s https://api.kuaidi100.com/stdio/autoNumber?key=${KEY}&kuaidiNum=${快递单号})
echo $RESULT

---

3. estimate_price — 估算运费

触发场景：用户询问从某地寄快递到某地的费用、运费是多少等。

参数：

• - kuaidicom（必填）：快递公司编码（小写），支持：

- 顺丰：shunfeng
- 京东：jd
- 德邦快递：debangkuaidi
- 圆通：yuantong
- 中通：zhongtong
- 申通：shentong
- 韵达：yunda
- EMS：ems

• - recAddr（必填）：收件地址，如 广东深圳南山区
• sendAddr（必填）：寄件地址，如 北京海淀区
• weight（必填）：重量（kg，不带单位），默认 1

curl 调用：
bash
KEY=${KUAIDI100APIKEY:-null}
RESULT=$(curl -s --get https://api.kuaidi100.com/stdio/estimatePrice \
--data-urlencode key=${KEY} \
--data-urlencode kuaidicom=${快递公司编码} \
--data-urlencode recAddr=${收件地址} \
--data-urlencode sendAddr=${寄件地址} \
--data-urlencode weight=${重量})
echo $RESULT

---

4. estimate_time — 预估寄件送达时间

触发场景：用户寄件前询问预计几天到、送达时间等（尚未寄出，无物流轨迹）。

参数：

• - kuaidicom（必填）：快递公司编码（小写），支持：

圆通yuantong、中通zhongtong、顺丰shunfeng、顺丰快运shunfengkuaiyun、京东jd、极兔速递jtexpress、申通shentong、韵达yunda、EMSems、跨越kuayue、德邦快递debangkuaidi、EMS-国际件emsguoji、邮政国内youzhengguonei、国际包裹youzhengguoji、宅急送zhaijisong、芝麻开门zhimakaimen、联邦快递lianbangkuaidi、天地华宇tiandihuayu、安能快运annengwuliu、京广速递jinguangsudikuaijian、加运美jiayunmeiwuliu

• - from（必填）：出发地，如 广东省深圳市南山区
• to（必填）：目的地，如 北京市海淀区
• orderTime（可选）：下单时间，格式 yyyy-MM-dd HH:mm:ss，默认当前时间
• expType（可选）：业务/产品类型，如 标准快递

curl 调用：
bash
KEY=${KUAIDI100APIKEY:-null}
RESULT=$(curl -s --get https://api.kuaidi100.com/stdio/estimateTime \
--data-urlencode key=${KEY} \
--data-urlencode kuaidicom=${快递公司编码} \
--data-urlencode from=${出发地} \
--data-urlencode to=${目的地})
echo $RESULT

若需传 orderTime 或 expType，追加对应 --data-urlencode 参数即可。

---

5. estimatetimewith_logistic — 预估在途快递送达时间

触发场景：用户查询了物流轨迹（querytrace）后，询问还需多久到达、预计几号能到等，通常在 querytrace 之后调用。

参数：

• - kuaidicom（必填）：快递公司编码（同 estimatetime，见上方支持列表）
• from（必填）：出发地，如 广东省深圳市南山区
• to（必填）：目的地，如 北京市海淀区
• orderTime（必填）：取 querytrace 返回的最早物流轨迹时间，格式 yyyy-MM-dd HH:mm:ss
• logistic（必填）：历史物流轨迹 JSON 数组，取自 query_trace 返回数据，格式：

json
[{time:2025-12-29 12:43:35,context:您的快件已到达快递驿站，请及时取件,status:投柜或驿站},{time:2025-12-29 08:48:27,context:【河北省承德市隆化县】的郭工正在派件,status:派件}]

curl 调用：
bash
KEY=${KUAIDI100APIKEY:-null}
RESULT=$(curl -s --get https://api.kuaidi100.com/stdio/estimateTime \
--data-urlencode key=${KEY} \
--data-urlencode kuaidicom=${快递公司编码} \
--data-urlencode from=${出发地} \
--data-urlencode to=${目的地} \
--data-urlencode orderTime=${下单时间} \
--data-urlencode logistic=${物流轨迹JSON})
echo $RESULT

---

结果处理

所有接口均直接返回 Markdown 格式内容，无需额外处理，直接将结果返回给用户即可。

典型调用流程

用户询问快递还需多久到
→ 1. query_trace 查询物流轨迹（获取快递公司、轨迹数据）
→ 2. estimatetimewith_logistic 预估剩余时间（携带轨迹数据）
→ 返回结果给用户