H5活体实名核验

业务介绍

H5视频活体认证产品，主要的应用在H5场景中，提供了三大功能：

• 通过开发者新录制并上传一个视频，来进行活体检测的判断，并解析出人脸图片。相对于APP有动作校验+静默图片活体、静默图片活体这两种方式，H5视频活体方案比APP方案更加灵活，同时比单张图片活体方式更加安全。
• 通过开发者提供的姓名和身份证号码，验证是否是同一人。
• 对视频活体检测得到的活体分数，如果高于开发者所默认的活体阈值，该产品会对视频中检测出的人脸信息，判断是否与开发者提供的姓名和身份证信息做检验，判断是否是同一人。

交互流程：

用户通过在页面上填写姓名，身份证号信息，并提交视频后，可以在页面上看到姓名，身份证号，视频中人脸是否为同一人。并可以通过sdk调用获取认证会话结果下载到视频中解析的人脸图片。

这里为了方便您的理解，请点击如下链接查看演示：

点我查看详细流程

获取认证会话入口

根据票据Id获取认证会话TOKEN，并获取认证会话地址。

一、请求说明

• 请求地址：http://api.spiderid.cn/api/router/rest，https://api.spiderid.cn/api/router/rest

• 服务接口名称(即公共参数method的值)： liveness.verifyToken.get

• 请求方式：GET，POST

二、请求参数

名称	类型	是否必须	描述
ticketId	String	是	票据id(随机字符串，唯一)
bizScene	String	是	业务场景(详情见字段解释)
attr	String	是	扩展参数(json字符串)(详情见字段解释)

• 字段解释

• bizScene 业务场景介绍

业务字段	业务场景介绍
LIVENESS_H5	H5活体检测

• attr 目前在H5场景时，需要传递扩展参数，具体如下表

H5扩展参数	类型	是否必填	H5扩展参数解释	备注
realname	String	否	姓名	例如: 张三；参数支持数据加密，详情参照加解密方法说明
idcard	String	否	身份证号	例如：412828200011113618；参数支持数据加密，详情参照加解密方法说明
livenessRate	String	否	活体分值阈值	默认0.393241(活体检测分数大于该值时才会进行人脸比对)
successPage	String	否	成功跳转地址 详情	认证成功后，跳转地址，GET请求访问开发者网站地址
errorPage	String	否	失败跳转地址 详情	认证失败后，跳转地址，GET请求访问开发者网站地址
callback	String	是	回调地址 详情	回调时，POST请求访问（回调地址+请求参数（ticketId）），程序执行完后必须打印输出：success

请求示例：

https://api.spiderid.cn/api/router/rest?
ticketId=XXX
&bizScene=XXX
&attr=XXX
&<[公共请求参数]>

三、响应参数

data 结果信息	类型	描述
verifyToken	String	认证Token
verifyDurationSeconds	Integer	认证有效时间（单位秒）
verifyPageUrl	String	认证流程页面入口 URL

四、成功示例

JSON示例

{
   "code": 0,
    "requestId":"dsd24...",
    "message": "success",
    "data": {
        "verifyToken":"g6gh8v0epwgvNT3CP3D7IdS8GMkl2hyB",
        "verifyDurationSeconds":1800,
        "verifyPageUrl":"https://h5api.spiderid.cn/liveness-auth-h5/auth-info/g6gh8v0epwgvNT3CP3D7IdS8GMkl2hyB"
    }
}

五、失败示例

JSON示例

{
  "code": 10005,
  "requestId":"b0c26c...",
  "message": "请求参数(ceshi0098)重复"
}

获取认证会话状态

根据票据Id获取认证会话状态

一、请求说明

• 请求地址：http://api.spiderid.cn/api/router/rest，https://api.spiderid.cn/api/router/rest

• 服务接口名称(即公共参数method的值)： liveness.verifyToken.status

• 请求方式：GET，POST

二、请求参数

名称	类型	是否必须	描述
ticketId	String	是	票据id(随机字符串，唯一)

请求示例：

https://api.spiderid.cn/api/router/rest?
ticketId=XXX
&<[公共请求参数]>

三、响应参数

data 结果信息	类型	描述
status	String	认证状态

• 字段解释

• status 认证状态介绍

字段	状态介绍
CREATE	未认证
ACTION	认证中
OVER	完成认证
INVALID	已失效

四、成功示例

JSON示例

{
   "code": 0,
    "requestId":"dsd24...",
    "message": "success",
    "data": {
        "status":"OVER"
    }
}

五、失败示例

JSON示例

{
  "code": 10023,
  "requestId":"dsd24...",
  "message": "认证记录不存在"
}

获取认证会话结果

根据票据Id获取认证会话结果,状态为OVER时，才能获取到认证结果。

一、请求说明

• 请求地址：http://api.spiderid.cn/api/router/rest，https://api.spiderid.cn/api/router/rest

• 服务接口名称(即公共参数method的值)： liveness.verifyToken.result

• 请求方式：GET，POST

二、请求参数

名称	类型	是否必须	描述
ticketId	String	是	票据id(随机字符串，唯一)

请求示例：

https://api.spiderid.cn/api/router/rest?
ticketId=XXX
&<[公共请求参数]>

三、响应参数

data 结果信息	类型	描述
result	String	认证结果(json字符串)
certificate	String	证书，不一定存在

• 字段解释

• result H5场景返回的认证结果是json字符串，其中包括以下数据

认证结果字段	字段类型	字段解释
livingScore	Double	活体分数
faceScore	Double	人脸比对分数
faceAdvise	String	人脸比对建议
pictures	String[]	解析的图片，临时url，有效期一天

四、成功示例

JSON示例

{
   "code": 0,
    "requestId":"dsd24...",
    "message": "success",
    "data": {
        "result":"{"faceAdvise":"系统判断为不同人","livingScore":"0.997323","faceScore":"0.03","pictures":["...."]}"
    }
}

五、失败示例

JSON示例

{
  "code": 10024,
  "requestId":"dsd24...",
  "message": "认证状态非法"
}

SDK 请求示例

获取认证会话入口

        //提供的url
        String url = "http://api.spiderid.cn/api/router/rest";
        //您的appKey
        String appkey = "XXX";
        //您的appSecret
        String secretKey = "XXX";
//
//        1.默认客户端
        ApiClient apiClient = new DefaultApiClient(url, appkey, secretKey);
        //2.调用出错自动重试客户端
        //AutoRetryApiClient apiClient = new AutoRetryApiClient(url, appkey, secretKey);
        VerifyTokenGetRequset req = new VerifyTokenGetRequset();
        //随机数，唯一
        req.setTicketId("XXX");
        //业务场景
        req.setBizScene(VerifyTokenGetRequset.BizScene.LIVENESS_H5);

        //扩展参数
        JSONObject json = new JSONObject();
        //认证成功回调地址
        json.put("callback","XXX");
        req.setAttr(json.toJSONString());

        //  配置此参数时,会对请求参数 attr.realname、attr.idcard 做加密
//       req.setEncMethod(EncryptMethod.SM4);
        try {
            VerifyTokenGetResponse response = apiClient.execute(req);
            //后续业务处理
        } catch (ApiException e) {
            e.printStackTrace();
        }

获取认证会话状态

        //提供的url
        String url = "http://api.spiderid.cn/api/router/rest";
        //您的appKey
        String appkey = "XXX";
        //您的appSecret
        String secretKey = "XXX";

//        1.默认客户端
        ApiClient apiClient = new DefaultApiClient(url, appkey, secretKey);
        //2.调用出错自动重试客户端
        //AutoRetryApiClient apiClient = new AutoRetryApiClient(url, appkey, secretKey);
        VerifyTokenStatusRequset req = new VerifyTokenStatusRequset();
        req.setTicketId("XXX");
        try {
            VerifyTokenStatusResponse response = apiClient.execute(req);
            //后续业务处理
        } catch (ApiException e) {
            e.printStackTrace();
        }

获取认证会话结果

        //提供的url
        String url = "http://api.spiderid.cn/api/router/rest";
        //您的appKey
        String appkey = "XXX";
        //您的appSecret
        String secretKey = "XXX";

        //1.默认客户端
        ApiClient apiClient = new DefaultApiClient(url, appkey, secretKey);
        //2.调用出错自动重试客户端
        //AutoRetryApiClient apiClient = new AutoRetryApiClient(url, appkey, secretKey);
        VerifyTokenResultRequset req = new VerifyTokenResultRequset();
        req.setTicketId("XXX");
        try {
            VerifyTokenResultResponse response = apiClient.execute(req);
            //后续业务处理
        } catch (ApiException e) {
            e.printStackTrace();
        }