本文介绍如何通过DescribeFaceVerify接口查询App实人认证方案的认证结果。

接口说明

接口名:DescribeFaceVerify

服务地址:cloudauth.aliyuncs.com

请求方法:HTTPS POST和GET。

接口说明:当您收到回调通知之后,可以在服务端通过该接口获取相应的认证状态和认证资料。

请求参数

名称 类型 是否必选 描述 示例值
SceneId Long 认证场景ID。 1000000006
CertifyId String 实人认证唯一标识。 91707dc296d469ad38e4c5efa6a0****

返回数据

名称 类型 描述 示例值
RequestId String 请求ID。 130A2C10-B9EE-4D84-88E3-5384FF039795
Message String 请求信息的响应消息。 success
Code String 返回码,200指接口响应成功。详细认证结果判断请参见ResultObject.SubCode 200
ResultObject.Passed String 认证结果。取值:
  • T:通过。
  • F:不通过。
说明 判断认证结果请以 ResultObject.Passed字段为准。
T
ResultObject.SubCode String 认证结果描述。更多信息,请参见ResultObject.SubCode错误码说明
说明 判断认证结果请以 ResultObject.Passed字段为准。
200
ResultObject.IdentityInfo String 认证的主体信息,一般的认证场景返回为空。 null
ResultObject.DeviceToken String 设备Token。 McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOxxxxxxx
ResultObject.MaterialInfo String 认证主体附件信息,主要为图片类材料。关于JSON格式,请参见下文中的返回示例。 {"faceAttack":"F","faceOcclusion":"F","facialPictureFront": {"faceAttackScore":0.00008597839769208804,"qualityScore":88.3615493774414,"verifyScore":50.28594166529785,"pictureUrl":"https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg","ossBucketName":"cn-shanghai-aliyun-cloudauth-1260051251634779","ossObjectName":"verify/1260051251634779/6ba7bcfccf33f56cdb44ed086f36ce3e0.jpeg"}}

返回示例

ResultObject.MaterialInfo的JSON格式示例

{
    //是否为攻击:攻击为T,非攻击为F。
    "faceAttack": "T",
    // 是否有脸部遮挡:有脸部遮挡为T,否则为F。
    "faceOcclusion": "F",
    // 认证的照片信息。
    "facialPictureFront": {
        // 人脸攻击分。
         "faceAttackScore": 0.00008597839769208804, 
        // 人脸和身份证照片比对分(仅当product code=ID_PLUS时,认证完成返回)。
        "idCardVerifyScore": 50.99797734769861,
        // 照片存放客户上海区域的OSS里,此为照片的bucket名。
        "ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779",
        // 照片存放客户上海区域的OSS里,此为照片的文件名。
        "ossObjectName": "verify/1260051251634779/03a081bd96328aedf83f635f39a50c57_0.jpeg",
        // 照片https地址,有效期15分钟,从查询时开始计时。
        "pictureUrl": "http://cn-shanghai-aliyun-cloudauth-1260051251634779.oss-cn-shanghai.aliyuncs.com/verify/1260051251634779/03a081bd96328aedf83f635f39a50c57_0.jpeg?Expires=1625371140&OSSAccessKeyId=STS.NTX1ngfr6Acg2Pmnn2RYM****&Signature=Hw5BF9WxJs6wI68IxKs41cxCU8****&security-token=CAISjgJ1q6Ft5B2yfSjIr5ftetTTi60X9qGMMHbcim5nXtZhu7GT1Dz2IH1PdXFgA%2Bgds%2Fswmm5U7vgalrkqEcEdHRGdN5YpsM8LrlzwO1h2TGRsq%2B5qsoasPETOITyZtZagToeUZdfZfejXGDKgvyRvwLz8WCy%2FVli%2BS%2FOggoJmadJlNWvRL0AxZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO4gEWq4bHm5fCskKD1Qenk7FO%2B9uuc6LJNZc8YM1NNP6ux%2FFze6b71ypd1gNH7q8ejtYfpGyW5oHHWwIMvErYbbaMrIV1WwZ9Z7knHaVAq%2BXwnOBkuuXYnIns0BdLMuZOSD7YQI2wYWEwgBcxt78agAF%2FHZbelNLYWtipAu5X5oG1t22SqIr1p3TMK5FrjDIVeWOppcxeRXtU%2BjR7hGcwd25scGhiraoxTXV3sxw%2F6dhFSswQ37O4j%2B%2FrCPtiGauqn2ZMdMj%2FvYwKb6KmpQqa%2BtR%2F9cxhS6hoIQRq0SUIfyXl5ZUiZbTjW22iwuX%2BPwzVCw%3D%3D",
        // 视频存放客户上海区域的OSS里,此为视频的文件名(仅当客户端设置视频参数时返回)。
        "ossVerifyVideoObjectName": "verify/1260051251634779/03a081bd96328aedf83f635****_verifyvideo_dcb7.mov",
        // 视频HTTPS地址,有效期15分钟,从查询时开始计时(仅当客户端设置视频参数时返回)。
        "verifyVideoUrl": "http://cn-shanghai-aliyun-cloudauth-1260051251634779.oss-cn-shanghai.aliyuncs.com/verify/1260051251634779/03a081bd96328aedf83f635f39a50c57__verifyvideo_dcb7.mov?Expires=1625371140&OSSAccessKeyId=STS.NTX1ngfr6Acg2Pmnn2RYM****&Signature=Hw5BF9WxJs6wI68IxKs41cxCU8****&security-token=CAISjgJ1q6Ft5B2yfSjIr5ftetTTi60X9qGMMHbcim5nXtZhu7GT1Dz2IH1PdXFgA%2Bgds%2Fswmm5U7vgalrkqEcEdHRGdN5YpsM8LrlzwO1h2TGRsq%2B5qsoasPETOITyZtZagToeUZdfZfejXGDKgvyRvwLz8WCy%2FVli%2BS%2FOggoJmadJlNWvRL0AxZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO4gEWq4bHm5fCskKD1Qenk7FO%2B9uuc6LJNZc8YM1NNP6ux%2FFze6b71ypd1gNH7q8ejtYfpGyW5oHHWwIMvErYbbaMrIV1WwZ9Z7knHaVAq%2BXwnOBkuuXYnIns0BdLMuZOSD7YQI2wYWEwgBcxt78agAF%2FHZbelNLYWtipAu5X5oG1t22SqIr1p3TMK5FrjDIVeWOppcxeRXtU%2BjR7hGcwd25scGhiraoxTXV3sxw%2F6dhFSswQ37O4j%2B%2FrCPtiGauqn2ZMdMj%2FvYwKb6KmpQqa%2BtR%2F9cxhS6hoIQRq0SUIfyXl5ZUiZbTjW22iwuX%2BPwzVCw%3D%3D",
        // 活体人脸质量分数。
        "qualityScore": 99.93476867675781,
        // 人脸和公安比对分数,阈值可参考下表详细说明。
        "verifyScore": 57.678396649466755
    },
    // 身份证OCR信息(仅当product code=ID_PLUS时,认证完成返回OCR识别的信息和图片)。
    "ocrIdCardInfo": {
        // 身份证字段信息。
    },
    "ocrPictureFront": {
        // 身份证OCR照片存放客户上海区域的OSS里,此为身份证OCR照片的Bucket名。
        "ossBucketName": "cn-shanghai-aliyun-cloudauth-1234567890",
        // 身份证OCR照片存放客户上海区域的OSS里,此为身份证OCR照片人脸面的文件名。
        "ossIdFaceObjectName": "verify/1234567890/f7ed1ef80ad1234fdsd95c66d83340cd_ocridface_b749.jpeg",
        // 身份证OCR照片人脸面的https地址,有效期15分钟,从查询时开始计时。
        "ossIdFaceUrl": "http://cn-shanghai-aliyun-cloudauth-1234567890.oss-cn-shanghai.aliyuncs.com/verify/1234567890/f7ed1ef80ad1234fdsd95c66d83340cd_ocridface_b749.jpeg?Expires=1625371165&OSSAccessKeyId=STS.NTGterbRtcVY7ykxixaQ6****&Signature=SqZoqBch%2BsdJefkabdaIJrPJWqtD%2FlmF****&security-token=CAISjdfgeJ1q6Ft5B2yfSjIr5fyP9%2FGj41V1JSyNV%2FanGktbd4aqInAmjz2IH1PdXFgA%2Bgds%2Fswmm5U7vgalrkqEcEdHRGdN5YpsM8LrlzwO30McmRsq%2B5qsoasPETOITyZtZagToeUZdfZfejXGDKgvyRvwLz8WCy%2FVli%2BS%2FOggoJmadJlNWvRL0AxZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO4gEWq4bHm5fCskKD1Qenk7FO%2B9uuc6LJNZc8YM1NNP6ux%2FFze6b71ypd1gNH7q8ejtYfpGyW5oHHWwIMvErYbbaMrIV1WwZ9Z7knHaVAq%2BXwnOBkuuXYnIns0BdLMuZOSD7YQI2wYWEwgBcxt78agAGe2a1NFO2XabhICqmUeN%2FLV25GuhaexEjjGL4sDC2VWjasWBmKzlXTQ6mHZoI9IhswopdGLLlWPC5ONnLNASWQEObAM28FAViS76clUdE8YVCMyU%2BuyFqLGeRNx4NjcPa%2FlOa9wsxjg4LwlfHKeXA3g0X%2BQQcRAqFc2j093K2r6A%3D%3D",
        // 身份证OCR照片存放客户上海区域的OSS里,此为身份证OCR照片国徽面的文件名。
        "ossIdNationalEmblemObjectName": "verify/1234567890/f7ed1ef80ad1234fdsd95c66d83340cd_ocridnationalemblem_a3hf.jpeg",
       // 身份证OCR照片国徽面的https地址,有效期15分钟,从查询时开始计时。
        "ossIdNationalEmblemUrl": "http://cn-shanghai-aliyun-cloudauth-1234567890.oss-cn-shanghai.aliyuncs.com/verify/1234567890/f7ed1ef80ad1234fdsd95c66d83340cd_ocridnationalemblem_a3hf.jpeg?Expires=1625371365&OSSAccessKeyId=STS.NTEz8oi35qJpxxX7no5gpGd****&Signature=wnHjNu3333ddW3zNMup1r4ovgrw6xJ0****&security-token=CAISjgJ1q6Ft5B2yfSjIr5fwMYLbhOwUxoibel7p0246OehcqLL%2BpTz2IH1PdXFgA%2Bgds%2Fswmm5U7vgalrkqEcEdHRGdN5YpsM8LrlzwO34PcmRsq%2B5qsoasPETOITyZtZagToeUZdfZfejXGDKgvyRvwLz8WCy%2FVli%2BS%2FOggoJmadJlNWvRL0AxZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO4gEWq4bHm5fCskKD1Qenk7FO%2B9uuc6LJNZc8YM1NNP6ux%2FFze6b71ypd1gNH7q8ejtYfpGyW5oHHWwIMvErYbbaMrIV1WwZ9Z7knHaVAq%2BXwnOBkuuXYnIns0BdLMuZOSD7YQI2wYWEwgBcxt78agAFThVhIcXH8zQiqbYVkTCHpZVRmDHH0mZ%2FMNuGikqSWdK3%2FhaSEvxmO1wyLH9E7mFzoKJErtxTCs453H6PYHO8H3pKOpKgZ0PfWTpJ8OEIJm26fKph%2F%2F3usSUBx5h0Ob17e2XB4BffkOJKQQiU3vXqoOZ6Vlyf7QpEJSvUMXXSKSg%3D%3D"
    }
}

ResultObject.SubCode错误码说明

错误码 认证描述文案 是否计费 可能原因和运营建议
200 认证通过 调用成功。
201 姓名和身份证不一致 可能是用户的信息有误或用户的信息为假信息,建议用户确认后重新操作。若同一身份信息重新发起认证,服务端初始化将会返回417错误。
202 查询不到身份信息 可能是用户户口迁移、军人等特殊状态导致,建议预留人工审核入口,进行人工审核。若同一身份信息重新发起认证,服务端初始化将会返回417错误。
203 查询不到照片或照片不可用 可能是公安库数据问题导致,建议预留人工审核入口,进行人工审核。若同一身份信息重新发起认证,服务端初始化将会返回417错误。
204 人脸比对不一致 可能不是同一人或活体照片质量较低,建议根据业务情况分层处理,若为同一人可重新操作。
205 活体检测存在风险 可能存在攻击风险,建议人工审核分层处理,若为真人可重新操作。
206 业务策略限制 个性化业务安全策略限制,如有疑问可咨询客服。
207 人脸与身份证人脸比对不一致 仅在使用ID_PLUS方案时返回,可能人证不符或人脸照片质量较低,建议根据业务情况分层处理,若为同一人可重新操作。
210 认证通过 通过产品安全策略综合判断,建议认证通过。

verifyScore阈值说明

千分之一误识率 万分之五误识率 万分之一误识率 十万分之五误识率 十万分之一误识率
70 71.5 75 76.5 80
说明 如果您有个性化需求,您可以根据业务情况,参考返回的比对分和阈值,自定义认证结果。

返回Code和Message说明

Code Message 描述
200 success 成功。
400 参数不能为空 参数不能为空。
401 参数非法 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
403 认证未完成 认证未完成。
404 认证场景配置不存在 认证场景配置不存在,请先在控制台上创建认证场景。
406 无效的CertifyId 无效的CertifyId
410 未开通服务 未开通OSS产品或未完成OSS读写授权。
411 RAM无权限 需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。
424 身份认证记录不存在 该CertifyId还没有对应的身份认证提交记录。
427 业务策略限制 仅在使用ID_PLUS方案时出现,指该身份因触发内部风控策略未完成认证。
500 系统错误 系统内部错误。