短信网关 API：在你自己的号码上接收验证码

认证

在控制台的 REST API 下创建密钥。密钥以 bsk_live_ 开头且只显示一次，请作为机密保存，例如存为 BUSYSMS_API_KEY。每个请求都要在以下任一请求头中携带它：

Authorization: Bearer bsk_live_xxxxxxxx
# or
X-API-Key: bsk_live_xxxxxxxx

密钥属于某个人，只能看到这个人的手机，以及共享给他的号码。在控制台创建的密钥可以读取验证码、列出你的手机和号码、读取账户状态，以及唤醒已暂停的手机；它不能删除设备或管理你的账户，所以密钥泄露也无法改变你的账单。尽管如此，仍请把密钥留在服务器端：任何持有密钥的人都能读取你的验证码。

接口

基础 URL 为 https://busysms.net/api/v1。请求都是普通的 GET，响应为 JSON。

• GET /codes：你所有号码中最新的验证码。带上 timeoutMs 时会等待下一条，最长 90 秒。过滤参数：service、phone、deviceId。
• GET /devices：你的网关手机，包含 id、名称、号码、平台，以及在线、已验证和暂停状态，另外还有共享给你的号码。
• GET /numbers：仅列出你的号码，每个都带有 canReceive，无法接收时还会附上 reason：unverified、verification_pending、inactive、gateway_off 或 phone_unreachable。
• GET /devices/:id/messages：某台手机最近捕获的短信，按时间倒序排列。支持 service、limit（默认 50，最多 200）和 since。
• GET /account：你的账户及其试用和订阅状态。

等待验证码：curl、Node.js 和 Python

大多数集成最需要的调用，是在触发短信的操作之后立即发起长轮询。先开始等待，再触发登录，一旦匹配的验证码到达，请求就会返回。

curl -s -H "Authorization: Bearer $BUSYSMS_API_KEY" \
  "https://busysms.net/api/v1/codes?service=exampleapp&timeoutMs=60000"

const params = new URLSearchParams({ service: "exampleapp", timeoutMs: "60000" });
const res = await fetch(`https://busysms.net/api/v1/codes?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BUSYSMS_API_KEY}` },
});

if (res.status === 402) throw new Error("Trial over or subscription inactive");
if (!res.ok) throw new Error(`BusySMS ${res.status}: ${await res.text()}`);

const { code, message } = await res.json();
if (code) console.log(`${code} from ${message.sender}`);
else console.log("No new code within 60 seconds");

import os
import requests

r = requests.get(
    "https://busysms.net/api/v1/codes",
    params={"service": "exampleapp", "timeoutMs": 60000},
    headers={"Authorization": f"Bearer {os.environ['BUSYSMS_API_KEY']}"},
    timeout=75,
)
if r.status_code == 402:
    raise RuntimeError("Trial over or subscription inactive")
r.raise_for_status()

data = r.json()
if data["code"]:
    print(data["code"], "from", data["message"]["sender"])
else:
    print("No new code within 60 seconds")

顺序没有你担心的那么要紧：在请求开始前约一秒内到达的验证码仍算作新的，更早的则不算。在测试中，先发起请求，再触发短信；OTP 自动化指南演示了如何在 Playwright、Selenium 和 Cypress 中这样做。

返回内容

每个 /codes 响应的结构都相同（此处 message 对象有删减）：

{
  "code": "482913",
  "message": {
    "otpCode": "482913",
    "phone": "+447700900123",
    "sender": "ExampleApp",
    "service": "exampleapp",
    "serviceLabel": "ExampleApp",
    "bodyPreview": "Your ExampleApp verification code is 482913",
    "receivedAt": 1792674000000,
    "deviceName": "Test phone"
  }
}

如果在时限内没有新验证码到达，code 为 null：等待期间，API 绝不会退回到旧的验证码。receivedAt 是以毫秒为单位的 Unix 时间戳。service 是 BusySMS 为每条短信分配的简短 id：已知品牌如 google、telegram 或 microsoft，否则为发件人名称的 slug。把它作为 service= 传入，就只等待该发件人的验证码。

错误及处理方式

• 401：密钥缺失、格式错误或已被吊销。已吊销的密钥会返回 key_revoked。
• 402 payment_required：试用已结束且没有有效订阅。读取验证码会停止，但 /devices 仍会响应，方便你查看问题所在，响应体中还带有 billingUrl。
• 403：设备属于其他账户，或密钥没有该路由的权限范围（insufficient_scope）。
• 404：设备不存在。
• 409 number_unverified：该手机的号码尚未验证，因此无法读取其短信。
• 429：触发了频率限制。请等待 retryAfterMs 后再重试。

限制与最佳实践

• 单次等待最长 90 秒。如果验证码可能需要更久，请用新的超时时间再次调用，而不是一直保持同一个请求。
• 有多个号码时请加过滤条件：用 phone= 指定接收号码，或用 deviceId= 指定你的某台手机，以免返回本属于另一次登录的验证码。
• 如果等待开始时你的手机都没有在捕获，BusySMS 会向手机发送通知，请求重新开启网关。它绝不会远程开启捕获；必须有人亲手轻点。
• 捕获的短信最多保留 7 天，之后删除。
• 读取验证码需要有效的试用或订阅：7 天免费试用结束后，每个已验证号码每月 $5。不按请求次数收费。

REST API 之外

同样的验证码，AI 智能体可以通过 BusySMS MCP 服务器获取（参见面向 AI 智能体的短信验证码），人则可以通过 Chrome 扩展获取，扩展会替你把验证码填进网站。

共享给你的号码也包括在内。当同事共享某个号码的验证码后，/codes 会把它们和你自己的验证码一起返回，用 phone= 即可单独筛选出该号码。

常见问题

常见问题解答