短信验证码 API 快速入门

第一种是 handler_api 协议。它是为 SMS-Activate 编写的工具所使用的请求格式。如果你的工具用的是这个协议，你只需要换掉 API 地址和密钥，代码保持不变。

第二种是 JSON API v2。它的请求和响应都是普通的 JSON，带有 webhooks，状态也很清晰。凡是从零开始写的东西，都用它。

每个请求都发往同一个地址，带上你的密钥和一个操作名称。地址在文档里。主要的操作就是你的工具已经在发送的那些。

• getNumber：为某个服务和某个国家购买号码。
• getStatus：查询验证码是否已经到达。
• setStatus：更改一次激活的状态，例如取消它。
• getBalance：读取你的钱包余额。

你的密钥在账号的开发者页面上。每个请求都要在 Authorization 请求头里把它作为 Bearer 令牌发送。

从 GET /catalog 开始。它返回你此刻可以购买的报价，附带你的价格，并且可以按国家和服务筛选。GET /balance 返回以美元计的钱包余额。钱包充值 3 美元起。

整个流程只有几次调用。

一次激活有四种状态之一：waiting、completed、expired 或 cancelled。只有在它仍处于 waiting 状态时才能取消。

默认情况下，一次激活会等待验证码十分钟，然后过期。你可以在购买调用里设置更短或更长的等待时间，从两分钟到二十分钟。GET /activations 列出你的激活，最新的排在前面。

• POST /activations 带上服务和国家，购买一个号码。
• GET /activations/:id 返回这次激活。轮询它，直到验证码出现。
• 或者在购买调用里传入一个 webhook 地址，验证码到达时我们会调用你的服务器。
• POST /activations/:id/cancel 取消一次处于 waiting 状态的激活，并全额退款。

网络会出故障，一次超时的购买调用可能其实已经成功。请在 POST /activations 上发送 Idempotency-Key 请求头。如果你用同一个键重试，拿回来的是第一次的激活，而不是第二笔购买。

每个接口都有自己的速率限制，每分钟 30 到 120 次请求，文档里逐一列出。如果你使用 webhook，就几乎不需要轮询。Webhooks 带有签名，所以在信任它之前请先校验签名。

每个号码都是移动网络上的一张真实 SIM 卡，只出售给一个服务的一次激活。它只接收 SMS，不接电话。我们不承诺应用会接受某个号码或发送验证码，所以你的代码必须预料到有些激活会在没有验证码的情况下结束。

只有验证码送达才收费。没有收到时，取消激活或等它过期，全款会自动退回你的钱包。请把它当作一个普通的分支来处理，而不是当作错误。

早期的大多数问题都是因为跳过了这几步。

• 先手动运行一次激活，并读一遍响应里的每个字段。
• 故意让一次激活过期，看着余额退回来。
• 把你的国家代码和服务代码与文档逐一对照。代码错了，可能返回一个你并不想要的号码。
• 把密钥放在你的服务器上，绝不要放在应用或网页里。