二要素核验 API 文档

接口说明

二要素实名验证 API 接口，支持姓名和身份证号的真实性核验。适用于用户注册、实名认证、风控审核等场景。

准确率说明：本接口核验准确率约 80%，适用于一般性实名验证场景。

请求参数

参数说明

• key：您的接口访问密钥，用于身份鉴权与计费统计。请在控制台申请并妥善保管。
• realname：待验证的真实姓名，需与身份证上的姓名保持一致。
• idcard：待验证的18位身份证号码，支持末尾为X的大小写格式。
• source：数据源选择策略。默认 auto 表示系统自动选择最优数据源；如需强制使用特定数据源，可指定 source1 或 source2。

请求示例

基础请求

GET https://openapi.xunjinlu.fun/apis/2ys?key=sk_xxxxxxxxxxxxxxxx&realname=张三&idcard=110101199001011234

指定数据源请求

GET https://openapi.xunjinlu.fun/apis/2ys?key=sk_xxxxxxxxxxxxxxxx&realname=张三&idcard=110101199001011234&source=source1

PHP 示例

// 二要素核验接口调用示例
$url = 'https://openapi.xunjinlu.fun/apis/2ys';
$params = [
    'key'      => 'sk_xxxxxxxxxxxxxxxx',
    'realname' => '张三',
    'idcard'   => '110101199001011234',
    'source'   => 'auto'
];

$requestUrl = $url . '?' . http_build_params($params);
$response = file_get_contents($requestUrl);
$result = json_decode($response, true);

if ($result['success'] === true) {
    $data = $result['data'];
    if ($data['is_match'] === true) {
        echo "核验通过：姓名与身份证号一致";
    } else {
        echo "核验未通过：姓名与身份证号不一致";
    }
} else {
    echo "请求失败：" . $result['msg'];
}

响应说明

成功响应（信息一致）

{
    "success": true,
    "code": 100200,
    "msg": "校验完毕",
    "data": {
        "realname": "张三",
        "idcard": "110101199001011234",
        "sex": "男",
        "age": 34,
        "address": "北京市东城区",
        "birthday": "1990-01-01",
        "is_match": true,
        "desc": "一致",
        "res_code": 1
    }
}

成功响应（信息不一致）

{
    "success": true,
    "code": 100200,
    "msg": "校验完毕",
    "data": {
        "realname": "张三",
        "idcard": "110101199001011234",
        "sex": "男",
        "age": 34,
        "address": "北京市东城区",
        "birthday": "1990-01-01",
        "is_match": false,
        "desc": "不一致",
        "res_code": 2
    }
}

错误响应（参数缺失）

{
    "success": false,
    "code": 400,
    "msg": "参数错误：姓名和身份证号不能为空",
    "data": null
}

错误响应（服务异常）

{
    "success": false,
    "code": 500,
    "msg": "服务繁忙，请稍后重试",
    "data": null
}

响应字段说明

顶层响应字段

data 对象字段

业务错误码（errcode）

本平台使用统一的业务错误码（errcode）标识各类异常情况，与 HTTP 状态码相互独立。调用方请根据 errcode 进行相应的错误处理。

错误响应 JSON 示例

{
    "code": 0,
    "msg": "未提供调用密钥",
    "errcode": 11001
}

{
    "code": 0,
    "msg": "请求过于频繁，请稍后重试",
    "errcode": 11005
}

{
    "code": 0,
    "msg": "服务暂不可用",
    "errcode": 11017
}

注意事项

1. 密钥安全：请勿将密钥暴露在前端代码或公开仓库中，建议通过后端服务转发请求。
2. 频率限制：本接口限制每分钟约 25 次请求，超出限制将返回 errcode: 11005。
3. 数据源选择：默认使用 auto 模式，系统会自动选择最优数据源。如需强制指定数据源，请谨慎使用 source1 或 source2 参数。
4. 身份证格式：请确保传入的身份证号码为18位，末尾X支持大小写格式。
5. 准确率说明：本接口核验准确率约 80%，对于高安全性要求的场景，建议结合其他验证方式综合判断。