API 对接文档

最后更新：2026-10-05　｜　对接地址：https://jh.fzywl.cn

本平台把短信验证码、国际短信、语音验证码、人脸实名认证聚合为统一 RESTful API。所有接口统一返回：{"code":0,"msg":"success","data":{}}，code=0 表示成功。

接口一览（先看这张表）

对接三步

使用前须知

一、快速开始（5 分钟跑通）

cURL

curl -X POST https://jh.fzywl.cn/api/sms/send \
 -H "Authorization: Bearer 你的API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"phone":"13800138000","content":"123456"}'

PHP

<?php
$ch = curl_init('https://jh.fzywl.cn/api/sms/send');
curl_setopt_array($ch, [
  CURLOPT_POST      => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER   => [
    'Authorization: Bearer 你的API_KEY',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS   => json_encode([
    'phone'  => '13800138000',
    'content' => '123456',
  ]),
]);
$res = curl_exec($ch);
curl_close($ch);
echo $res;  // {"code":0,"msg":"success","data":{...}}

Python

import requests

r = requests.post(
  "https://jh.fzywl.cn/api/sms/send",
  headers={
    "Authorization": "Bearer 你的API_KEY",
    "Content-Type": "application/json",
  },
  json={"phone": "13800138000", "content": "123456"},
  timeout=10,
)
print(r.json())  # {"code":0,"msg":"success","data":{...}}

更多语言的示例（Java / Node.js / Go）见「插件下载」页，或直接参考上面的 cURL 写法。

二、鉴权与通用规则

2.1 鉴权

Key 在控制台「API Key」页生成，产品类型必须与接口一致；可另外配置 IP 白名单（留空=不限制），不在白名单内返回 403。

2.2 幂等：防重复发送 / 重复扣费

请求头带 X-Request-Id（或 X-Idempotency-Key，也可以放 body 的 request_id）时，同一个 request_id 只会真正发送一次：重复请求直接返回上次结果，并带 data.duplicated = true、data.deducted = false。

curl -X POST https://jh.fzywl.cn/api/sms/send \
 -H "Authorization: Bearer 你的API_KEY" \
 -H "Content-Type: application/json" \
 -H "X-Request-Id: order-20261005-0001" \
 -d '{"phone":"13800138000","content":"123456"}'

推荐每笔业务给一个唯一 ID（如订单号），避免网络重试导致重复发送/重复扣费。

2.3 限流与响应头

限额按 Key 维度（默认 20/分钟、200/小时、800/天），可在控制台「API Key → 限流」自助调整；填 0 表示该周期不限。超限返回 429。

2.4 调用网站（便于你排查 / 与客服对账）

后台调用日志会记录每次调用来自哪个网站，取值优先级：

2.5 状态查询 / 余额查询（只读，不计费不占限流）

用同一把 Key 鉴权；只能查自己账号下、且与 Key 产品类型一致的记录，否则返回 404 / 403。

可用于程序化做低额度告警 / 自动充值。

三、短信发送接口

鉴权：API Key（sms 类型）　｜　计费：成功扣 1 条额度

3.1 请求体

{
 "phone": "13800138000",
 "content": "123456",
 "callback_url": "https://你的域名/webhook"
}

3.2 参数说明

3.3 响应示例

{
 "code": 0,
 "msg": "success",
 "data": {
  "call_id": 123,
  "status": "success",
  "deducted": true,
  "third_party_id": "xxx",
  "response_time": 4
 }
}

3.4 发送结果回执推送（Webhook，免轮询）

配置回执地址后，每次调用的结果会自动 POST（JSON）到你的地址，无需轮询 /api/status。地址优先级：单次请求的 callback_url > 该 Key 上配置的默认地址（控制台「API Key → 回调」设置）。

推送内容

{
 "event": "send_result",
 "call_id": 123,
 "product_type": "sms",
 "status": "success",
 "third_party_id": "xxx",
 "third_party_code": "OK",
 "error_message": null,
 "phone_masked": "138****8000",
 "deducted": true,
 "charged": 0,
 "request_id": null,
 "timestamp": 1790976000
}

请求头

验签示例（务必校验，防止伪造回调）

// PHP
$raw  = file_get_contents('php://input');      // 原始 body，不要重新 json_encode
$secret = '你的回执密钥';
$expect = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$got  = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (!hash_equals($expect, $got)) { http_response_code(403); exit('bad sign'); }
$data = json_decode($raw, true);           // 验签通过再解析
// ...按 $data['call_id'] 更新你的业务状态

// Node.js (Express)
const crypto = require('crypto');
app.post('/webhook', express.raw({type: '*/*'}), (req, res) => {
 const raw = req.body.toString('utf8');
 const expect = 'sha256=' + crypto.createHmac('sha256', process.env.HOOK_SECRET).update(raw).digest('hex');
 if (req.get('X-Webhook-Signature') !== expect) return res.status(403).end('bad sign');
 const data = JSON.parse(raw);
 res.status(200).end('ok');             // 返回 2xx 才算投递成功
});

# Python (Flask)
import hmac, hashlib, json
from flask import request
@app.route('/webhook', methods=['POST'])
def hook():
  raw = request.get_data()             # 原始字节
  expect = 'sha256=' + hmac.new(b'你的回执密钥', raw, hashlib.sha256).hexdigest()
  if request.headers.get('X-Webhook-Signature') != expect:
    return 'bad sign', 403
  data = json.loads(raw)
  return 'ok', 200

3.5 内容与频率限制

3.6 错误码（常用）

四、国际短信（POST /api/sms/intl）

鉴权：API Key（sms_intl 类型，申请制）　｜　计费：按国家单价扣账户余额

发送国际号码（不含中国大陆）的验证码短信。产品与 Key 独立；计费方式与国内短信不同：按号码归属国家/地区单价，从账户余额实时扣费（不买条数套餐）。完整价目见 国际短信费率。

4.1 请求体

{
 "mobile": "+93701234567",
 "code": "1234"
}

4.2 参数说明

4.3 响应示例

{
 "code": 0,
 "msg": "success",
 "data": {
  "call_id": 321,
  "status": "success",
  "deducted": true,
  "third_party_id": "xxx",
  "response_time": 120,
  "country": "菲律宾",
  "unit_price": 0.35,
  "charged": 0.35
 }
}

4.4 注意事项

五、语音验证码接口

把验证码用电话语音念给用户，适合用户收不到短信的场景。两个通道各自独立接口、独立产品与 Key 类型：

5.1 请求体

{
 "mobile": "13800138000",
 "code": "123456"
}

5.2 参数说明

5.3 响应示例

{
 "code": 0,
 "msg": "success",
 "data": {
  "call_id": 456,
  "status": "success",
  "deducted": true,
  "third_party_id": "3375655611",
  "response_time": 5
 }
}

5.4 通道限制（上游原样返回，失败不扣费）

5.5 错误码（常用）

六、人脸实名认证接口

两种通道，价格相同、共用一把 id_verify Key，但接口地址不同：

另有 POST /api/id/verify（等价于 h5）、POST /api/id/verify/init、GET /api/id/verify/result、GET /api/id/verify/status。

6.1 请求体（两种通道通用）

{
 "name": "张三",
 "id_number": "110101199001011234",
 "callback_url": "https://你的回调地址"
}

6.2 响应示例（创建认证）

{
 "code": 0,
 "msg": "认证已创建",
 "data": {
  "order_no": "202608151200001234",
  "verify_url": "https://jh.fzywl.cn/verify.html?orderNo=202608151200001234"
 }
}
// 把 verify_url 给终端用户打开（或转成二维码），用户完成扫脸

6.3 查询认证结果

{
 "code": 0,
 "data": {
  "order_no": "202608151200001234",
  "status": "passed",
  "result": { "passed": true, "sub_code": "Z5050", "material_info": "" }
 }
}

6.4 异步回调（配置了 callback_url 时）

{
 "order_no": "202608151200001234",
 "status": "passed",
 "passed": true,
 "sub_code": "Z5050"
}

6.5 认证状态说明

计费：每个账号有后台配置的免费次数，超出后每次认证扣 1 次额度；认证失败/过期会退还。

七、短信模板管理

鉴权：API Key（sms 类型）　｜　不计费

7.1 提交模板

{
 "name": "登录验证码",
 "template_content": "您的验证码是{code}，5分钟内有效",
 "template_var": "code",
 "type": "login",
 "callback_url": "https://your-site.com/callback"
}

7.2 响应示例（申请成功 / 自动复用）

{
 "code": 0,
 "msg": "模板已提交，等待审核",
 "data": {
  "id": 1,
  "name": "登录验证码",
  "template_code": "SMS_20250820_001",
  "status": 2,
  "status_text": "审核中"
 }
}

7.3 查询我的模板

{
 "code": 0,
 "data": [
  {
   "id": 1,
   "name": "登录验证码",
   "type": "login",
   "template_content": "您的验证码是{code}，5分钟内有效",
   "template_code": "SMS_20250820_001",
   "status": 1,
   "status_text": "已通过",
   "created_at": "2026-08-20 12:00:00"
  }
 ]
}

7.4 模板状态

7.5 审核结果回调通知

{
 "event": "template_audit",
 "template_id": 1,
 "template_name": "登录验证码",
 "template_code": "SMS_20250820_001",
 "status": "approved",
 "status_text": "已通过",
 "reject_info": "",
 "timestamp": 1724150400
}

回调地址需返回 HTTP 2xx，否则视为通知失败。签名由平台「签名管理」统一配置轮换，开发者无需配置；修改/删除模板请到控制台操作。

八、错误码

九、常见问题与排查

附录：用户端控制台接口（JWT）

鉴权：用户登录后拿到的 JWT Token（请求头 Authorization: Bearer {token}），不是 API Key，仅用于控制台页面。

提交模板审核

{
 "name": "登录验证码",
 "type": "login",
 "template_code": "",
 "template_content": "您的验证码是code，请5分钟内使用",
 "template_var": "code"
}
// sign_name 由平台统一（昭通市昭阳区互动游戏乐园），无需也不允许自定义

提交后模板状态为 2（待审核），管理员审核通过后变为 1（启用）；template_code 可留空，审核通过后由管理员填入。客户短信与客户模板的签名由平台统一为「昭通市昭阳区互动游戏乐园」，客户无需填写。

查询 / 编辑 / 删除

字段说明

十、第三方登录 API（微信 / 支付宝 / 抖音）

让你的网站 / APP 支持「微信、支付宝、抖音」扫码登录：用户在我们这边完成授权，你的服务端拿一次性 code 换取用户身份。全程用你现有的 API Key 鉴权，不需要另外申请应用。

10.0 接口地址（完整）

10.1 前提

10.2 流程

10.3 获取授权页地址

POST https://jh.fzywl.cn/api/oauth/authorize-url
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "provider": "wechat",              // wechat / alipay / douyin
  "redirect_uri": "https://your-site.com/oauth/callback",
  "state": "随机串（可选，会原样回传）"
}

10.4 用 code 换用户身份

POST https://jh.fzywl.cn/api/oauth/token
Authorization: Bearer {API_KEY}
Content-Type: application/json

{ "code": "回调里拿到的 code" }

{
  "code": 0,
  "msg": "success",
  "data": {
    "provider": "wechat",
    "open_id": "该平台用户唯一 ID",
    "union_id": "",
    "nickname": "昵称",
    "avatar": "头像 URL",
    "user_id": 0
  }
}

user_id 固定为 0：登录 API 只返回第三方身份，不会在你的调用下创建方栀云账号。

10.5 错误码

10.6 注意事项

10.7 如何绑定回调域（控制台操作）

回调域是按 API Key 配置的：同一账号下不同 Key 可以配不同域名，互不影响。

更新日志

接口如有不兼容调整，会在此处同步说明。