---
title: "接码 API 接入指南与接口文档 | SMS Activation - 短信接码平台 | Receive SMS"
description: "兼容主流接码协议的 API 文档：查询余额、获取号码价格、购买虚拟号码、自动短信在线接收验证码，助您快速集成虚拟手机号码接码能力。"
canonical_url: "https://www.sms-activation.net/api-doc"
locale: zh
meta:
  keywords: 接码API,SMS接码平台API,虚拟号码API,短信在线接收,虚拟手机号码,验证码API,API接入文档
  "og:description": "兼容主流接码协议的 API 文档：查询余额、获取号码价格、购买虚拟号码、自动短信在线接收验证码，助您快速集成虚拟手机号码接码能力。"
  "og:title": "接码 API 接入指南与接口文档 | SMS Activation - 短信接码平台 | Receive SMS"
---

> Index of every page on this site: [llms.txt](https://www.sms-activation.net/llms.txt)

# **接码 API 接入指南与接口文档**

兼容主流接码协议的 API 文档：查询余额、获取号码价格、购买虚拟号码、自动短信在线接收验证码，助您快速集成虚拟手机号码接码能力。

欢迎使用 **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 文档页](https://www.sms-activation.net/api-doc)点击「查看 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 分钟内尝试取消激活 |

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://www.sms-activation.net/#website","@type":"WebSite","inLanguage":"zh-CN","name":"SMS-Activation","url":"https://www.sms-activation.net/","workTranslation":[{"@id":"https://www.sms-activation.net/en#website"},{"@id":"https://www.sms-activation.net/ru#website"}]},{"@id":"https://www.sms-activation.net/api-doc#webpage","@type":"WebPage","description":"兼容主流接码协议的 API 文档：查询余额、获取号码价格、购买虚拟号码、自动短信在线接收验证码，助您快速集成虚拟手机号码接码能力。","name":"接码 API 接入指南与接口文档","url":"https://www.sms-activation.net/api-doc","isPartOf":{"@id":"https://www.sms-activation.net/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://www.sms-activation.net/api-doc"]}]}]}
```

## Sitemap

See the full [sitemap](https://www.sms-activation.net/sitemap.md) for all pages.