云手机号

NexSMS 云手机号的国家与项目查询、号码购买、已购记录、读取短信验证码，以及释放号码申请退款。购买只传国家、项目和数量，由服务端按当前价格直接扣减账户余额，单次最多 10 个号码。

号码以完整的 tel 字符串标识，读取短信和释放号码都使用它。业务接口的公共约定见服务与鉴权。

Agent/MCP 交互任务默认等待短信 120 秒，确认号码无效、不支持或等码超时后自动释放可释放的旧号码并换号，含首次最多 3 次。国家/项目切换须仍匹配目标站点及用户硬性要求，不重置次数；购买结果未知先核对记录和账单，未核清不重复扣费。HTTP 接口本身不隐式执行换购循环。

在本页搜索

显示 6 / 6 个接口

GET/sms/countries

号码国家列表

列出可购买云手机号的国家/地区，countryId 用于查询项目与购买。

鉴权Bearer API Key

请求参数

无参数

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	国家列表
`data[].countryId`	`number`	国家 ID
`data[].countryName`	`string`	国家名称

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "countryId": 1,
      "countryName": "美国"
    },
    {
      "countryId": 44,
      "countryName": "英国"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/sms/stocks

号码项目与库存

查询某个国家下可接码的项目（目标应用或站点）及实时单价与库存。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`countryId`	`number`	必填	国家 ID，取自 /sms/countries

注意事项

countryId 缺省或不是正整数时返回 code 1「countryId is required」。
库存只代表查询时的状态，不保证提交时仍有货。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	项目列表
`data[].countryId`	`number`	国家 ID
`data[].countryName`	`string`	国家名称
`data[].projectId`	`number`	项目 ID，购买时提交
`data[].projectName`	`string`	项目名称，如 Telegram、WhatsApp
`data[].available`	`number`	查询时的库存数量
`data[].price`	`number`	上游单价
`data[].discountPrice`	`number`	实际售价，购买按此单价计费
`data[].currency`	`string`	币种
`data[].iconUrl`	`string`	项目图标地址，可为 null

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "countryId": 1,
      "countryName": "美国",
      "projectId": 1001,
      "projectName": "Telegram",
      "available": 128,
      "price": 0.25,
      "discountPrice": 0.3,
      "currency": "USDT",
      "iconUrl": "https://oss.nexbrowser.net/images/sms/telegram.png"
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/sms/buy

购买手机号

按国家和项目购买接码号码并扣减余额，单次最多 10 个。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`countryId`	`number`	必填	国家 ID
`projectId`	`number`	必填	项目 ID，取自 /sms/stocks
`quantity`	`number`	可选	购买数量，1 到 10，默认 1

注意事项

校验国家、项目和数量后直接提交一次；服务端按当前价格扣费并校验权限、余额和库存，业务错误原样透传。
仅接受 countryId、projectId、quantity；携带已移除的 maxTotalPrice 或其他未知字段返回 code 1，且不提交购买。countryId、projectId 缺失或 quantity 不在 1 到 10 时同样返回 code 1。
批量购买逐个执行，不保证整批原子性；后面的号码失败时前面的可能已购成功。
成功且 data 为 null 时请刷新 /sms/records 获取号码；超时或结果不明时先查 /sms/records 与 /billing/trades，不要重复购买。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[] \| null`	服务端通常返回 null；返回号码数组时字段同 /sms/records 条目

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": null,
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/sms/records

已购号码记录

分页查询当前用户在当前团队下购买的号码，包含状态、到期时间与已收短信。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`page`	`number`	可选	页码，默认 1
`size`	`number`	可选	每页数量，默认 20，超过 100 按 100 处理
`keyword`	`string`	可选	关键词，匹配手机号、国家名或项目名

注意事项

page、size 不是正整数时按默认值处理，不返回错误。
需要号码时先查本接口，确认没有可用号码再购买。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data.count`	`number`	匹配到的总条数
`data.size`	`number`	每页数量，回显请求值
`data.page`	`number`	当前页码，回显请求值
`data.total`	`number`	总页数
`data.data`	`object[]`	当前页记录
`data.data[].id`	`number`	本地记录 ID
`data.data[].orderNo`	`string`	订单号
`data.data[].tel`	`string`	手机号，按字符串原样保留
`data.data[].countryId`	`number`	国家 ID
`data.data[].countryName`	`string`	国家名称
`data.data[].projectId`	`number`	项目 ID
`data.data[].projectName`	`string`	项目名称，即目标应用或站点
`data.data[].price`	`number`	实付单价，USDT
`data.data[].state`	`number`	状态：0 等待短信、1 已收到短信、2 已过期、-1 已退款
`data.data[].message`	`string`	已收到短信的 JSON 文本，按时间倒序
`data.data[].product`	`string`	购买时项目快照的 JSON 文本
`data.data[].expireTime`	`string`	号码到期时间
`data.data[].createdAt`	`string`	创建时间
`data.data[].updatedAt`	`string`	更新时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 7101,
        "orderNo": "NSMS20261023000001",
        "tel": "+12025550123",
        "countryId": 1,
        "countryName": "美国",
        "projectId": 1001,
        "projectName": "Telegram",
        "price": 0.3,
        "state": 0,
        "message": "[]",
        "product": "{\"projectId\":1001,\"projectName\":\"Telegram\",\"discountPrice\":0.3}",
        "expireTime": "2026-10-23 10:20:00",
        "createdAt": "2026-10-23 10:00:00",
        "updatedAt": "2026-10-23 10:00:00"
      }
    ]
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/sms/pull

读取号码短信

主动向上游拉取单个号码的最新短信，并返回更新后的号码记录。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`tel`	`string`	必填	完整手机号，取自 /sms/records 的 tel

注意事项

tel 缺省返回 code 1「tel is required」。
message 是 JSON 文本，部分记录会再被编码一次，解析一次后仍是字符串时请再解析一次。
是否收到短信以 message 列表为准，不要只看 state；建议每 5 到 15 秒轮询一次，号码到期后停止。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object \| null`	号码记录，字段同 /sms/records 条目；号码不存在时可能为 null
`data.tel`	`string`	手机号，按字符串原样保留
`data.state`	`number`	状态：0 等待短信、1 已收到短信、2 已过期、-1 已退款
`data.message`	`string`	已收到短信的 JSON 文本，按时间倒序
`data.expireTime`	`string`	号码到期时间
`data.message[].code`	`string`	解析 message 后每条短信的验证码，可能为空
`data.message[].message`	`string`	短信正文
`data.message[].from`	`string`	发送方
`data.message[].receivedAt`	`string`	收信时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 7101,
    "orderNo": "NSMS20261023000001",
    "tel": "+12025550123",
    "countryId": 1,
    "countryName": "美国",
    "projectId": 1001,
    "projectName": "Telegram",
    "price": 0.3,
    "state": 1,
    "message": "[{\"msgId\":\"m-1\",\"number\":\"+12025550123\",\"app\":\"Telegram\",\"region\":\"US\",\"from\":\"Telegram\",\"message\":\"Telegram code: 12345\",\"code\":\"12345\",\"receivedAt\":\"2026-10-23 10:02:00\"}]",
    "product": "{\"projectId\":1001,\"projectName\":\"Telegram\",\"discountPrice\":0.3}",
    "expireTime": "2026-10-23 10:20:00",
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:00"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/sms/recover

释放号码并申请退款

对仍在等待短信的号码申请释放与退款，是否退款及金额由服务端和上游判断。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`tel`	`string`	必填	完整手机号
`reason`	`string`	必填	原因：no_code 收不到验证码、rejected 号码被拒、already_registered 已被注册、cannot_send_code 无法发送验证码、other 其他

注意事项

tel 缺省返回 code 1「tel is required」；reason 不在枚举内返回「reason must be one of …」。
已收到短信的号码不能退款，服务端返回 -3004；购买时长等规则由上游判断，具体原因见 msg。
响应不代表已入账退款，也不要只看响应里的 state；请刷新 /sms/records 与 /billing/trades 确认，失败时不要自动重试。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object \| null`	号码记录，字段同 /sms/records 条目；重复操作或非等待状态时可能为 null

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 7101,
    "orderNo": "NSMS20261023000001",
    "tel": "+12025550123",
    "countryId": 1,
    "countryName": "美国",
    "projectId": 1001,
    "projectName": "Telegram",
    "price": 0.3,
    "state": -1,
    "message": "[]",
    "product": "{\"projectId\":1001,\"projectName\":\"Telegram\",\"discountPrice\":0.3}",
    "expireTime": "2026-10-23 10:20:00",
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:00"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}