使用方法

基本查询

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

自动识别

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

查看所有支持的快递公司

node scripts/query.js carriers

命令选项

选项	说明	默认值
`--format <text	json	compact>`
`--cache`	使用缓存 (1 小时内)	`true`
`--no-cache`	强制刷新缓存	`false`
`--lang <zh	en	ru>`
`--debug`	开启调试模式	`false`

快递公司代码

代码	快递公司	代码	快递公司
`sf`	顺丰速运	`yto`	圆通速递
`zto`	中通快递	`yunda`	韵达速递
`sto`	申通快递	`ems`	邮政 EMS
`jd`	京东快递	`jt`	极兔速递
`dhl`	DHL	`fedex`	FedEx
`ups`	UPS	`tnt`	TNT
`auto`	自动识别	`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 完整说明
使用示例 - 详细使用示例和最佳实践

注意事项

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

错误码

错误码	说明
`400`	请求参数错误
`401`	API Key 无效
`429`	请求过于频繁
`500`	服务器错误

版本: 1.0.1
作者: josh

kuaidi-query

快递查询 (kuaidi-query)

快速开始

支持的快递公司

国内快递