號碼狀態查詢 API
透過本介面，您可以對全球範圍內的手機號碼進行狀態查詢，取得號碼的有效性、歸屬營運商、漫遊、轉網等詳細資訊。該 API 提供兩種服務級別：Basic 和 Premium。
-
Basic：提供基礎資料（如國家代碼、原始歸屬營運商、號碼格式驗證）。需要注意的是，Basic 僅返回號碼在未轉網 (MNP) 之前所屬的原始營運商資訊；如果您需要取得號碼被轉網後的現網營運商資訊，請升級到 Premium。
-
Premium：在 Basic 基礎上，可進一步取得號碼在當前網路狀態下的營運商、是否可達、是否漫遊、是否轉網等資訊；但這一部份資料依賴目標國家/地區電信法規和用戶隱私保護政策，無法保證所有國家和所有營運商都能完整提供。
1. 呼叫方式
呼叫方式
- HTTP Method：
GET - 請求地址：
https://api.paasoo.com.tw/lookup
2. 請求範例
Basic:
cURL
curl -X GET "https://api.paasoo.com.tw/lookup?key=API_KEY&secret=API_SECRET&number=886912345678"
Premium:
cURL
curl -X GET "https://api.paasoo.com.tw/lookup?key=API_KEY&secret=API_SECRET&number=886912345678&service=premium"
說明
認證參數：透過 key 和 secret 進行身分驗證。
預設服務等級：若未指定 service，則預設為 basic。
3. 請求參數說明
| 參數 | 類型 | 必填 | 描述 | 範例 |
|---|---|---|---|---|
| key | string | 是 | API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。 | Abcdefgh |
| secret | string | 是 | API Secret（字母或數字構成，共 8 位），與 key 配合使用以進行身分驗證。可在 PaaSoo 用戶端後台取得。 | Abc123EF |
| number | string | 是 | 待查詢手機號碼。 建議使用完整國際格式（如 886912345678）。 無需在區號或號碼前補充其它前導字元。 | 886912345678 |
| service | string | 否 | 指定查詢服務級別: basic 或 premium。 不傳時預設為 basic。 | premium |
4. 回應說明
Basic: 僅提供號碼最初（未轉網前）的營運商資訊，無法返回即時轉網資訊。
Premium: 基於最大的努力（best effort）為您提供當前營運商資訊、漫遊、轉網等更多狀態，但並非所有地區均可查詢到完整或最新資料，受限於各地電信監管及隱私保護要求。
4.1 回應參數說明
| 參數 | 類型 | 服務 | 描述 |
|---|---|---|---|
| requestId | string | basic / premium | 查詢請求的唯一 ID，可用於日誌追蹤。 |
| number | string | basic / premium | 原始傳入的待查詢電話號碼。 |
| format | integer | basic / premium | 號碼格式的有效性：
|
| errorCode | string | basic / premium | 請求的錯誤編碼：
|
| errorDesc | string | basic / premium | 與 errorCode 對應的描述資訊。 |
| cc | string | basic / premium | 待查詢號碼對應的國家或地區代碼，如 886。 |
| countryIso | string | basic / premium | 國家或地區名稱縮寫，如 TW。 |
| operator | string | basic / premium | 號碼歸屬的營運商名稱。在 Basic 版本，此處僅返回號碼在原始網路（未轉網）時的營運商資訊；如要取得現網營運商資訊，請使用 Premium。 |
| mccmnc | string | premium | 營運商網路代碼 (MCC+MNC)，如 46692；若無法查詢到，不一定返回。 |
| reachable | string | premium | 號碼可達性：
|
| ported | string | premium | 是否轉網：
|
| portedFrom | string | premium | 轉網前的網路名稱和網路代碼資訊，例如 Chunghwa Telecom 46692； 若無法取得或未轉網則為空或 unknown。 |
| imsi | string | premium | IMSI 編碼資訊；若無法取得，則返回 unknown。 |
4.2 Basic (預設) 回應範例
{
"requestId": "900249-0c1a64-d000",
"number": "886912345678",
"format": 0,
"errorCode": "00",
"errorDesc": "Successful",
"cc": "886",
"countryIso": "TW"
}
4.3 Premium 回應範例
{
"requestId": "900249-0c0aba-2000",
"number": "886912345678",
"format": 1,
"errorCode": "00",
"errorDesc": "Successful",
"cc": "886",
"countryIso": "TW",
"mccmnc": "46692",
"operator": "Chunghwa Telecom",
"reachable": "reachable",
"ported": "not ported",
"portedFrom": "",
"imsi": "unknown"
}
5. 錯誤碼與常見問題
- 00 - Successful：呼叫成功。
- 01 - Insufficient balance：當前剩餘餘額不足，需要儲值或升級帳戶。
- 02 - Wrong credentials：帳號或密碼錯誤，請檢查
key、secret。 - 03 - Missing parameters：參數缺失或不合法，請檢查請求範例。
- 07 - IP limit：您的請求來源 IP 不在白名單中。
- 08 - No allow hlr：當前用戶帳號未訂閱 Premium 版本的 HLR 查詢服務。
- 13 - Daliy quota exceeded：基礎版當日可查詢次數用盡。
- 99 - Other error：系統繁忙或其他未知錯誤。
6. 最佳實踐與注意事項
- 服務選擇：
- Basic：僅能取得號碼原始營運商資訊。若您對轉網後營運商等動態資訊有需求，請使用 Premium。
- Premium：基於最大的努力 (best effort) 取得當前營運商、漫遊、轉網等資訊；該功能在部分國家或地區可能受限於當地電信監管與用戶隱私保護規定，導致部分資訊無法取得。
- 號碼格式：建議傳入完整國際格式號碼，去掉任何前置的 + 或 0 等前導符。
- 安全性：強烈建議使用 HTTPS 協定，結合 IP 白名單或其他技術手段來保護 API Key 和 Secret。
- 帳戶餘額：確保在呼叫前有足夠餘額，如需更高配額或更高級別服務，請聯絡 PaaSoo 取得支援。
- 請求頻率：若頻繁呼叫，請控制併發或設定合理延遲，以避免超出服務限額。
- 傳輸延遲：Premium 查詢可提供即時的號碼狀態，但仍應注意網路時延及目標營運商聯調時效。
技術支援
如在 API 對接過程中遇到任何技術問題或業務疑問，歡迎隨時聯絡我們的開發者支援團隊：support@paasoo.com。我們將竭誠為您提供技術協助。