🚀 千帆信用实名认证 API 开发文档 v5.0

欢迎使用本系统。本文档将指导您如何通过 API 快速集成金融级人脸实名认证功能。

1. 创建认证会话 (Create Auth Session)

在您的服务器端调用此接口，创建一个人脸认证会话并获取认证链接。

请求方式	POST
接口地址	face/api.php?action=create_auth

请求参数

参数名	类型	必填	说明
api_key	String	是	您在后台分配的 API Key
name	String	是	用户真实姓名（需与身份证一致）
id_card	String	是	用户 18 位身份证号码
callback_url	String	否	认证完成后的异步通知地址

返回示例 (JSON)

{
  "success": true,
  "message": "认证成功会话已创建",
  "data": {
    "token": "a1b2c3d4e5f6...",
    "auth_url": "https://gulangvision.cn/face/liveness_check.html?token=a1b2c3d4e5f6...",
    "expire_in": 300
  }
}

代码示例 (PHP)

<?php
// 在服务器端调用 API
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://gulangvision.cn/face/api.php?action=create_auth');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'name' => '张三',
    'id_card' => '110101199001011234',
    'callback_url' => 'https://gulangvision.cn/callback.php'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    // 重定向用户到认证页面
    header('Location: ' . $result['data']['auth_url']);
} else {
    echo '错误: ' . $result['message'];
}
?>

2. 查询认证状态 (Query Status)

如果您没有配置回调地址，可以通过此接口主动查询认证状态。

请求方式	GET
接口地址	face/api.php?action=query_status

请求参数

参数名	类型	必填	说明
token	String	二选一	认证令牌（从创建会话时获取）
id_card	String	二选一	身份证号

返回示例 (JSON)

{
  "success": true,
  "data": {
    "is_finished": true,
    "name": "张*",
    "id_card": "110***********1234",
    "result_code": 1001,
    "score": 95,
    "result_text": "成功",
    "time": "2026-04-30 12:30:45"
  }
}

代码示例 (PHP)

<?php
// 查询认证状态
$token = $_SESSION['auth_token']; // 之前保存的 token
$url = "https://gulangvision.cn/face/api.php?action=query_status&token=" . urlencode($token);
$response = file_get_contents($url);
$result = json_decode($response, true);

if ($result['success'] && $result['data']['is_finished']) {
    if ($result['data']['result_code'] == 1001) {
        echo "认证成功！相似度: " . $result['data']['score'];
    } else {
        echo "认证失败: " . $result['data']['result_text'];
    }
} else {
    echo "认证尚未完成";
}
?>

3. 异步回调通知 (Callback)

当用户完成认证后，系统会向您的 callback_url 发送 POST 请求。

回调参数

参数名	类型	说明
key	String	API Key
token	String	认证令牌
name	String	用户姓名
id_card	String	身份证号
result_code	Integer	1001: 成功, 1002: 存疑, 1003: 失败, 其他: 错误
message	String	结果描述

回调处理示例 (PHP)

<?php
// callback.php
$key = $_POST['key'] ?? '';
$resultCode = intval($_POST['result_code'] ?? 0);
$message = $_POST['message'] ?? '';

// 验证来源
if ($key !== 'YOUR_API_KEY') {
    http_response_code(403);
    exit('Invalid key');
}

// 处理不同认证结果
if ($resultCode == 1001) {
    // 认证成功 - 更新用户状态
    update_user_verification_status('verified');
    log_success("认证成功");
} elseif ($resultCode == 1002) {
    // 认证存疑 - 需要人工审核
    flag_for_manual_review();
    log_warning("认证存疑，需要人工审核");
} elseif ($resultCode == 1003) {
    // 信息比对不匹配
    log_failure("信息比对不匹配");
} else {
    // 其他错误
    log_failure("认证失败: $message");
}

// 返回成功响应
echo 'OK';
?>

4. 计费与数据说明

计费规则

• 扣费时机：仅在认证服务 API 调用成功时扣费（HTTP 状态码 < 300）
• 扣费金额：根据账户设置的单价扣除（支持自定义单价）
• 查询不计费：查询认证状态不扣费
• 失败也扣费：认证失败也会扣费（因为调用了认证服务 API）
• 并发保护：扣费前会再次验证账户状态和余额，防止并发问题
• 同步扣费：扣费与认证服务 API 调用完全同步，确保数据一致性

5. 常见错误码 (Error Codes)

错误信息	原因及解决方案
无效的 API Key	Key 不存在，请检查是否正确。
API Key 已被禁用	该 Key 已被管理员封禁。
余额不足	账户余额为 0，请登录后台充值。
操作过于频繁，请稍后再试	同一身份证号 5 秒内只能认证一次。
缺少必要参数	缺少 api_key、name 或 id_card 参数。
无效的认证令牌或已过期	Token 不存在或超过 5 分钟有效期。
该认证已完成	Token 已被使用，每个 Token 只能使用一次。
认证服务暂时不可用	认证服务 API 调用失败，请稍后重试。
当前IP未被授权访问	IP不在白名单中，用户设置白名单

6. v5.0 新功能说明

6.1 IP白名单功能

为了提高系统安全性，系统支持设置IP白名单，只允许特定的IP地址调用API。

如何设置：

1. 登录用户中心，进入"Key管理"页面
2. 勾选"启用IP白名单限制"
3. 在文本框中输入允许访问的IP地址（每行一个）
4. 点击"保存设置"

示例：

192.168.1.100
10.0.0.50
172.16.0.1

6.2 API Key更换功能

如果您需要更换API Key（例如Key泄露），可以在线更换，无需联系管理员。

更换步骤：

1. 登录用户中心，进入"Key管理"页面
2. 输入新的API Key（4-32位字母和数字）
3. 点击"更换Key"
4. 系统会自动迁移所有历史记录到新Key