# Taiwan Postal Tracking

> 查詢台灣中華郵政（Chunghwa Post）掛號郵件投遞狀態。透過圖形驗證碼辨識自動查詢郵件追蹤資訊，包含投遞狀態、處理局所、時間等。當使用者提到掛號查詢、郵局追蹤、郵件投遞狀態、掛號信、包裹追蹤碼、中華郵政、郵局包裹，或任何與台灣郵政追蹤相關的查詢時，都應使用此 skill。即使使用者只是說「查掛號」、「這個追蹤碼的狀態」、「郵件到了嗎」也應觸發。

- Skill: `arova-ai/taiwan-postal-tracking` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add arova-ai/taiwan-postal-tracking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arova-ai/taiwan-postal-tracking/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: arova-ai (https://skillmd.com/u/arova-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arova-ai/taiwan-postal-tracking

---


# 台灣中華郵政掛號追蹤

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

## 依賴

- Python 3.10+
- `httpx` 套件（`pip install httpx`）

## 使用方式

### 方式一：使用隨附腳本

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

```bash
# 步驟 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：取得並辨識驗證碼**

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

腳本會輸出：
```json
{"captcha_image": "/tmp/postal-captcha.jpg", "uuid": "xxx-xxx-xxx"}
```

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

讀取 `/tmp/postal-captcha.jpg`，辨識 4 位數字。驗證碼特徵：
- 固定 4 位純數字（0-9）
- 有網格線和噪點干擾
- 數字通常較大且清晰

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

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

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

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

### 一次查詢多筆

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

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