SMS Activate App REST API 让您的代码为自己的应用、账户和测试购买私人号码、触发验证并读取短信验证码。
本指南涵盖完整流程:选择号码、安全购买、读取 OTP(一次性密码)验证码,以及用完后释放号码。
何时适合自动化
自动化适合您自己拥有且需要重复执行的工作。常见场景有三种:
- 对您自己应用中短信步骤的端到端测试:注册、登录、密码重置和 2FA(双因素认证)。
- 为您自己的服务账户和内部工具保持 2FA 正常运行。
- 您运营的产品中的验证步骤。
每个号码都是私人虚拟号码。它是运营商号段中的真实手机号或本地号码,具体取决于国家。您的账户持有该号码,期限为 28 天。同一号码可以接收后续验证码,因此在有效期内重新验证和账户恢复都能正常使用。
有两项限制。号码一经发放即为最终状态,不可退款。是否接受该号码由您验证的平台决定,而非我们。
大多数验证码在平台发送后几分钟内到达。我们尚未公布送达率,因此请在围绕某个号码构建流程之前,先用目标平台测试该号码。
API 接收短信,不发送短信。
开始之前
- 在注册页面创建免费账户。
- 为账户充值。
- 在账户面板的 API 密钥选项卡中或在 Telegram 机器人中创建个人 API 密钥。
每次发送请求时都携带该密钥,包括目录请求:
该密钥会消耗您的余额。请将其保存在服务端,存放在密钥管理服务或 CI 密钥中。切勿将其放入客户端代码或提交到代码仓库。
参考信息:
- 基础 URL:https://api.sms-activate.app/v1/public
- 金额以美元美分为单位的整数表示。balanceCents: 2000 表示 $20.00。
- 机器可读规范:OpenAPI 文件(OpenAPI 3.1)。
- 人工可读文档:API 文档。
- 为 LLM 代理准备的技能文件:代理技能。
- 限制:每个账户每分钟至少可发送 120 个请求,每分钟最多购买 30 次。超出后返回 rate_limited,并附带 Retry-After 响应头。
验证流程
- 调用 GET /countries。该接口返回每个国家的可用性和价格范围。
- 调用 GET /numbers/search?country=US&limit=1 选择一个可用号码。每个结果都包含 phoneNumber 和您的价格 priceCents。
- 使用 POST /numbers 购买号码,请求体为 {"phone": "<phoneNumber>", "country": "US"}。添加 Idempotency-Key: <uuid> 请求头,确保重试不会重复扣费。购买成功返回 201,包含 number、chargedCents 和 balanceAfterCents。还有两个可选字段:autoRenew(默认 true)和 note。
- 在您要测试的流程中输入该号码并触发短信发送。
- 读取验证码。每 5 到 15 秒轮询该号码的 GET /numbers/{id}/sms,或轮询所有号码的 GET /sms,并设置超时。每条短信包含 id、numberId、from、to、body 和 receivedAt;请从 body 中提取验证码。消息列表使用游标分页,字段为 cursor、limit 和 nextCursor。
- 结束。发送 PATCH /numbers/{id},请求体为 {"autoRenew": false},停止续期;或发送 DELETE /numbers/{id} 释放号码。对于每天运行的测试套件,保持一个号码持续续期通常比每次运行都购买新号码更简单。
curl 示例
第一个调用查找号码。第二个购买该号码。第三个读取收到的短信。
将 +15551234567 替换为第一个调用返回的号码。如果在网络错误后重试购买,请复用相同的 Idempotency-Key 值,而不是生成新的。
Python 示例
下面这个函数在您已有的号码上等待验证码。它使用 requests 库,并从环境变量中读取密钥。
如果同一号码上之前收到的短信也可能匹配,请将 receivedAt 与您的测试触发消息的时间做比较,只取更新的那条。
用 Webhook 替代轮询
发送 PATCH /numbers/{id},请求体为 {"forwardWebhookUrl": "https://your-app.example.com/sms"},此后该号码收到的每条短信和每个来电都会在到达时推送到您的服务器。系统会先检查该地址:它必须以 2xx 状态码响应一个测试 POST。
每个请求都带有 x-vpn-event、x-vpn-timestamp 和 x-vpn-signature。签名是用您的 Webhook 密钥对 v1.<timestamp>.<raw body> 计算的 HMAC-SHA256。请基于原始字节验证签名,并拒绝时间戳偏差超过五分钟的请求。
对于只运行一次的测试,轮询更简单。Webhook 适合长期运行的服务,在验证码到达时即时处理。
把错误当作回答来处理
每个错误的结构都相同:
请根据 error 代码分支处理,不要根据 HTTP 状态码。同一个状态码可能对应多种拒绝原因,仅凭状态码无法判断具体发生了什么。部分拒绝会附带一个 details 对象,例如 insufficient_balance 会包含 requiredCents 和 availableCents。
需要处理的错误代码:
- insufficient_balance:余额不足以完成购买。停止操作并充值。
- no_numbers:当前没有可用的匹配号码。换一个号码或国家。
- number_unavailable:该号码已售出或不再出售。重新搜索。
- validation_failed:请求体或参数有误,或者购买请求缺少 Idempotency-Key。修正输入。
- idempotent_replay:带有此 Idempotency-Key 的请求使用了不同的请求体,或仍在处理中。不要将其视为新的购买。
- rate_limited:请求过多。请按 Retry-After 响应头给出的时间等待。
- priceexceeded 和 providerfailure:读取 message,展示给用户,并停止运行。出现 provider_failure 后,请先检查您的号码再重新购买。
这些错误都不是可以盲目重试的缺陷。请将错误展示给运行代码的人,或者停止运行。在日志中保留 reqId,支持团队用它来定位您的请求。
在 CI 测试套件中
- 将短信测试作为独立的串行任务运行,避免两个测试读取同一条验证码。
- 将 API 密钥存储为 CI 的 secret。
- 通过号码和测试开始的时间,将每条验证码与对应的测试匹配。
- 设置超时,并在失败时输出明确的信息,注明号码和当前步骤。
- 保留一个可续期的号码用于重复运行,而不是每次都购买新号码。
相关视频
以下是第三方视频,讲解本指南用到的技术。它们教授通用技术,不涉及我们的服务。
- Python Requests Tutorial: Request Web Pages, Download Images, POST Data, Read JSON, and More(Corey Schafer):从 Python 发送 GET 和 POST 请求,携带请求头,并读取 JSON 响应。
- Server-Sent Events Crash Course(Hussein Nasser):Server-Sent Events 流的工作原理,以及它在什么场景下优于轮询。
- Polling vs Webhooks | System Design Tradeoffs(SoftwareDude):定时请求与接收推送之间的成本与收益对比。
- Idempotency in APIs Explained | Why It Matters + Code Example(Arkynate):幂等键和安全重试,附代码示例。
- Playwright Tutorial: Re-use state & Re-use Authentication(CommitQuality):在测试套件中登录一次并复用已登录状态,使短信步骤只在必要时运行。
下一步
- 在 API 文档中阅读完整的接口参考。
- 从 OpenAPI 文件将规范导入您的工具。
- 将现成的代理技能交给 LLM 代理。
- 在定价页面查看当前价格。
- 如果您计划基于此 API 构建产品,请阅读如何用虚拟号码赚取收入这篇概览。