SMSPVA / DOCUMENTATION
激活流程
选择号码、获取结果并管理订单。
SMSPVA API
1. 选择代码及消息类型
查询国家和服务、运营商、余量及价格。检查权限：voice=0 短信，1 来电显示，2 语音。
价格和余量只是快照，不构成号码预留。外部供应商运营商的 9999 表示准确数量未知。
2. 获取号码
使用获取号码申请号码；需要指定运营商时，使用按运营商获取号码。
保存 data.orderId，之后接收消息和管理订单都会用到。响应中的 data.orderExpireIn 是订单到期前剩余的秒数，用它计算一次到期时间：
const expiresAt = Date.now() + numberResult.data.orderExpireIn * 1000;之后查询消息时，一直使用这个到期时间。订单有效期以 API 返回值为准，不要固定设为十分钟，也不要在每次查询时重新计时。
如果申请请求超时，先检查当前订单再申请新号码：之前的请求可能已经创建订单。文档未提供用于避免重复请求的幂等键。
3. 等待结果
将 orderId 传给接收短信。语音和来电显示也使用此接口，无需再传 voice。
| 响应 | 操作 |
|---|---|
| 200 | 使用 data.sms，并停止本次轮询 |
| 202 + SMS_NOT_YET_RECEIVED | 等待后在有效期内继续查询 |
| 410 + ORDER_CLOSED | 订单已关闭，停止轮询 |
| 其他错误 | 根据接口文档处理 |
等待响应也包含 error。先判断是否为 SMS_NOT_YET_RECEIVED，再处理其他错误。读取新收到的短信可能触发计费，调用时请留意。
本例采用五秒间隔，这是客户端示例设置，不是新增 API 限制。遵循返回的限流错误和订单期限。网络或非 JSON 错误会停止循环，不自动重试。
// Node.js 22.16+. No automatic retries after transport errors or terminal responses.
export async function waitForSms({ apiKey, orderId, expiresAt, intervalMs = 5000 }, {
fetchImpl = fetch,
now = Date.now,
sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
baseUrl = 'https://api.smspva.com',
} = {}) {
if (!apiKey || !/^\d+$/.test(String(orderId))) throw new Error('Set your API key and order ID');
if (!Number.isFinite(expiresAt) || expiresAt <= now()) throw new Error('Order deadline has passed');
if (!Number.isFinite(intervalMs) || intervalMs < 5000) throw new Error('Use a polling interval of at least 5000 ms in this example');
while (now() < expiresAt) {
const remaining = expiresAt - now();
const response = await fetchImpl(`${baseUrl}/activation/sms/${encodeURIComponent(orderId)}`, {
headers: { apikey: apiKey },
signal: AbortSignal.timeout(Math.max(1, Math.floor(Math.min(30_000, remaining)))),
});
const result = await response.json();
if (response.status === 202 && result.statusCode === 202 && result.error?.type === 'SMS_NOT_YET_RECEIVED') {
const delay = Math.min(intervalMs, expiresAt - now());
if (delay <= 0) break;
await sleep(delay);
continue;
}
if (response.status !== 200 || result.error || result.statusCode !== 200) {
throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
}
return result.data;
}
throw new Error('No result before the order deadline');
}将函数保存为 poll-sms.mjs，并使用收到号码时计算的截止时间：
import { waitForSms } from './poll-sms.mjs';
const data = await waitForSms({ apiKey, orderId, expiresAt });
console.log(data.sms);4. 明确管理订单
- 清除短信：清除当前短信以接收下一条。保留返回的
orderExpireIn。404 / NO_SMS_TO_CLEAN 不代表清除成功。 - 停止接收：停止短信接收。
- 取消订单：取消订单。
- 屏蔽号码：标记号码不可用。
- 号码状态：查询此前在同一服务用过的号码。
这些操作各有用途，不能互换。示例不会在超时后自动调用它们，请先阅读对应响应说明。