Kuaidi Query

快递查询 (kuaidi-query)

快速查询国内国际主流快递公司的物流信息。基于 Track123 API，支持 200+ 家快递公司。

快速开始

# 1. 配置 API Key
cp config.example.json config.json
# 编辑 config.json，填入你的 Track123 API Key

# 2. 查询快递
node scripts/query.js sf SF1234567890123

支持的快递公司

国内快递

顺丰速运、圆通速递、中通快递、韵达速递、申通快递、邮政 EMS、京东快递、极兔速递、菜鸟直送等。

国际快递

DHL、FedEx、UPS、TNT、顺丰国际等。

使用方法

基本查询

node scripts/query.js <快递公司代码> <运单号>

自动识别

node scripts/query.js auto <运单号>

查看所有支持的快递公司

node scripts/query.js carriers

命令选项

快递公司代码

输出示例

文本格式

📦 顺丰速运 SF Express
运单号：SF1234567890123
状态：运输中

🚚 物流轨迹:
2024-03-14 08:30:00 已发出，下一站【上海转运中心】
   📍 北京转运中心
2024-03-13 22:15:00 已到达【北京转运中心】
   📍 北京转运中心

JSON 格式

node scripts/query.js sf SF1234567890123 --format json

配置

1. 复制配置模板

cp config.example.json config.json

2. 填写 API Key

在 Track123 注册账号获取 API Key。

{
  "track123": {
    "api_secret": "你的 API_Key"
  },
  "cache_duration": 3600000,
  "debug": false
}

3. 完整配置示例

# 复制配置模板
cp config.example.json config.json

# 编辑 config.json，填入你的 API Key
# 例如：
# {
#   "track123": {
#     "api_secret": "5d9e90a4acfb4c1abfba5cf75ee6dfdc"
#   },
#   "cache_duration": 3600000,
#   "debug": false
# }

# 验证配置
node scripts/query.js carriers

4. 安全提示

⚠️ API Key 是私密凭证，不应该公开分享！

• 不要将 config.json 提交到公共仓库
• 使用 .gitignore 排除 config.json
• 如果 API Key 泄露，请立即在 Track123 控制台重置

参考文档

• API 文档 - Track123 API 完整说明
• 使用示例 - 详细使用示例和最佳实践

注意事项

1. API 配额: 免费额度 100 次/天
2. 缓存机制: 相同运单号 1 小时内自动缓存
3. 错误处理: 查询失败会显示具体原因
4. 隐私保护: 不要将 config.json 提交到公共仓库

错误码

版本: 1.0.1
作者: josh