# 接码平台 · API 对接文档 v2.0

> 新接入统一使用 `https://api.psyawqnx.beauty/v2/`（豪猪协议风格，API 账号 + API 密码）。本文档说明全链路能力、接口定义、状态机与计费规则；原 `open/*` 规则仅供历史存量兼容，新软件不再使用。
> 最后更新：2026-11-20
> 权威源：`app/controllers/OpenController.php` + `app/core/KeywordService.php`（源码路径仅作说明，不提供前端下载）

---

## v2 豪猪兼容接入（现成软件推荐）

v2 使用豪猪风格的 `api=动作` 协议。现成软件只需把接口地址改为 `https://api.psyawqnx.beauty/v2/`，账号密码填本平台账号密码即可接入。与原协议相比，本平台额外支持全球国家、统一服务搜索、通用短信关键词、租号与邮箱；且不会返回任何上游供应商标识或成本字段。

> 唯一对外入口为 `https://api.psyawqnx.beauty/v2/`；`/v2`、`/v2/`、`/v2/sms/` 均可直接使用。

> **安全说明**：第三方软件请填写「个人中心 → 独立 API 账号 / 密码」，**不要填写网站登录用户名与登录密码**。独立凭证可随时重置；旧的用户名 + API Key 仅用于历史兼容，网站登录密码不会用于 v2 鉴权。

### 入口与鉴权

| 项目 | 说明 |
|------|------|
| 登录 | `api=login&user=API账号&pass=API密码` → 返回 `token`、`money` |
| 后续请求 | 携带 `token=登录返回的token`；也兼容直接传 `user`+`pass`、`apikey`、`X-API-KEY` |
| 响应 | 字段平铺在顶层；`code=0` 成功，`code=-1` 等待短信，其他为错误 |

```bash
curl -s -G 'https://api.psyawqnx.beauty/v2/' \
  --data-urlencode 'api=login' \
  --data-urlencode 'user=YOUR_API_ACCOUNT' \
  --data-urlencode 'pass=YOUR_API_PASSWORD'

curl -s -G 'https://api.psyawqnx.beauty/v2/' \
  --data-urlencode 'api=getSummary' \
  --data-urlencode 'token=YOUR_TOKEN'
```

### 核心字段速查表

所有响应字段平铺在顶层。国家编码、服务编号与接码链路常用字段如下。

**国家字段（getCountries）**

| 字段 | 示例 | 说明 |
|------|------|------|
| id | `name:china` / `US` | 国家编码，唯一标识；可作为 `country` 使用 |
| name | `中国` | 中文展示名 |
| code | `CN` | ISO 3166-1 alpha-2 国家码，部分国家可能为空 |

```json
{"code":0,"msg":"success","list":[{"id":"name:china","name":"中国","code":"CN"}],"total":210}
```

**服务编号字段（getProjects）**

| 字段 | 示例 | 说明 |
|------|------|------|
| sid | `eyJ0Ijoic21zIi...` | 服务编号/下单标识，原样传给 `getPhone` / `rentPhone` |
| name | `Hostinger` | 服务名称 |
| country | `哥伦比亚` | 服务所属国家 |
| price | `0.22` | 用户折后销售价（USD），不返回成本 |

```json
{"code":0,"msg":"success","list":[{"sid":"eyJ0Ijoic21zIi...","name":"Hostinger","country":"哥伦比亚","price":"0.22"}],"total":235}
```

**取号与短信字段**

| 接口 | 字段 | 示例 | 说明 |
|------|------|------|------|
| getPhone | phone / number | `+639651150154` | 分配到的号码 |
| getPhone | order_no | `O20261120172249330228` | 普通接码订单号 |
| getMessage | yzm | `839217` | 验证码，等待时 `code=-1` |
| getMessage | sms | `【XX】验证码 839217` | 短信全文 |
| keywordPhone | order_no | `K20261120172212673647` | 通用短信订单号 |
| keywordMessage | yzm / sms | `839217` | 关键词匹配验证码与内容 |
| cancelRecv / keywordRelease | order_no | `O...` / `K...` | 释放订单，重复释放被拒绝 |

**通用请求字段**

| 字段 | 适用接口 | 说明 |
|------|----------|------|
| api | 全部 | 动作名 |
| user / pass | login（也可直传全部接口） | 个人中心生成的独立 API 账号/密码，与网站登录密码无关 |
| token | 除 login 外 | 登录返回的 token |
| sid | getPhone / rentPhone | 服务编号 |
| country | getProjects / keywordPhone | 国家编码或国家名 |
| kw / service | getProjects | 服务关键词，中英文均可 |
| keyword | keyword* | 短信关键词，通用短信必填 |
| order_no | 拉码/释放/历史 | 订单号 |

### 动作清单

| 分类 | api | 主要参数 |
|------|-----|----------|
| 账户 | `login` / `getSummary` | `user`/`pass`；`token` |
| 全球国家 | `getCountries` | `force=1` 强刷缓存 |
| 统一服务 | `getProjects` | `kw`/`service`、`country`、`page`、`page_size` → `sid`/`name`/`country`/`price` |
| 普通接码 | `getPhone` / `getMessage` / `cancelRecv` | `sid`；`order_no` |
| 通用短信 | `keywordPhone` / `keywordMessage` / `keywordRelease` / `keywordNumbers` / `keywordHistory` | `keyword` 必填，`country` 可选 |
| 租号 | `rentOptions` / `rentPhone` / `rentMessage` / `rentRelease` / `rentOrders` | `sid`、`minutes` |
| 邮箱 | `emailOffers` / `emailBuy` / `emailSms` | `site`；`site`+`domain`；`order_no` |

### 与原 open API 的差异

- 接入规则：`https://api.psyawqnx.beauty/v2/` 是唯一对外接入规则；原 `open/*` 仅保留给历史存量系统，新对接软件不再使用。
- 全球国家：`getCountries` 跨通道聚合去重，不返回来源。
- 统一服务：`getProjects` 支持中英文关键词搜索与用户折扣价。
- 扩展能力：通用短信、租号、邮箱为 v2 原生能力。
- 安全：不返回 `provider`、`upstream_provider`、`cost`、`cny_cost` 等内部字段。

---

## 目录

- [v2 豪猪兼容接入](#v2-豪猪兼容接入现成软件推荐)
  - [核心字段速查表](#核心字段速查表)
- [一、准备工作](#一准备工作)
- [二、协议规范](#二协议规范)
- [三、鉴权](#三鉴权)
- [四、快速开始（10 分钟跑通）](#四快速开始10-分钟跑通)
- [五、速率限制](#五速率限制)
- [六、错误码与状态语义](#六错误码与状态语义)
- [七、返回格式](#七返回格式)
- [八、接口全量定义](#八接口全量定义)
  - [健康检查与状态（无需认证）](#健康检查与状态无需认证)
  - [状态与能力查询（需认证）](#状态与能力查询需认证)
  - [查询类](#查询类)
  - [接码取号链路](#接码取号链路)
  - [租号链路](#租号链路)
  - [通用短信（关键词匹配）链路](#通用短信关键词匹配链路)
  - [批量取号](#批量取号)
  - [在线测试](#在线测试)
- [九、订单状态机](#九订单状态机)
- [十、计费规则](#十计费规则)
- [十一、多语言示例](#十一多语言示例)
- [十二、变更记录](#十二变更记录)

---

## 一、准备工作

1. 注册/登录接码平台 `https://www.psyawqnx.beauty`
2. 进入 **用户中心 → 账户设置** 查看并复制 API Key（32 位十六进制串）
3. 确保账户余额 ≥ $0.05（通用短信取号占号费 $0.02/次）

```bash
export API_KEY='YOUR_API_KEY'
export BASE='https://www.psyawqnx.beauty/web/index.php'
```

---

## 二、协议规范

| 项目 | 说明 |
|------|------|
| Base URL | `https://www.psyawqnx.beauty/web/index.php` |
| 路由格式 | URL 参数 `?r=<controller>/<action>` |
| 数据格式 | JSON 响应；请求参数支持 GET query 或 POST form-urlencoded |
| 字符集 | UTF-8 |
| 时间戳 | Unix 秒级（Asia/Shanghai） |
| 金额 | 字符串小数，保留 2 位 |
| HTTP 超时建议 | 15 秒；上游通道波动时最多 30 秒 |
| 重试建议 | 仅对 `code=429` 或上游 5xx 重试；首次 2 秒，指数退避上限 10 秒 |

---

## 三、鉴权

两种方式任选其一（同时存在时 `X-API-KEY` 优先）：

| 方式 | 位置 | 示例 |
|------|------|------|
| URL 参数 | `apikey` | `?r=open/balance&apikey=abc123...` |
| 请求头 | `X-API-KEY` | `X-API-KEY: abc123...` |

**无需认证的端点**：`open/ping`、`open/status`

鉴权失败返回：

| 场景 | code | msg |
|------|------|-----|
| 缺少 apikey | 401 | 缺少 apikey（参数或 X-API-KEY 请求头） |
| 密钥无效或已停用 | 401 | apikey 无效或已停用 |

---

## 四、快速开始（10 分钟跑通）

### 第一步：先确认供应商状态（无需密钥）

```bash
curl -s "$BASE?r=open/ping"
# {"code":0,"msg":"pong","timestamp":1795100948,"timezone":"Asia/Shanghai","version":"2.0.0"}

curl -s "$BASE?r=open/status"
# 返回当前启用供应商、各自支持能力、汇率、限流配置
```

### 第二步：鉴权测试 + 余额查询

```bash
curl -s "$BASE?r=open/balance&apikey=$API_KEY"
# {"code":0,"msg":"success","data":{"username":"xxx","balance":"197.63"}}

# 也可以用请求头
curl -s -H "X-API-KEY: $API_KEY" "$BASE?r=open/balance"
```

### 第三步：搜索可买到的号码

```bash
# 统一国家列表（跨供应商规范化，带 ISO 码/有货标记）
curl -s "$BASE?r=open/countries_v2&apikey=$API_KEY"

# 按服务搜索（如 "微信"）
curl -s -G "$BASE?r=open/projects" \
  --data-urlencode "kw=微信" \
  --data-urlencode "page_size=5" \
  --data-urlencode "apikey=$API_KEY"

# 租号套餐
curl -s "$BASE?r=open/rent_options&apikey=$API_KEY"
```

> ⚠️ `projects` 返回的 `key` 是 HMAC 签名值，必须原样传回下单接口，超过 30 分钟可能失效。

### 第四步：完整取号链路

```bash
# 4.1 下单取号
curl -s -X POST "$BASE?r=open/number" \
  -d "apikey=$API_KEY" \
  -d "key=K45mS8k2dVn9A..."

# 返回: {"order_no":"O2026...","number":"17139763817","amount":0.25,"expire_at":...}

# 4.2 轮询拉验证码（建议 2~3 秒一次，最多 30 次）
curl -s -X POST "$BASE?r=open/sms" \
  -d "apikey=$API_KEY" \
  -d "order_no=O2026..."
# status=wait  短信还没到
# status=success  {"sms_code":"839217"}

# 4.3 释放并退款（取号满 2 分钟后）
curl -s -X POST "$BASE?r=open/release" \
  -d "apikey=$API_KEY" \
  -d "order_no=O2026..."
# 返回: {"refund":0.25,"balance":...}
```

### 第五步：通用短信（关键词匹配）链路

```bash
# 5.1 取号（占号费 $0.02/次）
curl -s -X POST "$BASE?r=open/keyword_request" \
  -d "apikey=$API_KEY" \
  -d "keyword=验证码" \
  -d "country=china" \
  -d "provider=luban"
# 返回: {"order_no":"K2026...","phone":"19907024796","amount":0.02}

# 5.2 拉短信（关键词匹配，按条计费）
curl -s -X POST "$BASE?r=open/keyword_sms" \
  -d "apikey=$API_KEY" \
  -d "order_no=K2026..."
# status=wait      未匹配，不扣费
# status=success   收到匹配短信，已扣费
# status=blocked   运营商屏蔽，自动退回占号费

# 5.3 释放（未收到有效码时）
curl -s -X POST "$BASE?r=open/keyword_release" \
  -d "apikey=$API_KEY" \
  -d "order_no=K2026..."
```

### 第六步：租号链路

```bash
# 下单租号
curl -s -X POST "$BASE?r=open/rent_number" \
  -d "apikey=$API_KEY" -d "key=..." -d "minutes=60"

# 租号期间持续拉短信
curl -s -X POST "$BASE?r=open/rent_sms" -d "apikey=$API_KEY" -d "order_no=RT2026..."

# 主动结束（不退费，上游按分钟扣费）
curl -s -X POST "$BASE?r=open/rent_release" -d "apikey=$API_KEY" -d "order_no=RT2026..."
```

### 第七步：速率限制 & 远程调试

```bash
# 查看当前窗口已用/剩余次数
curl -s "$BASE?r=open/rate_limit&apikey=$API_KEY"
# {"limit":60,"window_sec":60,"used":3,"remaining":57,"reset_at":1795101069}

# 远程直接打上游接口排查问题
curl -s -X POST "$BASE?r=open/test&apikey=$API_KEY" \
  -d "provider=luban" -d "endpoint=getBalance"
# 返回上游原始响应 + 耗时 ms
```

---

## 五、速率限制

- 默认 **60 次/分钟/用户**（系统参数 `openapi_rate_limit` 可调）
- 算法：滑动窗口，基于 `api_logs` 表统计
- **健康检查端点**（ping/status）不计数
- 超限返回：HTTP 200 + `code=429`

自助查询：`GET open/rate_limit`

---

## 六、错误码与状态语义

### 顶层 code

| code | 含义 | 典型场景 |
|------|------|----------|
| 0    | 业务成功 | 绝大多数成功响应 |
| 1    | 业务逻辑失败 | 参数缺失、余额不足、订单已释放、上游暂不可用 |
| 400  | 无效路由 | `r=` 不匹配任何端点 |
| 401  | 鉴权失败 | 密钥缺失或无效 |
| 429  | 限流拒绝 | 超过每分钟上限 |

> 注：当前所有响应 HTTP 状态码均为 200，区分业务状态请用 `code` 字段。

### 子系统业务状态

#### 短信拉取状态（sms/keyword_sms）

| status | 含义 | 是否扣费 |
|--------|------|----------|
| `wait` | 上游暂未返回匹配短信 | 否 |
| `success` | 收到有效短信 | 是 |
| `blocked` | 运营商屏蔽，平台自动退款 | 否（已退占号费） |

#### 普通接码订单（orders）

| status | 含义 |
|--------|------|
| 0 | 进行中（取号成功，等待释放/收码） |
| 1 | 已收码（成功拿到验证码） |
| 2 | 已释放并退款 |
| 3 | 已释放不退余额（isms 规则 / 上游返回已释放） |

#### 通用短信订单（keyword_orders）

| status | 含义 |
|--------|------|
| 0 | 进行中（占号成功，等待匹配短信） |
| 1 | 已收码（首条/按次匹配成功） |
| 2 | 已释放 |
| 3 | 屏蔽退款关闭 |

#### 租号订单（rent_orders）

| status | 含义 |
|--------|------|
| 0 | 租号中 |
| 1 | 已结束 |

---

## 七、返回格式

成功：

```json
{"code": 0, "msg": "success", "data": { ... }}
```

业务失败：

```json
{"code": 1, "msg": "余额不足，请先充值", "data": null}
```

认证/限流失败：

```json
{"code": 401, "msg": "apikey 无效或已停用", "data": null}
```

---

## 八、接口全量定义

### 健康检查与状态（无需认证）

#### GET `open/ping`

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 固定 0 |
| msg | string | 固定 `"pong"` |
| timestamp | int | 服务器时间戳 |
| timezone | string | Asia/Shanghai |
| version | string | API 版本 |

---

#### GET `open/status`

系统状态总览。返回：version、server_time、fx_rate（CNY→USD）、rate_limit、refund_min（秒）、keyword_fee、providers（按供应商索引的启用状态/支持能力/上游地址）。

每个供应商条目：`code, name, enabled, desc, supports{rent, keyword, blacklist}, base_url`

---

### 状态与能力查询（需认证）

#### GET `open/balance`

返回 `{username, balance}`，balance 为字符串小数。

---

#### GET `open/providers`

供应商能力清单，比 `status` 多 `config_fields` 和 `supports.multi_acct`。

---

#### GET `open/rate_limit`

返回 `{limit, window_sec, used, remaining, reset_at}`。

---

### 查询类

#### GET `open/countries`

旧版国家列表（仅中文），跨供应商合并去重。建议用 `countries_v2`。

---

#### GET `open/countries_v2`

统一国家列表，缓存 10 分钟。

| 参数 | 必填 | 说明 |
|------|------|------|
| force | 否 | `1` 强制刷新缓存 |

每个条目：`key（唯一键）, name, name_en, name_cn, code（ISO 码）, has_stock, providers`

---

#### GET `open/projects`

搜索服务项目（分页），返回 HMAC 签名的 `key` 用于下单，自动应用当前用户折扣率，隐藏内部成本。缓存 60 秒。

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| kw | 否 | - | 关键词 |
| country | 否 | - | 国家（精确匹配） |
| page | 否 | 1 | 页码 |
| page_size | 否 | 10 | 每页条数，最大 50 |
| force | 否 | - | `1` 强制刷新缓存 |

---

#### GET `open/rent_options`

可租地区与套餐。每个地区含 `packages` 数组（`minutes, price, key`）。

---

#### GET `open/orders` / `open/rent_orders`

分页查询历史订单。参数：`page, page_size（默认 20，最大 50）`。

---

### 接码取号链路

#### POST `open/number`

| 参数 | 必填 | 说明 |
|------|------|------|
| key | 是 | `open/projects` 返回的 HMAC key |

返回：`order_no(O前缀), number, request_id, service_name, amount, expire_at`

典型失败：产品已失效、余额不足、请求号码失败（含上游无库存）。

---

#### POST `open/sms`

| 参数 | 必填 | 说明 |
|------|------|------|
| order_no | 是 | 取号返回的订单号 |

返回：`order_no, status(success/wait), sms_code`

---

#### POST `open/release`

| 参数 | 必填 | 说明 |
|------|------|------|
| order_no | 是 | 取号返回的订单号 |

返回：`order_no, refund, balance, auto(可选)`

**释放前置条件**：未收码 + 取号满 120 秒 + 未被释放过 + 非 isms 供应商。

---

### 租号链路

#### POST `open/rent_number`

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| key | 是 | - | `open/rent_options` 返回的 HMAC key |
| minutes | 否 | 60 | 时长（30/60/360/720/1440） |

返回：`order_no(RT前缀), number, rent_id, minutes, amount, expire_at`

---

#### POST `open/rent_sms`

| 参数 | 必填 | 说明 |
|------|------|------|
| order_no | 是 | 租号订单号 |

返回：`status, list（短信条目数组）`

---

#### POST `open/rent_release`

| 参数 | 必填 | 说明 |
|------|------|------|
| order_no | 是 | 租号订单号 |

上游释放成功后结束租号。租号费用不退。

---

### 通用短信（关键词匹配）链路

#### POST `open/keyword_request`

| 参数 | 必填 | 说明 |
|------|------|------|
| keyword | **是** | 短信关键词（用于过滤上游返回内容） |
| provider | 否 | 指定供应商（luban/hog/hero），不指定自动选 |
| country | 否 | 国家名 |
| province | 否 | 省份/地区 |
| phone | 否 | 指定号码（limit_only=1 时生效） |
| limit_only | 否 | `1` 只允许指定号码 |
| dup_filter | 否 | `1` 上游侧开启去重过滤 |
| card_type | 否 | 卡类型过滤 |

返回：`order_no(K前缀), phone, keyword, amount`（占号费固定 $0.02）

---

#### POST `open/keyword_sms`

| 参数 | 必填 | 说明 |
|------|------|------|
| order_no | 是 | 通用短信订单号 |

返回：`status, sms_code, content, order_no, amount, billed, list, msg`

**行为**：首条匹配扣费；后续轮询同 content 不扣费；运营商屏蔽自动退占号费。

---

#### POST `open/keyword_release`

| 参数 | 必填 | 说明 |
|------|------|------|
| order_no | 是 | 通用短信订单号 |

前置条件：未被释放 + 未收到有效关键词短信。占号费不退。

---

#### GET `open/keyword_numbers` / `open/keyword_history`

进行中号码（最多 100 条）/ 历史记录（最近 100 条）。

---

### 批量取号

#### POST `open/batch`

| 参数 | 必填 | 说明 |
|------|------|------|
| action | 是 | `number` 或 `rent_number` |
| items | 是 | 数组或 JSON 字符串，最多 10 项；每项含 `key`，rent_number 时需 `minutes` |

返回：`total, success, failed, results`（每条结果含 `index, code, data/msg`）

---

### 在线测试

#### POST `open/test`

直接调用上游供应商接口，返回原始响应和耗时。

| 参数 | 必填 | 说明 |
|------|------|------|
| provider | 是 | 供应商标识（luban/hog/hero/smsman/isms） |
| endpoint | 是 | 上游接口名（不在实现列表中会返回可用清单） |
| 其他 | 否 | 透传给上游的参数 |

返回：`provider, endpoint, cost_ms, result（上游原始响应）`

---

## 九、订单状态机

### 普通接码订单

```
  ┌─────────────────────┐      sms_code 有值       ┌─────────────────┐
  │  status=0  进行中    │ ──────────────────────► │ status=1 已收码 │
  │                     │                         │  完结            │
  └─────────────────────┘                         └─────────────────┘
          │
          │ release（取号满 refund_min 秒 + sms_code 空）
          ▼
  ┌─────────────────────┐
  │  status=2 已释放退款 │ ←── 上游自动释放也会被平台检测到后跟退
  └─────────────────────┘
          │
          │ isms 供应商规则 / 上游返回已释放状态
          ▼
  ┌─────────────────────┐
  │ status=3 已释放不退  │
  └─────────────────────┘
```

### 通用短信订单

```
  ┌─────────────────────┐     关键词匹配短信        ┌─────────────────┐
  │ status=0  进行中     │ ─────────────────────►  │ status=1 已收码 │
  │ (占号 $0.02)        │                          │ 按条扣费        │
  └─────────────────────┘                          └─────────────────┘
          │                                                  │
          │ release（未收有效码）                               │ 收到运营商屏蔽短信
          ▼                                                  ▼
  ┌─────────────────────┐                           ┌─────────────────┐
  │ status=2 已释放      │                           │ status=3 屏蔽   │
  │ 占号费不退           │                           │ 自动退占号费    │
  └─────────────────────┘                           └─────────────────┘
```

### 租号订单

```
  status=0（租号中） ───── 主动 release 或 expire_at 到期 ─────► status=1（已结束）
```

---

## 十、计费规则

### 普通接码取号

| 场景 | 费用 | 退款 |
|------|------|------|
| number 成功 | `projects` 返回的 `price`（已应用用户折扣） | - |
| release 成功 | - | 退回已扣全额（isms 供应商除外） |
| 释放门槛 | 取号满 120 秒后才能释放 | - |
| 上游自动释放 | - | 平台检测到后自动跟退 |

### 租号

| 场景 | 费用 | 退款 |
|------|------|------|
| rent_number 成功 | `rent_options` 价格 × minutes | - |
| rent_release | - | **不退**（上游按分钟扣费，已消耗） |

### 通用短信

| 场景 | 费用 | 退款 |
|------|------|------|
| keyword_request | 固定占号费 **$0.02** | - |
| keyword_sms（首条匹配） | 按条计费，基于上游成本应用折扣 | - |
| keyword_sms（后续匹配） | 同上 | - |
| keyword_sms（重复内容） | 不扣费 | - |
| keyword_release | - | **不退**（屏蔽场景除外） |
| 自动过期（24 小时） | - | 自动退回占号费 |

### 折扣机制

每个用户可配置独立折扣率，`projects`、`number`、`keyword_sms` 均使用 `site_price()` 统一计算，**展示价与实际扣费同源**。

---

## 十一、多语言示例

### PHP

```php
<?php
$base = 'https://www.psyawqnx.beauty/web/index.php';
$key  = 'YOUR_API_KEY';

// 余额查询
$ch = curl_init("$base?r=open/balance&apikey=$key");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $data['data']['balance'];
```

### Python

```python
import requests, time, random

BASE = 'https://www.psyawqnx.beauty/web/index.php'
KEY  = 'YOUR_API_KEY'

def call(ep, method='GET', **kwargs):
    params = {'apikey': KEY}
    params.update(kwargs)
    if method == 'GET':
        r = requests.get(f"{BASE}?r={ep}", params=params, timeout=15)
    else:
        r = requests.post(f"{BASE}?r={ep}", data={**params, **kwargs}, timeout=15)
    body = r.json()
    if body['code'] != 0:
        raise Exception(f"[{r.status_code}] {body['msg']}")
    return body['data']

# 完整链路：搜索 → 取号 → 轮询拉码 → 释放
p = call('open/projects', kw='微信', page=1, page_size=5)['list'][0]
order = call('open/number', method='POST', key=p['key'])
for _ in range(30):
    sms = call('open/sms', method='POST', order_no=order['order_no'])
    if sms['status'] == 'success':
        print(f"验证码: {sms['sms_code']}"); break
    time.sleep(2 + random.random())
else:
    call('open/release', method='POST', order_no=order['order_no'])
```

### Go

```go
package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "strings"
    "time"
)

const (
    base = "https://www.psyawqnx.beauty/web/index.php"
    key  = "YOUR_API_KEY"
)

func call(ep, method string, body url.Values) (string, error) {
    u := base + "?r=" + ep + "&apikey=" + key
    var req *http.Request
    var err error
    if method == "POST" {
        req, err = http.NewRequest("POST", u, strings.NewReader(body.Encode()))
        req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
    } else {
        req, err = http.NewRequest("GET", u, nil)
    }
    if err != nil { return "", err }
    client := &http.Client{Timeout: 15 * time.Second}
    resp, err := client.Do(req)
    if err != nil { return "", err }
    defer resp.Body.Close()
    b, _ := io.ReadAll(resp.Body)
    return string(b), nil
}

func main() {
    v := url.Values{}
    v.Set("keyword", "验证码")
    v.Set("country", "china")
    v.Set("provider", "luban")
    resp, _ := call("open/keyword_request", "POST", v)
    fmt.Println(resp)
}
```

---

## 十二、变更记录

### v2.0.0（当前版本）

**新增端点**：
- `open/ping` — 无需认证健康检查
- `open/status` — 无需认证系统总览
- `open/providers` — 需认证供应商能力清单
- `open/rate_limit` — 需认证速率限制查询
- `open/test` — 需认证在线测试（直接调上游接口）

**优化**：
- `countries_v2` 按国家规范化 key、去重、带 ISO 码/有货标记/供应商列表
- `projects` 返回 HMAC 签名 key、隐藏内部成本字段、自动应用用户折扣
- 通用短信独立子系统 `KeywordService`，与前台共用扣费/状态处理逻辑
- 统一 `serve()` 入口：所有端点走同一套鉴权/限流/日志/异常处理
- 参数脱敏日志：不记录 `apikey`，`key` 只保留前 24 字符

### v1.0（旧版，已弃用）

后台 `ApiController` 接口，仅供内部调用。外部请全部迁移到 v2。
