跳到主要內容
tomnumber

短訊驗證 API

用你自己的軟件購買號碼和讀取驗證碼。API 使用你的餘額,價格和 20 分鐘退款規則都與網站相同。

API 金鑰在你的帳戶內建立。經 API 購買的號碼從同一個餘額扣款,價格與網站相同。

建立帳戶API 金鑰

每個號碼 $0.0018 起

重點資料

每個號碼最低價
$0.0018
認證
API 金鑰
格式
經 HTTPS 傳送 JSON
請求限制
每分鐘 120 個請求
退款
與網站相同

REST 及 JSON

6 個請求涵蓋餘額、服務、價格、取得號碼、狀態和取消。

帳戶內的金鑰

在帳戶的「API 金鑰」頁面建立金鑰,並放在 Authorization 標頭發送。

價格與網站相同

號碼價格和 20 分鐘退款規則都與網站相同。

可以發送哪些請求?

路徑接在基本 URL 後面。每個請求都需要你的 API 金鑰。

可以發送哪些請求?
方法及路徑用途
GET/balance你的美元餘額
GET/services所有服務,附最低價和國家數目
GET/prices?service=telegram某項服務在各國家的單個號碼價格
POST/numbers取得指定服務和國家的號碼;價格從餘額扣除
GET/numbers/{id}號碼狀態及目前收到的所有驗證碼
POST/numbers/{id}/cancel在收到驗證碼前取消;款項退回餘額

API 應按甚麼次序呼叫?

  1. 1

    取得號碼 以 service 和 country 呼叫 POST /numbers,保存 id 和號碼。

  2. 2

    輸入號碼 把號碼輸入發送驗證碼的服務。

  3. 3

    檢查驗證碼 每 5 秒呼叫 GET /numbers/{id},直至 codes 清單不是空的。

  4. 4

    完成 使用驗證碼。如收到驗證碼前已不需要號碼,請取消。

如何取得 API 金鑰?

登入後在帳戶打開「API 金鑰」。建立金鑰後請立即複製,金鑰只會顯示一次。建立新金鑰後,舊金鑰會停用。

API 金鑰

基本 URL 是甚麼?

所有請求都發送到這個地址,並把金鑰放在 Authorization 標頭(Bearer)或 X-Api-Key 標頭:

https://tomnumber.com/api/v1
Authorization: Bearer <API_KEY>

請求欄位

請求欄位
欄位用於值
servicePOST /numbers, GET /prices/services 中的服務名稱,例如 telegram
countryPOST /numbers兩個字母的國家代碼,例如 gb

回應欄位及狀態

回應欄位及狀態
值意思
waiting號碼已開啟,暫未收到驗證碼
received已收到至少一個驗證碼;在 expires_at 前仍可收到更多
refunded20 分鐘內未收到驗證碼;款項已退回餘額
canceled你在收到驗證碼前取消;款項已退回餘額

回應範例

{  "ok": true,  "id": "R8KQ2M7XWD4P",  "service": "telegram",  "country": "gb",  "number": "+44 7700 900412",  "price": "0.167",  "status": "received",  "expires_at": "2026-11-11T09:20:00.000Z",  "codes": [    { "code": "483920", "text": "Telegram code: 483920", "received_at": "2026-11-11T09:01:12.000Z" }  ]}

錯誤代碼

錯誤代碼
unauthorized缺少 API 金鑰或金鑰錯誤
rate_limited一分鐘內超過 120 個請求
bad_service服務名稱不存在
bad_country該服務不提供此國家
low_balance餘額低於價格
unavailable目前沒有可用號碼,沒有扣款
not_found你的帳戶沒有這個 id 的號碼
cannot_cancel已收到驗證碼或號碼已關閉

程式碼範例

# get a numbercurl -X POST https://tomnumber.com/api/v1/numbers \  -H "Authorization: Bearer $API_KEY" \  -H "Content-Type: application/json" \  -d '{"service":"telegram","country":"gb"}' # check for codescurl https://tomnumber.com/api/v1/numbers/R8KQ2M7XWD4P \  -H "Authorization: Bearer $API_KEY"

短訊驗證 API 常見問題

甚麼是短訊驗證 API?

一種用你自己的程式代替網站,購買號碼和讀取驗證碼的方法。

使用 API 要額外收費嗎?

不用。號碼價格與網站相同,從同一個餘額扣款。

可以發送多少個請求?

每個金鑰每分鐘最多 120 個請求。每 5 秒查詢一次遠低於這個限制。

API 號碼也會退款嗎?

會,規則相同:20 分鐘內未收到驗證碼,款項就會退回你的餘額。

在哪裏建立金鑰?

在帳戶的「API 金鑰」。

其他服務的虛擬號碼