重點資料
- 每個號碼最低價
- $0.0018
- 認證
- API 金鑰
- 格式
- 經 HTTPS 傳送 JSON
- 請求限制
- 每分鐘 120 個請求
- 退款
- 與網站相同
REST 及 JSON
6 個請求涵蓋餘額、服務、價格、取得號碼、狀態和取消。
帳戶內的金鑰
在帳戶的「API 金鑰」頁面建立金鑰,並放在 Authorization 標頭發送。
價格與網站相同
號碼價格和 20 分鐘退款規則都與網站相同。
可以發送哪些請求?
路徑接在基本 URL 後面。每個請求都需要你的 API 金鑰。
| 方法及路徑 | 用途 |
|---|---|
GET/ | 你的美元餘額 |
GET/ | 所有服務,附最低價和國家數目 |
GET/ | 某項服務在各國家的單個號碼價格 |
POST/ | 取得指定服務和國家的號碼;價格從餘額扣除 |
GET/ | 號碼狀態及目前收到的所有驗證碼 |
POST/ | 在收到驗證碼前取消;款項退回餘額 |
API 應按甚麼次序呼叫?
- 1
取得號碼 以 service 和 country 呼叫 POST /numbers,保存 id 和號碼。
- 2
輸入號碼 把號碼輸入發送驗證碼的服務。
- 3
檢查驗證碼 每 5 秒呼叫 GET /numbers/{id},直至 codes 清單不是空的。
- 4
完成 使用驗證碼。如收到驗證碼前已不需要號碼,請取消。
基本 URL 是甚麼?
所有請求都發送到這個地址,並把金鑰放在 Authorization 標頭(Bearer)或 X-Api-Key 標頭:
https://tomnumber.com/api/v1Authorization: Bearer <API_KEY>請求欄位
| 欄位 | 用於 | 值 |
|---|---|---|
service | POST /numbers, GET /prices | /services 中的服務名稱,例如 telegram |
country | POST /numbers | 兩個字母的國家代碼,例如 gb |
回應欄位及狀態
| 值 | 意思 |
|---|---|
waiting | 號碼已開啟,暫未收到驗證碼 |
received | 已收到至少一個驗證碼;在 expires_at 前仍可收到更多 |
refunded | 20 分鐘內未收到驗證碼;款項已退回餘額 |
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"const api = (path, init = {}) => fetch("https://tomnumber.com/api/v1" + path, { ...init, headers: { Authorization: "Bearer " + process.env.API_KEY, "Content-Type": "application/json" }, }).then((r) => r.json()); const n = await api("/numbers", { method: "POST", body: JSON.stringify({ service: "telegram", country: "gb" }) });console.log(n.number); // enter this number in the app let codes = [];while (!codes.length) { await new Promise((r) => setTimeout(r, 5000)); const s = await api("/numbers/" + n.id); if (s.status === "refunded" || s.status === "canceled") break; codes = s.codes;}console.log(codes.map((c) => c.code));import os, time, requests API = "https://tomnumber.com/api/v1"H = {"Authorization": "Bearer " + os.environ["API_KEY"]} n = requests.post(API + "/numbers", json={"service": "telegram", "country": "gb"}, headers=H).json()print(n["number"]) # enter this number in the app while True: time.sleep(5) s = requests.get(API + "/numbers/" + n["id"], headers=H).json() if s["codes"] or s["status"] in ("refunded", "canceled"): breakprint([c["code"] for c in s["codes"]])短訊驗證 API 常見問題
甚麼是短訊驗證 API?
一種用你自己的程式代替網站,購買號碼和讀取驗證碼的方法。
使用 API 要額外收費嗎?
不用。號碼價格與網站相同,從同一個餘額扣款。
可以發送多少個請求?
每個金鑰每分鐘最多 120 個請求。每 5 秒查詢一次遠低於這個限制。
API 號碼也會退款嗎?
會,規則相同:20 分鐘內未收到驗證碼,款項就會退回你的餘額。
在哪裏建立金鑰?
在帳戶的「API 金鑰」。