✆
接码云平台
↧ 下载 Markdown

API 开发文档

完整 API 对接指南 · 24 个接口 · v2.0

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

本文档为接码平台(API v2)完整对接指南,覆盖鉴权、协议、快速跑通、全量接口定义、状态机与计费规则。 最后更新:2026-11-20 权威源:OpenController.php + KeywordService.php


v2 豪猪兼容接入(现成软件推荐)

v2 采用豪猪风格的 api=动作 协议,原有对接豪猪的软件只需把接口地址换成下方入口、账号密码填本平台账号密码即可接入。差异:本平台支持全球国家、统一服务搜索、通用短信关键词、租号与邮箱,并且不会向下游返回任何上游供应商标识或成本字段。

入口与鉴权

项目说明
推荐入口https://api.psyawqnx.beauty/v2/(需完成域名解析与 SSL 证书)
兼容入口https://api.psyawqnx.beauty/web/index.php?r=v2/handle(子域名未切换时可先用此地址)
登录api=login&user=账号&pass=密码 → 返回 token 与 money
后续请求携带 token=登录返回的token;也兼容 apikey 与 X-API-KEY
响应语义code=0 成功;code=-1 等待接收短信;其他 code 为错误,msg 为说明。字段平铺在顶层,无 data 包裹。
# 登录
curl -s -G 'https://api.psyawqnx.beauty/v2/' \
  --data-urlencode 'api=login' \
  --data-urlencode 'user=YOUR_USERNAME' \
  --data-urlencode 'pass=YOUR_PASSWORD'

# 查询余额
curl -s -G 'https://api.psyawqnx.beauty/v2/' \
  --data-urlencode 'api=getSummary' \
  --data-urlencode 'token=YOUR_TOKEN'

v2 动作清单

分类api 参数主要参数 / 说明
账户login / getSummary登录换 token / 查询余额
全球国家getCountries跨通道聚合去重,返回 id/name/code,force=1 强刷
统一服务getProjectskw/service 中英文搜索,country、page、page_size;返回 sid/name/country/price
普通接码getPhone / getMessage / cancelRecvsid 下单;order_no 拉码/释放;等待返回 code=-1
号码列表getNumbers / getOrders进行中号码 / 历史订单
通用短信keywordPhone / keywordMessage / keywordRelease / keywordNumbers / keywordHistorykeyword 必填,country 可选;支持按条扣费与关键词匹配
租号rentOptions / rentPhone / rentMessage / rentRelease / rentOrderssid 来自 rentOptions,minutes 可选
邮箱emailOffers / emailBuy / emailSms先按 site 查报价,再用 site+domain 购买,最后用 order_no 收码

与 open API 的差异

  • 协议差异:v2 用 api=动作 与平铺字段;原 open/* 继续保留,使用 ?r=open/xxx&apikey=... 与 code/msg/data 包裹。
  • 全球国家:v2 的 getCountries 聚合所有已启用通道并去重,不返回来源标识。
  • 统一服务:v2 的 getProjects 支持中英文关键词统一搜索,价格已按用户折扣计算。
  • 扩展能力:v2 原生支持通用短信、租号、邮箱;豪猪协议软件无需改协议即可使用。
  • 安全约束:v2 不返回 provider、upstream_provider、cost、cny_cost 等内部字段。

常用迁移映射

豪猪软件动作本平台 v2备注
loginloginuser/pass 换成平台账号密码
getSummarygetSummary返回 money
getCountriesgetCountries全球国家,无来源标识
getProjectsgetProjects返回 sid 供 getPhone 使用
getPhonegetPhone返回 phone/order_no
getMessagegetMessage返回 yzm,等待为 code=-1
cancelRecvcancelRecv释放并退款
(无对应)keyword* / rent* / email*本平台扩展能力

目录


一、准备工作

  1. 注册/登录接码平台 https://www.psyawqnx.beauty
  2. 进入 用户中心 → 账户设置 查看并复制 API Key(32 位十六进制串)
  3. 确保账户余额 ≥ $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。