# API 接入文档

通过 API Key 调用接码服务:取号,使用号码触发短信,轮询获取验证码

### 快速开始

1. 在[用户中心](https://rdwpxs.vip/user/login)获取您的 **API Key**(形如 `sk-xxxx`)。
2. 调用 `get_number` 取号,指定**平台** `platform`(必填)与**国家** `country`(选填,**不传则随机选国家**),得到订单号与手机号。
3. 将该手机号填入目标平台(Telegram/Instagram 等)触发短信验证码。
4. 轮询 `get_sms`(建议每 3~5 秒一次)直到返回验证码。

同一个号码不会重复分配给同一个平台,避免"号码已注册过该平台"的问题。**取号不计费,只有成功收到验证码才按对应平台价格(美元)扣费**;超时/取消不产生费用。

### 基础信息

| 项目 | 内容 |
| --- | --- |
| 接口基址 | `https://rdwpxs.vip/api/` |
| 请求方式 | GET 或 POST 均可 |
| 鉴权方式 | 参数 `key=API_KEY`,或请求头 `X-API-KEY` / `Authorization: Bearer` |
| 返回格式 | JSON,统一结构 `{"code":0,"msg":"success","data":{...}}`;code=0 为成功 |
| 监听时效 | 取号后 5 分钟内有效,超时未收码自动释放(取号不计费,无扣款) |

## 1. 获取国家 + 平台列表

```
GET https://rdwpxs.vip/api/?action=countries&key=API_KEY
```

返回可用国家及其号码库存,每个国家下附带开放的平台与**面向当前 API Key 的实际价格**(已含用户专属价)。

```
{
  "code": 0, "msg": "success",
  "data": [
    {
      "country": "CD", "name": "刚果金", "available": 1980,
      "platforms": [
        { "platform": "tg", "name": "Telegram", "price": 0.1 },
        { "platform": "ins", "name": "Instagram", "price": 0.2 },
        { "platform": "ws", "name": "WhatsApp", "price": 0.2 }
      ]
    }
  ]
}
```

## 2. 获取平台列表(可选)

```
GET https://rdwpxs.vip/api/?action=platforms&key=API_KEY
```

仅返回全部平台及其默认价格(不含国家/用户维度差异)。

```
{ "code": 0, "msg": "success",
  "data": [ { "platform": "tg", "name": "Telegram", "price": 0.1 }, { "platform": "fb", "name": "Facebook", "price": 0.3 } ] }
```

## 3. 取号

```
GET https://rdwpxs.vip/api/?action=get_number&country=CD&platform=tg&key=API_KEY
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `action` | 是 | 固定 get_number |
| `country` | **否** | 国家代码(见国家列表 country 字段)。**不传则自动随机选择国家** —— 详见下方说明 |
| `platform` | 是 | 平台代码,如 tg/ins/ws/tk/fb(见下方平台代码表) |
| `count` | 否 | **批量取号**:一次取多少个(1~15,默认 1)。省略或 =1 时返回单个对象;>1 时返回号码数组 |
| `key` | 是 | 您的 API Key |

**不指定国家(随机取号)**  
省略 `country` 参数即可,系统会自动从**您已开通、且该平台当前有库存的国家**中随机挑选一个:

```
// 不传 country,随机国家取一个 ws 号
GET https://rdwpxs.vip/api/?action=get_number&platform=ws&key=API_KEY

{ "code":0, "msg":"success", "data":{
    "order_no":"202607290012345678",
    "country":"PE",          // ← 实际选中的国家,以返回值为准
    "platform":"ws", "number":"51966364963", "price":0.25,
    "expire_in":300
} }
```

- 选择按**库存加权**:库存多的国家被选中的概率更高,不会总撞到快取空的小国家。
- 选中的国家若恰好取空或上游异常,会**自动换下一个国家重试**(最多 5 个),提高成功率。
- 批量取号(`count`>1)时,当前国家取完会自动切换到下一个国家继续凑数。
- **价格以返回的 `price` 为准** —— 不同国家单价不同,随机取号前请确认各国定价可接受。
- 没有任何符合条件的国家时返回 `code=3`,请稍后重试或改为指定国家。

**批量取号示例** `&count=5` 一次取 5 个:

```
// GET .../api/?action=get_number&country=CD&platform=tg&count=5&key=API_KEY
{ "code":0, "msg":"success", "data":{
    "country":"CD", "platform":"tg", "price":0.1,
    "requested":5, "count":5,
    "numbers":[
      {"order_no":"2026...001","number":"24390000001"},
      {"order_no":"2026...002","number":"24390000002"}
    ]
}}
```

```
{
  "code": 0, "msg": "success",
  "data": {
    "order_no": "202607151203339981",
    "country": "CD",
    "platform": "tg",
    "number": "243906887805",
    "price": 0.1,
    "expire_in": 300,
    "tip": "请在 5 分钟内使用该号码接收验证码;仅收到验证码时扣费 $0.1"
  }
}
```

**取号本身不扣费**。只有 get_sms 成功返回验证码时,才从余额扣除该平台价格(美元);超时或 cancel 不产生任何费用。系统保证同一号码不会重复分配到同一平台。

**渠道授权**:取号需管理员为你的账号开通该国家/渠道,未开通返回 `code 1`「未开通该国家/渠道权限」,请联系管理员。 **并发线程**:每个账号有并发上限(管理员可设),超过返回 `code 429`,请降低客户端并发线程数后重试。

## 4. 获取验证码(轮询,支持批量)

```
GET https://rdwpxs.vip/api/?action=get_sms&order_no=ORDER_NO&key=API_KEY
```

建议每 3~5 秒轮询一次,直到 status 变为 received。**批量查码**:order_no 用逗号分隔多个订单号(最多 20),一次查询多单。

```
// 批量:GET .../api/?action=get_sms&order_no=单号1,单号2,单号3&key=API_KEY
{ "code":0, "msg":"success", "data":{
    "total":3, "received":1,
    "results":[
      {"order_no":"单号1","status":"received","number":"...","code":"123456","charged":0.1},
      {"order_no":"单号2","status":"waiting","number":"...","code":null},
      {"order_no":"单号3","status":"expired","code":null}
    ]
}}
```

批量模式恒返回 code 0,逐单看 results[].status;单个模式仍兼容旧的 code 0/6/7。取消也支持批量:`action=cancel&order_no=单号1,单号2`。

```
// 尚未收到
{ "code": 7, "msg": "暂无验证码,请稍后重试", "data": { "status": "waiting", "number": "243906887805" } }

// 已收到验证码
{
  "code": 0, "msg": "success",
  "data": {
    "order_no": "202607151203339981",
    "status": "received",
    "number": "243906887805",
    "code": "123456",
    "content": "您的验证码是 123456"
  }
}
```

## 5. 取消订单

```
GET https://rdwpxs.vip/api/?action=cancel&order_no=ORDER_NO&key=API_KEY
```

取消等待中的订单并释放号码(取号未计费,无扣款)。

**取号后 4 分钟内不可取消**:4 分钟内调用会返回 `code 1`「取号后 4 分钟内不可取消,请先等待验证码」。请等待验证码,或订单满 5 分钟超时后自动作废(超时不计费)。批量取消中未满 4 分钟的单会保持 waiting、其余正常取消。

## 6. 查询余额(美元)

```
GET https://rdwpxs.vip/api/?action=balance&key=API_KEY
```

```
{ "code": 0, "msg": "success", "data": { "username": "demo", "balance": 9.85, "currency": "USD" } }
```

balance 为美元可用余额;收到验证码时按平台价格扣减。余额充值请联系管理员。

## 返回码说明

| code | 含义 |
| --- | --- |
| 0 | 成功 |
| 1 | 参数错误 / 资源不存在 / 未开通该渠道权限 / 取号 4 分钟内不可取消 |
| 2 | 余额不足 |
| 3 | 该国家号码库存不足,或上游繁忙(稍后重试) |
| 4 | 号码提交上游失败 |
| 6 | 订单已超时(满 5 分钟)或已取消,未收到验证码 |
| 7 | 暂无验证码(继续轮询) |
| 429 | 请求过于频繁 / 已达账户并发线程上限(降低并发或稍后重试) |
| 401 / 403 | API Key 无效 / 账户禁用 |

## 代码示例(Python)

```python
import requests, time

BASE = "https://rdwpxs.vip/api/"
KEY  = "你的API_KEY"

def call(action, **params):
    params.update(action=action, key=KEY)
    return requests.get(BASE, params=params, timeout=30).json()

# 1) 取号(指定国家 + 平台)
r = call("get_number", country="CD", platform="tg")
print(r)
order_no = r["data"]["order_no"]
number   = r["data"]["number"]
print("请用号码接收验证码:", number)

# 2) 轮询收码(最多 5 分钟)
for _ in range(60):
    time.sleep(5)
    r = call("get_sms", order_no=order_no)
    if r["code"] == 0:
        print("验证码:", r["data"]["code"]); break
    print("等待中...")
```

## 代码示例(cURL)

```bash
curl "https://rdwpxs.vip/api/?action=get_number&country=CD&platform=tg&key=你的API_KEY"
curl "https://rdwpxs.vip/api/?action=get_sms&order_no=订单号&key=你的API_KEY"
```

## 平台代码表

| 平台 | 代码 | 默认价(美元) |
| --- | --- | --- |
| RCS | `rcs` | $0.20 |
| Instagram | `ins` | $0.20 |
| TikTok | `tk` | $0.15 |
| Facebook | `fb` | $0.30 |
| Google | `ggl` | $0.06 |
| 抖音 | `dy` | $0.10 |
| Viber | `vb` | $0.15 |

实际价格以 `countries` 返回的 platforms.price 为准(含国家差价与您的专属价)。用户可在控制台自建**专属渠道**并上传号码,仅本人 Key 可调用。

## 当前可用国家代码

| 国家 | 代码 |
| --- | --- |
| 阿富汗 | `AF` |
| 阿富汗2 | `AF2` |
| 巴基斯坦 | `PK` |
| 巴西 | `BR` |
| 赤道几内亚 | `GQ` |
| 刚果金 | `CD` |
| 哥伦比亚 | `CO` |
| 喀麦隆 | `CM` |
| 马尔代夫 | `MV` |
| 马来西亚 | `MY` |
| 马里 | `ML` |
| 蒙古 | `MN` |
| 秘鲁 | `PE` |
| 莫桑比克 | `MZ` |
| 斯里兰卡 | `LK` |
| 布基纳法索 | `BF` |
| 印度尼西亚 | `ID` |
| 吉尔吉斯坦 | `KG` |
| 加蓬 | `GA` |
| 塞拉利昂 | `SL` |
| 泰国 | `TH` |

© 2026 接码 API 分配平台

---

文档生成时间:2026-11-13 20:24  
在线版本:https://rdwpxs.vip/guide