号码租用 API
通过兼容的 handler_api.php 接口按固定时长租用号码,并读取其收到的所有短信。
工作方式
每个请求都是带 api_key 和 action 的 GET /stubs/handler_api.php。租用操作在成功和出错时都返回 JSON。
租用操作只接受 API 密钥认证。网页会话令牌会收到 WRONG_ACTION。
价格与网页面板相同,以美元从您的钱包扣款。
操作
| 操作 | 参数 | 作用 |
|---|---|---|
getRentServicesAndCountries | country, rent_time | 某个国家和时长的租用报价。services.{code}.cost 是价格,quant 是可用库存。 |
getRentNumber | service, country, rent_time | 租用号码并从钱包扣款。返回 phone.id、phone.number 和 phone.endDate。 |
getRentStatus | id, page, size | 租用号码收到的短信,最新的在前。可选 page(从 0 开始)和 size。 |
setRentStatus | id, status (1 | 2) | status=1 提前结束租用,不退款。status=2 取消租用;只有未收到任何短信时才全额退款。 |
continueRentNumber | id, rent_time, expectedCharge | 将有效租用延长 rent_time 小时并从钱包扣款。 |
getRentList | - | 您的有效租用:id 和 phone。 |
getContinueRentPriceNumber | id, 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_ | 钱包余额不足。 |
NO_ | 目前该服务、国家和时长没有可用号码。 |
BAD_ | 服务代码缺失或不受支持。 |
BAD_ | 国家缺失、未知或不可用(请使用 ISO 代码)。 |
BAD_ | 该数字国家 ID 不可用于租用(在其他服务中代表不同国家)。请使用 ISO 代码;不会扣费。受影响的数字见“国家代码”一节。响应中还包含可读的 description 字段。 |
BAD_ | 不提供该时长。 |
NO_ | 缺少 id 参数。 |
INVALID_ | 您的账户中没有此 id 的租用。 |
INCORECT_ | setRentStatus 的 status 必须为 1 或 2。 |
CANT_ | 目前不能取消(前 2 分钟内,或超过最长 20 分钟的免费窗口之后)。 |
ALREADY_ | 租用已结束。 |
ALREADY_ | 租用已取消。 |
STATUS_ | 租用有效,但尚未收到短信。 |
STATUS_ | 租用已取消。 |
STATUS_ | 租用已结束或已过期。 |
RENT_ | 已达到此 API 密钥的每日租用上限。 |
TEMPORARILY_ | 临时问题。对于 getRentNumber 和 continueRentNumber,未扣款或已退款。对于取消,结果可能未知:重试前请用 getRentStatus 检查租用状态。 |
WRONG_ | continueRentNumber:价格高于您的上限(最近一次向您显示的报价,有效期 10 分钟,可由 expectedCharge 降低),或您没有有效报价。未续租,未扣款。新报价在 price 字段中,请用它重试。 |
CONTINUE_ | continueRentNumber:租用开始后的前 20 分钟内(免费取消窗口)不能续租。未扣款,请在窗口结束后重试。getContinueRentPriceNumber 在此期间仍可使用。 |
ERROR_ | 意外的服务器错误。 |
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 时间),即可以开始续租的时刻。不扣款,报价查询仍可使用。