# 实人认证时间戳/数字证书服务API

在验证用户身份信息（身份证号、姓名、人像）通过后签发具有法律效力的第三方可信时间戳/数字证书

# 一、公共参数

请求地址：http://api.spiderid.cn/api/router/rest，https://api.spiderid.cn/api/router/rest
服务接口名称(即公共参数method的值)： realid.idcard.detectionFace
请求方式：POST

# 二、请求参数(请求方式为post)

请求参数以表单形式提交，Content-Type值为: application/x-www-form-urlencoded;charset=utf-8

名称	类型	是否必须	描述
realname	String	是	身份证姓名，中文；参数支持数据加密，详情参照加解密方法说明
idcard	String	是	身份证号码，18位；参数支持数据加密，详情参照加解密方法说明
image	String	是	人脸照片base64位字符串，图片大小1024KB以内，2KB以上；参数支持数据加密，详情参照加解密方法说明
control	String	否	json字符串如 `{"quality_control":"NORMAL"}` .quality_control（照片质量控制）
issueType	String	是	签发类型默认`evc`，tsp 时间戳, evc 短效证书
digest	String	是	摘要值，SM3算法，tsp 时间戳证书时必传
event	String	否	事件描述,evc 短效证书时设置
async	String	是	是否开启异步签发,默认 `false` 为同步(将会影响性能)

字段解释

control 字段	类型	描述
quality_control	String	照片质量控制等级：NONE(不进行控制) LOW(较低的要求) NORMAL(一般的要求，默认) HIGH(较高的要求)

请求示例：

http或https://api.spiderid.cn/api/router/rest?
<[公共请求参数]>

realname=XXX&idcard=XXX&image=XXX...

# 三、响应参数

data结果信息	类型	描述
valid	Boolean	true比对成功(该字段已被废弃)
message	String	描述
incorrect	Integer	返回码
scoreMsg	String	分数建议
score	Double	incorrect为100时，才有该字段，两张照片的相似度（0到1），值越大相似度越高
score2	Double	incorrect为100，两张照片的相似度（0到1），值越大相似度越高
score3	Double	incorrect为100，两张照片的相似度（0到1），值越大相似度越高,推荐使用此字段
certificate	String	证书,签发类型 `evc` 时返回
signature	String	证书签名结果 base64编码 ,签发类型 `evc` 时并且`digest`不为空返回
trustedtimestamp	String	时间戳,签发类型 `tsp` 时返回

score 属性介绍:

判断说明	score	score2	score3
系统判断为不同人	score < 0.4	score < 0.40	score3 < 0.6
不能确定是否为同一人	0.40 ≤ score < 0.45	0.40 ≤ score2 < 0.60	0.60 ≤ score3 < 0.70
系统判断同一人	score >= 0.45	score2 ≥ 0.60	score3 ≥ 0.70

错误接受率 0.01%，阈值比对分数 0.7
注：错误接受率，又称误识率，即把某人误识为其他人的概率。

# 四、sdk用户注意事项

sdk版本大于等于1.15.0,增加响应参数score2,score属性区间改变为score2的区间,具体属性区间见参数描述

// 代码修改示例: score 分数判定改完 0.6
        IdcardDetectionFaceRequest req = new IdcardDetectionFaceRequest();
        // ...
        IdcardDetectionFaceResponse response = apiClient.execute(req);
        if (response.isSuccess() && null != response.getData()) {
            IdcardDetectionFaceResponse.Result data = response.getData();
            // incorrect 等于 100,比对成功,后续判断分数是否为同一人
            if (data.getIncorrect() == 100) {
                // sdk 版本 1.15.0 前(不包含1.15.0)
//                    if (data.getScore() >= 0.45) {
//                        // todo 系统判断为一人
//                    }

                // sdk 版本 1.15.0及以上, score 与score2一致,变更为0.6以上为同一人
                if (data.getScore() >= 0.6) {
                    // todo 系统判断为一人
                }
            }
        }

# 五、成功示例

JSON示例

{
  "code": 0,
  "requestId": "d022123ca86945fbb6562a8c90a416f1",
  "data": {
    "valid": true,
    "scoreMsg": "系统判断为同一人",
    "score": 0.81,
    "score2": 0.81,
    "incorrect": 100,
    "trustedtimestamp": "Mz...",
    "message":"比对成功"
  },
  "message": "success"
}

# 六、失败示例

JSON示例

{
  "code": 0,
  "requestId": "dsd24...",
  "data": {
      "message": '库中无此号' ,
      "incorrect": 102 ,
      "valid": false
  },
  "message": "success"
}

# 七、返回码说明(incorrect)

返回码	描述	是否收费
100	比对成功	是
101	身份证号码姓名不一致	是
102	库中无此号	是
103	身份核验成功，数据非法	是
104	数据非法	否
106	身份核验成功，人脸识别系统异常	否
107	照片质量不合格	否
108	上传图片文件过大	否
109	身份核验成功，库中无照片	是
110	身份核验成功，特征提取失败	是
111	身份核验成功，检测到多于一张人脸	是
112	身份核验成功，图片不合法	是
113	人像比对服务异常	否

103 身份核验成功，数据非法

核验中心已经进行了身份核验（姓名身份证号码一致），核验中心返回的错误:除库中无照片（109），特征提取失败（110），检测到多于一张人脸(111)，人脸识别系统异常(106)，图片不合法(112)以外的情况。

104 数据非法

核验中心未进行身份核验前图片校验，核验中心返回的错误:除照片质量不合格(107)，上传图片文件过大(108)，人像比对服务异常(113)以外的情况。

103，104区别

103证件号码一致，照片比对时报错；104未进行证件号校验，数据检验报错。

104，107区别

107检测到的核验中心错误；104未检测到的核验中心错误。

# SDK 请求示例

        //提供的url
        String url = "http://api.spiderid.cn/api/router/rest";

        //您的appKey
        String appkey = "XXX";

        //您的appSecret
        String secretKey = "XXX";

        //身份证姓名，注意不要有空格
        String realname = "XXX";

        //身份证号码是18位的，最后一位如果是大写X转换为x，注意不要有空格
        String idcard = "XXX";

        //图片转换成base64位字符串
        String image = null;

        //签发类型 默认evc，tsp 时间戳, evc 短效证书
        String issueType = "evc";

        try {
            image = Base64.encodeBase64String(FileUtils.readFileToByteArray(new File("D:/scb_photo.jpg")));
        } catch (IOException e) {
            e.printStackTrace();
        }

        //1.默认客户端
        ApiClient apiClient = new DefaultApiClient(url, appkey, secretKey);

        //2.调用出错自动重试客户端
        //AutoRetryApiClient apiClient = new AutoRetryApiClient(url, appkey, secretKey);

        IdcardDetectionFaceRequest req = new IdcardDetectionFaceRequest();

        req.setRealname(realname);

        req.setIdcard(idcard);

        req.setImage(image);

        //true 开启异步 false 关闭异步（默认）
        req.setAsync(false);

        //非必填参数，质量控制
        req.setQualityControl(QualityControl.NORMAL);

        // 配置此参数时,会对请求参数中的realname、idcard、image做加密
        //req.setEncMethod(EncryptMethod.SM4);

        try {

            IdcardDetectionFaceResponse response = apiClient.execute(req);

            //后续业务处理

        } catch (ApiException e) {

            e.printStackTrace();

        }

← 实名四要素身份时间戳/数字证书服务API 手机号实名核验数字证书服务API →