API 开发文档
完整 API 对接指南 · 24 个接口 · v2.0
接码平台 · API 对接文档 v2.0
本文档为接码平台(API v2)完整对接指南,覆盖鉴权、协议、快速跑通、全量接口定义、状态机与计费规则。 最后更新:2026-11-20 权威源:OpenController.php + KeywordService.php
目录
- 一、准备工作
- 二、协议规范
- 三、鉴权
- 四、快速开始(10 分钟跑通)
- 五、速率限制
- 六、错误码与状态语义
- 七、返回格式
- 八、接口全量定义
- 健康检查与状态(无需认证)
- 状态与能力查询(需认证)
- 查询类
- 接码取号链路
- 租号链路
- 通用短信(关键词匹配)链路
- 批量取号
- 在线测试
- 九、订单状态机
- 十、计费规则
- 十一、多语言示例
- 十二、变更记录
一、准备工作
- 注册/登录接码平台
https://www.psyawqnx.beauty - 进入 用户中心 → 账户设置 查看并复制 API Key(32 位十六进制串)
- 确保账户余额 ≥ $0.05(通用短信取号占号费 $0.02/次)
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 分钟跑通)
第一步:先确认供应商状态(无需密钥)
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"
# 返回当前启用供应商、各自支持能力、汇率、限流配置
第二步:鉴权测试 + 余额查询
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"
第三步:搜索可买到的号码
# 统一国家列表(跨供应商规范化,带 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 分钟可能失效。
第四步:完整取号链路
# 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":...}
第五步:通用短信(关键词匹配)链路
# 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..."
第六步:租号链路
# 下单租号
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..."
第七步:速率限制 & 远程调试
# 查看当前窗口已用/剩余次数
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 | 已结束 |
七、返回格式
成功:
{"code": 0, "msg": "success", "data": { ... }}
业务失败:
{"code": 1, "msg": "余额不足,请先充值", "data": null}
认证/限流失败:
{"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
$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
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
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。