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: bash

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

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

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

Usage#

bash

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

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

Examples#

bash

# 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)#

Prefix/PatternCarrierCodeSF顺丰速运shunfeng``YT圆通速递yuantong``JT / J0极兔速递jitu``JD京东快递jd``CN菜鸟速递cainiao``DPK德邦快递debangkuaidi``KYE跨越速运kuayue``AN安能物流annengwuliu``1ZUPSups``78/73/72/21/68 + digits中通快递zhongtong``10/11/12/13/19/46 + 13 digits韵达快递yunda``77/88/66/55/44 + 13-15 digits申通快递shentong``E + letter + 9 digits + 2 lettersEMSems

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#

CodeMeaningAction400Incomplete data / wrong carrierCheck carrier code408Phone verification failedSF/ZTO require phone number500No tracking info foundVerify tracking number and carrier503Signature verification failedCheck API Key and Customer ID601API Key expired / no balanceRecharge account

Agent Integration#

When a user provides a tracking number, run:

bash

EXPRESS_TRACKER_KEY="$KEY" EXPRESS_TRACKER_CUSTOMER="$CUSTOMER" scripts/track.sh <number>

Parse the output and present the tracking timeline to the user. If carrier detection fails, ask the user which carrier it is.