Express Tracker（快递物流查询）

Track packages from 200+ carriers (Chinese domestic + international) via Kuaidi100 API.

Setup (Required)

Users must obtain their own Kuaidi100 API credentials:

1. Register at Kuaidi100 Open Platform

   • 注册企业版账号（个人也可注册）
   • Free tier: 100 queries/day after verification

2. Get credentials from the Kuaidi100 Dashboard:

   • 授权 Key（API Key）: Found in 授权信息 → 授权key
   • Customer ID: Found in 授权信息 → customer

3. Set environment variables:

   export EXPRESS_TRACKER_KEY="your_api_key_here"
   export EXPRESS_TRACKER_CUSTOMER="your_customer_id_here"
   

   For persistent config, add to ~/.bashrc or ~/.zshrc:

   echo 'export EXPRESS_TRACKER_KEY="your_key"' >> ~/.zshrc
   echo 'export EXPRESS_TRACKER_CUSTOMER="your_customer"' >> ~/.zshrc
   

Usage

# Auto-detect carrier and query
scripts/track.sh <tracking_number>

# Specify carrier manually
scripts/track.sh <tracking_number> <carrier_code>

Examples

# Auto-detect (recommended)
scripts/track.sh 770308811947591

# Specify carrier explicitly
scripts/track.sh SF1234567890 shunfeng

How It Works

1. Carrier auto-detection: Local rule-based matching by tracking number prefix/length/format
2. API query: Sends signed request to Kuaidi100 poll API with resultv2=4 for advanced status
3. Output: Formatted timeline with full tracking history (newest first)

Supported Carriers (Auto-Detection)

If auto-detection fails, specify the carrier code manually as the second argument.

Full carrier code list: Kuaidi100 Carrier Codes

Dependencies

• curl — HTTP requests
• jq — JSON parsing (install: brew install jq / apt install jq)
• openssl or md5sum or md5 — MD5 signature (at least one required)

Error Codes

Agent Integration

When a user provides a tracking number, run: