快递查询 (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

命令选项

快递公司代码

输出示例

文本格式

node scripts/query.js sf SF1234567890123

输出：

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

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

JSON 格式

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

输出：

{
  "tracking_number": "SF1234567890123",
  "carrier": {
    "code": "sf",
    "name": "顺丰速运",
    "nameEn": "SF Express"
  },
  "status": "002",
  "status_description": "运输中",
  "origin": "北京市朝阳区",
  "destination": "上海市浦东新区",
  "weight": null,
  "signed_by": null,
  "tracks": [
    {
      "checkpoint_time": "2024-03-14 08:30:00",
      "tracking_detail": "已发出，下一站【上海转运中心]",
      "location": "北京转运中心"
    },
    {
      "checkpoint_time": "2024-03-13 22:15:00",
      "tracking_detail": "已到达【北京转运中心]",
      "location": "北京转运中心"
    }
  ]
}

Compact 格式（简洁模式）

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

输出：

📦 SF1234567890123 (顺丰速运) - 运输中
最新：2024-03-14 08:30:00 已发出，下一站【上海转运中心】

配置

1. 复制配置模板

cp config.example.json config.json

2. 填写 API Key

在 Track123 注册账号获取 API Key。

⚠️ 重要：下面的示例值（your_api_key_here）需要替换为你真实的 API Key！

{
  "track123": {
    "app_key": "your_api_key_here",
    "api_secret": "your_api_key_here"
  },
  "cache_duration": 3600000,
  "debug": false
}

3. 完整配置示例

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

# 编辑 config.json，填入你的 API Key
# 例如（❌ 下面的值只是示例格式，不是真实可用的 API Key）：
# {
#   "track123": {
#     "app_key": "your_real_api_key",
#     "api_secret": "your_real_api_key"
#   },
#   "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