首页 控制台 短信测试 插件下载 人脸认证测试

API 对接文档

本平台将短信验证码、人脸认证等服务聚合为统一 RESTful API。所有接口返回统一 JSON 格式：{"code":0,"msg":"success","data":{}}，其中 code=0 表示成功。

API 对接地址

https://api.fzyidc.com

所有接口统一使用 https://api.fzyidc.com。

快速对接步骤

步骤操作
1注册账号（手机号或邮箱），购买对应产品套餐获得额度
2控制台「API Key」页面生成对应产品类型的 API Key
3按下方接口说明调用

注意事项

项说明
短信支持范围目前仅支持中国大陆手机号（+86），暂不支持国际号码
API Key 安全Key 仅创建时完整显示一次，请妥善保存；可为 Key 配置 IP 白名单
计费调用成功扣 1 条额度，余额不足返回 402；人脸认证有免费次数（后台配置），超出后才扣费

一、鉴权说明

所有接口均使用 API Key 鉴权，请求头携带：

Authorization: Bearer {API_KEY}

API Key 在控制台「API Key」页面生成，每个产品类型（短信/实名认证）使用独立 Key，且 Key 仅创建时完整显示一次。

二、短信发送接口

POST/api/sms/send

鉴权：API Key（短信类型）

请求体

{
  "phone": "13800138000",
  "content": "123456"
}

参数说明

参数类型必填说明
phonestring是接收手机号（仅支持中国大陆 +86）
contentstring是验证码内容，直接传数字即可（如 123456）
对接提示：签名由平台「签名管理」统一配置和轮换，开发者无需配置签名。发送前需先通过「三、短信模板管理」提交模板并审核通过，系统自动使用开发者已通过的模板发送。如未提交模板，将使用平台默认模板。

响应示例

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

错误码

code说明
0发送成功
401API Key 无效或已禁用
402余额不足，请先购买额度
403API Key 类型不匹配（需使用短信类型 Key）
429请求过于频繁，请稍后再试

三、短信模板管理

鉴权：API Key（短信类型）

对接流程：
1. 开发者提交短信模板（名称、内容），系统自动提交阿里云审核；
2. 通过「查询模板」接口查看审核状态，阿里云审核通过后即可用于发送；
3. 发送短信时自动使用已通过的模板，签名由平台「签名管理」统一提供。
4. 相同内容的模板自动复用，不会重复申请阿里云（变量格式 {code} 和 ${code} 视为相同内容）。

3.1 提交模板

POST/api/sms/templates

请求体

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

参数说明

参数类型必填说明
namestring是模板名称
template_contentstring是模板内容，变量用 {code} 或 ${code} 均可，系统自动转换为阿里云要求的格式
template_varstring否模板变量名，默认 code
typestring否场景：login / register / bind / reset / custom（默认 custom）
callback_urlstring否审核结果回调地址，审核状态变化时系统自动 POST 通知
变量格式说明：模板内容中的变量占位符支持 {code} 和 ${code} 两种写法，提交阿里云时系统自动转换为 ${code} 格式。template_var 指定变量名，需与模板内容中的占位符一致。

响应示例（阿里云申请成功）

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

响应示例（相同内容已存在，自动复用）

{
  "code": 0,
  "msg": "模板已提交阿里云，等待审核",
  "data": {
    "id": 2,
    "name": "注册验证码",
    "template_code": "SMS_20250820_001",
    "status": 2,
    "status_text": "审核中"
  }
}

3.2 查询我的模板

GET/api/sms/templates

响应示例

{
  "code": 0,
  "msg": "success",
  "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"
    }
  ]
}

模板状态说明

status说明
0已禁用
1已通过（可用于发送）
2审核中（已提交阿里云，等待阿里云审核）
3已拒绝（阿里云审核未通过）
4待重试（阿里云提交失败，可重新提交）

签名由平台「签名管理」统一配置和轮换，开发者无需配置签名。修改/删除模板请到控制台操作。

3.3 审核结果回调通知

提交模板时传入 callback_url，审核状态变化时系统自动 POST 通知：

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

回调字段说明

字段说明
event事件类型，固定为 template_audit
template_id模板ID
template_code阿里云模板Code
status审核状态：approved（已通过）/ rejected（已拒绝）
reject_info拒绝原因（status=rejected 时有值）
timestamp通知时间戳

回调地址需返回 HTTP 2xx 状态码，否则视为通知失败。系统每5分钟自动检查审核状态并触发回调。

四、人脸认证接口

本平台提供三种人脸/实名认证通道，每种通道有独立的接口地址：

通道接口地址产品 / Key 类型价格说明
阿里云 H5 刷脸POST /api/id/verify/h5实名认证（id_verify）同价（共享）网页刷脸活体检测
支付宝认证POST /api/id/verify/alipay实名认证（id_verify）同价（共享，与 H5 共用一个 Key）支付宝扫码刷脸，实名与人脸一致
腾讯人脸核身POST /api/id/verify/wechat腾讯人脸核身（tencent_face）单独计价微信扫码，身份证拍摄 + 意愿确认
价格与 Key 说明：
1. 「阿里云 H5」与「支付宝认证」价格相同、共用一个 API Key（都属实名认证产品 id_verify），但接口地址不同；
2. 「腾讯人脸核身」为独立商品、独立价格、独立 API Key（产品 tencent_face）；
3. 生成 Key 时需选择对应产品类型；调用接口时 Key 的产品类型必须与接口匹配，否则返回 403。

4.1 阿里云 H5 刷脸

POST/api/id/verify/h5

鉴权：API Key（实名认证 id_verify 类型）

4.2 支付宝认证

POST/api/id/verify/alipay

鉴权：API Key（实名认证 id_verify 类型，与 H5 共用）

4.3 腾讯人脸核身

POST/api/id/verify/wechat

鉴权：API Key（腾讯人脸核身 tencent_face 类型）

请求体（三种接口通用）

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

参数说明

参数类型必填说明
namestring是真实姓名
id_numberstring是身份证号
callback_urlstring否认证结果异步回调地址（POST JSON）

响应示例

{
  "code": 0,
  "msg": "认证已创建",
  "data": {
    "order_no": "202608151200001234",
    "verify_url": "https://api.fzyidc.com/verify.html?orderNo=202608151200001234"
  }
}

查询认证结果

GET/api/id/verify/result?order_no=202608151200001234

鉴权：API Key（对应产品类型）

响应示例

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

异步回调（可选）

认证完成后，平台向 callback_url POST JSON：

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

认证结果状态码

status说明
pending已发起，等待用户扫脸
processing已初始化，扫脸进行中
passed认证通过
failed认证未通过
expired已过期（30 分钟内未完成扫脸），冻结额度自动退还

五、短信模板管理（用户端）

鉴权：用户 JWT Token（登录后获取）

提交模板审核

POST/api/user/sms-templates/submit
{
  "name": "登录验证码",
  "type": "login",
  "sign_name": "恒创联众",
  "template_code": "",
  "template_content": "您的验证码是code，请5分钟内使用",
  "template_var": "code"
}

提交后模板状态为"待审核"（status=2），管理员审核通过后变为"启用"（status=1）。template_code 可留空，审核通过后管理员手动填入阿里云模板ID。

查询我的模板

GET/api/user/sms-templates

返回用户自己的私有模板 + 所有公开模板。

编辑我的模板

POST/api/user/sms-templates/update
{"id":1,"name":"新名称","template_code":"SMS_yyyy"}

删除我的模板

POST/api/user/sms-templates/delete
{"id":1}

字段说明

字段说明
type场景类型：login（登录）、register（注册）、bind（绑定）、reset（重置）、custom（自定义）
sign_name阿里云短信签名
template_code阿里云短信模板ID（如 SMS_xxxx），可留空待管理员审核后填入
template_content模板内容（用于提交阿里云审核）
template_var模板变量名，默认 code

五、错误码说明

code说明
0成功
401未授权 / API Key 无效或已禁用
402余额不足
403API Key 与产品类型不匹配，或 IP 不在白名单内
429请求过于频繁（触发限流）
1101-1104短信参数错误（手机号/验证码为空或过长）
1241短信模板提交参数不完整
1301实名认证参数错误
1311-1315实名认证初始化错误（订单不存在、未配置插件等）
1321-1325实名认证查询结果错误（含已过期）