接码 API 接入指南与接口文档 | SMS Activation - 短信接码平台

欢迎使用 SMS-Activation API。

API 是您的软件与我们的服务器之间进行交互的协议，我们的 API 与主流网站保持兼容。所有请求都应被发送至 https://www.sms-activation.net/stubs/handler_api.php，使用 GET/POST 方法；每一个请求都必须携带一个 API 密钥作为 api_key 参数。

基本信息(Overview)

项目	说明
Base URL	`https://www.sms-activation.net/stubs/handler_api.php`
请求方法	`GET`/`POST`
返回格式	文本或 JSON
鉴权方式	`api_key` 参数

所有请求都必须携带以下两个公共参数：

参数	类型	必填	说明
`api_key`	string	是	您的 API 密钥，可以在 API 文档页点击「查看 API Key」获取
`action`	string	是	要调用的接口方法，请见下方 Action 总览

如果 api_key 无效或缺失，将返回 BAD_KEY,
如果 action 不存在，将返回 BAD_ACTION。

Action 总览

Action	说明	返回类型
`getBalance`	查询账户余额	文本
`getPrices`	获取号码价格与库存	JSON
`getNumber`	购买一个手机号用于接收验证码	文本
`setStatus`	更新某个激活订单的状态（确认/重发/取消）	文本
`getActiveActivations`	获取当前账户所有进行中的激活订单	JSON

1. 查询余额 `getBalance`

返回账户的当前可用余额。

请求参数

参数	类型	必填	说明
`api_key`	string	是	API 密钥
`action`	string	是	固定值 `getBalance`

请求示例

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance"

返回示例

ACCESS_BALANCE:128.50

可能的错误

返回值	说明
`BAD_KEY`	`api_key` 无效

2. 获取价格 `getPrices`

获取各国家/各服务的号码单价与库存数量，可以按 service、country 进行过滤。

请求参数

参数	类型	必填	说明
`api_key`	string	是	API 密钥
`action`	string	是	固定值 `getPrices`
`service`	string	否	服务代码，例如 `tg`（Telegram）；如果不传，则返回全部服务
`country`	number	否	国家代码，例如 `187`（美国）；如果不传，则返回全部国家

请求示例

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices&service=tg&country=187"

返回示例

{
  "187": {
    "tg": {
      "cost": 13.5,
      "count": 5000,
      "physicalCount": 4800
    }
  }
}

返回结构为 { 国家代码: { 服务代码: { cost, count, physicalCount } } }：

字段	说明
`cost`	该号码的单价（人民币元，已根据账户等级折算）
`count`	该国家/服务当前可用的库存数量
`physicalCount`	实体号码的库存数量（部分服务可能没有此字段）

3. 获取号码 `getNumber`

购买一个临时手机号，用于接收来自指定服务的短信验证码。

请求参数

参数	类型	必填	说明
`api_key`	string	是	API 密钥
`action`	string	是	固定值 `getNumber`
`service`	string	是	服务代码，例如 `tg`
`country`	number	是	国家代码，例如 `187`

请求示例

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=187"

返回示例

ACCESS_NUMBER:38223344:12015550123

返回格式为 ACCESS_NUMBER:{activationId}:{phoneNumber}。请保存好 activationId，后续的查询与状态更新将会用到它。

可能的错误

返回值	说明
`NO_NUMBERS`	当前服务/国家暂时没有可用号码
`NO_BALANCE`	账户余额不足
`BAD_SERVICE`	`service` / `country` 参数不正确

4. 更新激活状态 `setStatus`

在获取号码之后使用，用于告知系统下一步的操作：重新发送短信、确认完成、或者取消该次激活。

请求参数

参数	类型	必填	说明
`api_key`	string	是	API 密钥
`action`	string	是	固定值 `setStatus`
`id`	string	是	`getNumber` 所返回的 `activationId`
`status`	number	是	目标状态，请见下表

状态值说明

`status`	含义
`3`	请求重发一条短信（等待下一条验证码）
`6`	确认激活完成
`8`	取消本次激活（购买后的 2 分钟内不可取消）

status=1（号码已准备好）由系统自动设置；客户端在调用 getNumber 之后，无需也不能手动传入。

请求示例

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=38223344&status=6"

返回示例

ACCESS_ACTIVATION

可能的错误

返回值	说明
`BAD_STATUS`	`status` 取值不在允许范围内
`WRONG_ACTIVATION_ID`	`id` 不存在，或不属于当前账户
`EARLY_CANCEL_DENIED`	在购买后的 2 分钟内尝试取消（`status=8`）

5. 查询进行中的激活 `getActiveActivations`

返回当前账户中所有尚未结束（未确认/未取消）的激活订单详情。

请求参数

参数	类型	必填	说明
`api_key`	string	是	API 密钥
`action`	string	是	固定值 `getActiveActivations`

请求示例

curl "https://www.sms-activation.net/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getActiveActivations"

返回示例

[
  {
    "activationId": "38223344",
    "phoneNumber": "12015550123",
    "countryCode": 187,
    "countryName": "美国",
    "countryNameCN": "美国",
    "serviceCode": "tg",
    "serviceNameCN": "Telegram",
    "activationStatus": 2,
    "status": 0,
    "activationCost": 13.5,
    "price_cn": 13.5,
    "activationTime": "2026-06-27T08:00:00.000Z",
    "canGetAnotherSms": true,
    "activationOperator": "",
    "discount": "",
    "repeated": "",
    "smsCode": ["123456"],
    "smsText": ["Your Telegram code: 123456"]
  }
]

字段说明

字段	说明
`activationId`	激活订单 ID
`phoneNumber`	分配到的手机号
`countryCode` / `countryName`	国家代码 / 中文名称
`serviceCode` / `serviceNameCN`	服务代码 / 中文名称
`activationCost` / `price_cn`	订单的价格
`smsCode`	已收到的验证码列表
`smsText`	已收到的完整短信内容列表
`canGetAnotherSms`	是否允许继续请求下一条短信

错误码一览(Error Codes)

错误码	说明
`BAD_KEY`	`api_key` 无效
`BAD_ACTION`	`action` 参数无效
`BAD_SERVICE`	`service` 或 `country` 参数无效
`BAD_STATUS`	`status` 参数无效
`NO_NUMBERS`	当前服务/国家暂时没有可用号码
`NO_BALANCE`	账户余额不足
`WRONG_ACTIVATION_ID`	激活订单 ID 不存在，或不属于当前账户
`EARLY_CANCEL_DENIED`	在购买后的 2 分钟内尝试取消激活