Developer API

开放接口文档

开放接口统一使用 API Key 鉴权。请求头支持 Authorization: Bearer <api_key> 或 X-API-Key。

状态码

401 无 API Key，403 Key 已禁用，409 已收到验证码不可取消。

兑换卡密

POST /api/open/redeem

请求示例

{
  "code": "SMS-XXXX-XXXX-XXXX"
}

响应示例

{
  "ok": true,
  "redemptionId": 123,
  "phoneNumber": "+15551234567",
  "maxCodes": 3,
  "receivedCount": 0,
  "expiresAt": 1780000000000
}

取消卡密

POST /api/open/cancel

请求示例

{
  "redemptionId": 123
}

响应示例

{
  "ok": true,
  "redemption": {
    "id": 123,
    "state": "cancelled_by_user"
  }
}

获取验证码

GET /api/open/code?redemptionId=123

请求示例

Authorization: Bearer sms_xxx
X-API-Key: sms_xxx

响应示例

{
  "ok": true,
  "latestCode": "998877",
  "latestMessage": "Your code is 998877",
  "latestReceivedAt": 1780000000000,
  "receivedCount": 1,
  "maxCodes": 3,
  "history": []
}

响应字段说明

字段	类型	说明
ok	boolean	请求是否成功。失败时通常为 false，并返回 error。
cardCode	string	兑换卡密。部分接口会返回，便于业务侧关联订单。
redemptionId	number	兑换记录 ID，后续取消和查询验证码建议优先使用它。
phoneNumber	string	分配到的完整号码，通常包含国家区号。
providerKind	string	实际使用的渠道，例如 mock、grizzlysms、anosim、nexsms。
state	string	兑换状态：waiting_code、code_received、cancelled_by_user、expired_consumed 等。
maxCodes	number	本次兑换最多可接收验证码次数。nexsms 为 3，其他默认 1。
receivedCount	number	当前已收到验证码次数。达到 maxCodes 后不能继续接码。
expiresAt	number	号码有效期，毫秒时间戳。
latestCode	string\|null	最新验证码；未收到时为 null。
latestMessage	string\|null	最新完整短信内容；未收到时为 null。
latestReceivedAt	number\|null	最新验证码收到时间，毫秒时间戳。
country	object	号码国家信息，包含 key 和 name。
smsUsage	object	次数摘要，包含 used 和 limit。
canCancel	boolean	当前是否允许取消。收到任意验证码后为 false。
canResend	boolean	当前是否允许再次接码。仅 NexSMS 且未达到次数上限时为 true。
history	array	短信历史记录，包含 phoneNumber、code、message、receivedAt、operationAt。
error	string	失败原因。401 表示缺少或无效 API Key，403 表示 Key 已禁用，409 表示已收码不能取消。