Taiwan postal tracking

台灣中華郵政掛號追蹤

查詢中華郵政掛號郵件的投遞狀態。支援國內各類掛號郵件（掛號信、雙掛號、包裹等）。

依賴

• Python 3.10+
• httpx 套件（pip install httpx）

使用方式

方式一：使用隨附腳本

附帶的 scripts/track_postal.py 腳本處理驗證碼下載與查詢提交：

# 步驟 1：取得驗證碼
python <skill-path>/scripts/track_postal.py captcha
# 輸出：驗證碼圖片路徑和 UUID

# 步驟 2：用 Read tool 辨識驗證碼圖片（4 位數字）

# 步驟 3：送出查詢
python <skill-path>/scripts/track_postal.py query --uuid <UUID> --code <驗證碼> <追蹤碼1> [追蹤碼2] ...
# 輸出：JSON 格式的追蹤結果

方式二：Agent 自動化流程

當 AI Agent 需要查詢郵局追蹤時，按以下步驟操作：

步驟 1：取得並辨識驗證碼

python <skill-path>/scripts/track_postal.py captcha

腳本會輸出：

{"captcha_image": "/tmp/postal-captcha.jpg", "uuid": "xxx-xxx-xxx"}

步驟 2：用 Read tool 辨識驗證碼

讀取 /tmp/postal-captcha.jpg，辨識 4 位數字。驗證碼特徵：

• 固定 4 位純數字（0-9）
• 有網格線和噪點干擾
• 數字通常較大且清晰

步驟 3：立即送出查詢（驗證碼約 60 秒過期）

python <skill-path>/scripts/track_postal.py query --uuid <UUID> --code <4位數字> <追蹤碼>

輸出 JSON：

[
  {
    "mail_no": "07896140245117",
    "events": [
      {
        "datetime": "2026/03/27 14:34",
        "status": "投遞成功",
        "branch_name": "太平宜欣郵局郵務股",
        "branch_code": "400601",
        "event_code": "I4"
      }
    ],
    "error": ""
  }
]

重要：步驟 2 和步驟 3 之間不要做其他事，驗證碼有時效限制。

一次查詢多筆

一次最多可查 5 筆追蹤碼（共用同一個驗證碼）：

python <skill-path>/scripts/track_postal.py query --uuid <UUID> --code <驗證碼> 追蹤碼1 追蹤碼2 追蹤碼3

追蹤碼格式

中華郵政的掛號追蹤碼常見格式：

• 國內掛號：14 位數字（如 07896140245117）
• 國內包裹：13 位（如 06450954000017）
• 國際郵件：13 碼英數混合（如 RR123456789TW）

常見投遞狀態

事件碼	狀態	說明
I1	收寄	郵局收件
I2	到達處理中心	轉運中
I3	離開處理中心	已發送
I4	投遞成功	已送達
I5	無法投遞	投遞失敗（招領/退回）

錯誤處理

• 驗證碼錯誤或已過期：重新取得驗證碼再試
• 查無此郵件：確認追蹤碼是否正確
• 網路逾時：中華郵政伺服器偶爾較慢，可重試

API 技術細節

此 skill 使用中華郵政「郵件查詢」系統的 eSoaf 框架 API：

• 驗證碼端點：GET https://postserv.post.gov.tw/pstmail/jcaptcha?uuid={uuid}
• 查詢端點：POST https://postserv.post.gov.tw/pstmail/EsoafDispatcher
• 請求格式：eSoaf JSON（TxnCode=EB500100, BizCode=query）
• SSL 驗證：中華郵政伺服器憑證可能有問題，腳本使用 verify=False