号码租用 API

号码租用 API

通过兼容的 handler_api.php 接口按固定时长租用号码,并读取其收到的所有短信。

租用操作对所有 API 密钥开放,每个密钥有每日上限(见“限制”)。

工作方式

每个请求都是带 api_key 和 action 的 GET /stubs/handler_api.php。租用操作在成功和出错时都返回 JSON。

租用操作只接受 API 密钥认证。网页会话令牌会收到 WRONG_ACTION。

价格与网页面板相同,以美元从您的钱包扣款。

操作

操作参数作用
getRentServicesAndCountriescountry, rent_time某个国家和时长的租用报价。services.{code}.cost 是价格,quant 是可用库存。
getRentNumberservice, country, rent_time租用号码并从钱包扣款。返回 phone.id、phone.number 和 phone.endDate。
getRentStatusid, page, size租用号码收到的短信,最新的在前。可选 page(从 0 开始)和 size。
setRentStatusid, status (1 | 2)status=1 提前结束租用,不退款。status=2 取消租用;只有未收到任何短信时才全额退款。
continueRentNumberid, rent_time, expectedCharge将有效租用延长 rent_time 小时并从钱包扣款。
getRentList-您的有效租用:id 和 phone。
getContinueRentPriceNumberid, rent_time续租价格,不扣款。

国家代码

  • 租用已在 27 个国家开放:AT, BE, BR, CZ, DE, EE, ES, FI, FR, GB, GE, GR, HR, ID, IT, LV, MD, MY, NL, PL, PT, RO, SE, SI, SK, UA, US。租用号码或查询价格时 country 为必填,建议使用两位字母的 ISO 代码。时长:24, 72, 168 小时。
  • 如需通过 API 读取此列表,请在不带 country 的情况下调用 getRentServicesAndCountries:响应包含 countryList(ISO 代码)、hours 和 currency,不含价格和库存。如需价格和库存,请发送 country 和 rent_time。
  • 推荐:发送 ISO 国家代码,例如 country=US 或 country=GB。大小写均可。
  • 数字国家 ID 在不同服务之间并不相同。如果发送数字,请使用您自己的 API 密钥从 getCountries 的响应中读取;不要从其他服务商的列表中复制。
  • 租用操作仅接受可租用国家的数字 ID,以 getCountries 中列出的为准。其他数字会返回 BAD_COUNTRY;如不确定,请使用 ISO 代码。
  • 数字 42 (DE), 44 (HR), 45 (SE), 47 (NL), 48 (LV), 49 (AT), 51 (TH), 55 (ES), 58 (SI), 62 (CZ), 72 (BR), 77 (FR), 90 (SK), 97 (PT), 115 (GE), 116 (GR), 128 (BE), 175 (FI), 178 (IT) 不可用于租用,因为它们在其他服务中代表不同的国家。这些数字始终返回 BAD_COUNTRY_USE_ISO;不会扣费,也不会租用号码。请改为发送 ISO 代码,例如 country=DE。对于这些国家,getRentServicesAndCountries 响应中的 countries 为空。
  • 也接受我们的国家 slug。
  • getRentServicesAndCountries 会在 countries 中返回该国家的数字 ID。

列出国家及其代码

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getCountries"

按 ISO 代码查询某国家的租用报价

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries&country=US&rent_time=24"

列出可租用的国家

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries"

响应

{"countryList":["AT","BE","BR","CZ","DE","EE","ES","FI","FR","GB","GE","GR","HR","ID","IT","LV","MD","MY","NL","PL","PT","RO","SE","SI","SK","UA","US"],"hours":[24,72,168],"currency":840}

示例

请求

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentNumber&service=wa&country=US&rent_time=24"

响应

{
  "status": "success",
  "phone": {
    "id": "cm4x9k2...",
    "endDate": "2026-11-02T12:00:00",
    "number": "15550000001"
  }
}

请求

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentStatus&id=cm4x9k2..."

响应

{
  "status": "success",
  "quantity": "1",
  "values": {
    "0": {
      "phoneFrom": "WhatsApp",
      "text": "Your code: 123456",
      "service": "wa",
      "date": "2026-11-01 12:05:00"
    }
  }
}

响应细节

  • 租用 id 是字符串(例如 "cm4x9k2..."),不是数字。请以文本形式保存。
  • 时长(小时)从 rent_time 读取;也接受 time 参数。
  • 如果未发送时长,将使用可用的最短时长(目前为 24 小时)。租用和续租时请明确发送 rent_time。
  • currency 为 840(美元)。cost 和 price 是以美元计的数字。
  • endDate 和短信日期为 UTC,不带时区后缀。
  • url 参数会被忽略:租用不发送 webhook。请轮询 getRentStatus 读取新短信。
  • 错误以 {"status":"error","message":"<CODE>"} 返回。认证和速率限制错误保持纯文本格式(BAD_KEY、RATE_LIMITED)。
  • 调用 continueRentNumber 前,请先用 getContinueRentPriceNumber 获取报价。扣款金额绝不会超过最近一次向您显示的报价(有效期 10 分钟,同一租用和 rent_time)。可选参数 expectedCharge(USD,例如 1.334)只能降低此上限,不能提高。如果价格高于上限,或您没有有效报价,则不续租、不扣款,并返回新报价:WRONG_CHARGE,金额在 price 字段中。请使用新报价重试。
  • 租用只能在免费取消窗口(前 20 分钟)结束后续租;在此之前 continueRentNumber 返回 CONTINUE_TOO_EARLY,且不扣款。

取消窗口

租用开始后的前 2 分钟内拒绝取消(CANT_CANCEL)。

租用开始后最长 20 分钟内可免费取消。超过该窗口后取消会被拒绝,通常返回 CANT_CANCEL(少数情况下为 TEMPORARILY_UNAVAILABLE);请改用 status=1 结束。

取消的租用只有在未收到任何短信时才全额退款。

超时与重试

getRentNumber 不是幂等的:超时后不要重试。请先调用 getRentList;如果发现不需要的租用,请在租用开始满 2 分钟后、最长 20 分钟内取消以获得全额退款(未收到短信)。

限制

新租用按每个 API 密钥每个 UTC 日限制(续租不计):每个密钥最多 50 次租用。超出:RENT_LIMIT。

getRentNumber 和 continueRentNumber 也计入该密钥的每日 API 购买配额。

您账户中的所有 API 密钥都可以使用这些操作。

错误代码

{ "status": "error", "message": "NO_BALANCE" }
NO_BALANCE钱包余额不足。
NO_NUMBERS目前该服务、国家和时长没有可用号码。
BAD_SERVICE服务代码缺失或不受支持。
BAD_COUNTRY国家缺失、未知或不可用(请使用 ISO 代码)。
BAD_COUNTRY_USE_ISO该数字国家 ID 不可用于租用(在其他服务中代表不同国家)。请使用 ISO 代码;不会扣费。受影响的数字见“国家代码”一节。响应中还包含可读的 description 字段。
BAD_TIME不提供该时长。
NO_ID_RENT缺少 id 参数。
INVALID_PHONE您的账户中没有此 id 的租用。
INCORECT_STATUSsetRentStatus 的 status 必须为 1 或 2。
CANT_CANCEL目前不能取消(前 2 分钟内,或超过最长 20 分钟的免费窗口之后)。
ALREADY_FINISH租用已结束。
ALREADY_CANCEL租用已取消。
STATUS_WAIT_CODE租用有效,但尚未收到短信。
STATUS_CANCEL租用已取消。
STATUS_FINISH租用已结束或已过期。
RENT_LIMIT已达到此 API 密钥的每日租用上限。
TEMPORARILY_UNAVAILABLE临时问题。对于 getRentNumber 和 continueRentNumber,未扣款或已退款。对于取消,结果可能未知:重试前请用 getRentStatus 检查租用状态。
WRONG_CHARGEcontinueRentNumber:价格高于您的上限(最近一次向您显示的报价,有效期 10 分钟,可由 expectedCharge 降低),或您没有有效报价。未续租,未扣款。新报价在 price 字段中,请用它重试。
CONTINUE_TOO_EARLYcontinueRentNumber:租用开始后的前 20 分钟内(免费取消窗口)不能续租。未扣款,请在窗口结束后重试。getContinueRentPriceNumber 在此期间仍可使用。
ERROR_SQL意外的服务器错误。

REST API

所有 API 密钥都可以通过 JSON 接口使用同样的操作,路径为 /api/v1/rentals(在 x-api-key 请求头中发送密钥)。每个密钥的每日租用上限与上述操作共用;超出后 REST API 返回 429,原因为 rent_daily_cap。

curl -X POST "https://smsbulk.net/api/v1/rentals" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "serviceCode": "wa", "countryIso": "US", "durationHours": 24 }'

续租:请先用 GET /api/v1/rentals/{id}/extend-price 获取报价,再调用 POST /api/v1/rentals/{id}/extend。扣款金额绝不会超过最近一次向您显示的报价(有效期 10 分钟,同一租用和时长)。可选参数 expectedCharge(USD,以字符串形式,例如 "1.334")只能降低此上限,不能提高。如果价格高于上限,或您没有有效报价,则不续租、不扣款,API 返回 409 PRICE_CHANGED,新报价在 currentCharge 中。请使用新报价重试。

租用开始后的前 20 分钟内(免费取消窗口),POST /api/v1/rentals/{id}/extend 返回 409 RENTAL_EXTEND_TOO_EARLY;响应体包含 extendAllowedFrom(ISO 时间),即可以开始续租的时刻。不扣款,报价查询仍可使用。