PC或移动端H5网页认证方案的接入流程_实人认证-阿里云帮助中心

本文介绍了PC或移动端H5网页认证方案的接入流程。

发起认证请求

接口名：InitFaceVerify。

服务地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）

请求方法：POST和GET。

传输协议：HTTPS。

接口说明：每次开始认证前通过本接口获取CertifyId，用来串联认证请求中的各个接口。

请求参数


名称	类型	是否必选	描述	示例值
SceneId	Long	是	要接入的认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景，请参见添加认证场景。	1000000006
OuterOrderNo	String	是	您自定义的业务唯一标识，用于后续定位排查问题使用。支持长度为32位的字母和数字组合，请确保唯一。	e0c34a77f5ac40a5aa5e6ed20c353888
ProductCode	String	是	要接入的认证方案。唯一取值：ID_PRO。	ID_PRO
Model	String	是	要进行活体检测的类型。 LIVENESS：默认，眨眼动作活体检测。 MULTI_ACTION：多动作活体检测，眨眼+任意摇头检测（顺序随机）。	MULTI_ACTION
CertType	String	是	用户证件类型。支持的证件类型，请参见方案概述。唯一取值：IDENTITY_CARD。	IDENTITY_CARD
CertName	String	是	您的终端用户的真实姓名。	张三
CertNo	String	是	您的终端用户的证件号码。	330103xxxxxxxxxxxx
ReturnUrl	String	是	您业务页面回跳的目标地址。	http://www.aliyun.com
MetaInfo	String	是	MetaInfo环境参数。实际环境需要通过JS文件，调用函数`getMetaInfo()`获取，详情请参见启动刷脸。	{"zimVer":"3.0.0","appVersion": "1","bioMetaInfo": "4.1.0:1150****,0","appName": "com.aliyun.antcloudauth","deviceType": "ios","osVersion": "iOS 10.3.2","apdidToken": "","deviceModel": "iPhone9,1"} 说明该示例仅供参考，实际集成中不能直接应用，否则会导致无法正常获取到认证URL。
Mobile	String	否	您终端用户的手机号码。	130xxxxxxxx
Ip	String	否	您终端用户的IP。	47.100.XX.XX
UserId	String	否	您自定义的用户ID，请保持唯一。	123456789
CallbackUrl	String	否	认证结果的回调通知地址，必须以`https`开头。平台在完成认证后会回调该地址，并自动添加`certifyId`、`passed`字段，`passed`字段值返回的是subcode值，示例：`https://www.aliyun.com?callbackToken=1000004826&certifyId=shaxxxx&passed=200`。说明仅当认证完成（包含认证通过和认证未通过）时才会触发回调，若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时，若有需要可通过查询接口获取认证详情信息。	https://www.aliyun.com
CallbackToken	CallbackToken	否	安全Token，由您自行生成，用于防重复、防篡改校验。如果设置了该值会在回调地址显示CallbackToken字段。	NMjvQanQgplBSaEI0sL86WnQplB
CertifyUrlType	String	否	Web SDK设备类型。取值WEB或者H5。说明只支持Web SDK设备类型。	WEB
AuthId	String	否	用户授权ID，最大长度为64位字符。	92d46b9e9e2d703f2897f350d5bd4149
EncryptType	String	否	加密类型。为空表示不加密。如开启加密传输，需传入加密算法。目前仅支持SM2国密算法。如需传入加密算法，需对CertName和CertNo进行加密，并传入加密后的密文。有关参数加密的更多信息，请参见参数加密说明。	SM2

返回数据


名称	类型	描述	示例值
RequestId	String	请求ID。	130A2C10-B9EE-4D84-88E3-5384FF039795
Message	String	返回信息。	success
Code	String	返回码：200为成功，其他为失败。	200
ResultObject.CertifyId	String	实人认证唯一标识。警告 CertifyId字段为计费统计字段，为了方便后续核对账单，请您在本地留存该字段信息。初始化接口返回的认证CertifyId在30分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。	91707dc296d469ad38e4c5efa6a0f24b
ResultObject.CertifyUrl	String	Web认证URL，认证结束后根据入参ReturnUrl进行跳转。说明初始化接口返回的认证CertifyUrl在30分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。	http://m.alyms.cn/****

返回Code和Message说明


Code	Message	描述
200	success	成功。
400	参数不能为空	参数不能为空。
401	参数非法	非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
402	应用配置不存在	应用配置不存在。
404	认证场景配置不存在	认证场景配置不存在，请先在控制台上创建认证场景。
410	未开通服务	未开通OSS产品或未完成OSS读写授权，请登录控制台完成授权。
411	RAM无权限	需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。
412	欠费中	金融级实人认证或OSS存在欠费，请充值后操作。
414	设备类型不支持	当前移动设备不支持刷脸认证，请更换设备后操作。
415	SDK版本不支持	当前认证SDK版本不支持刷脸认证，请升级SDK后操作。
416	系统版本不支持	当前操作系统版本不支持刷脸认证，请升级系统或更换设备操作。
417	无法使用刷脸服务	当前身份信息比对源不可用。若信息正确，建议人工审核。
418	刷脸失败次数过多	当天刷脸认证次数过多，请明天再试。
500	系统错误	系统内部错误，请反馈工程师排查。

查询认证结果

接口名：DescribeFaceVerify。

服务地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）

请求方法：POST和GET。

传输协议：HTTPS。

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

请求参数


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

返回数据


名称	类型	描述	示例值
RequestId	String	请求ID。	130A2C10-B9EE-4D84-88E3-5384FF039795
Message	String	请求消息的响应信息。	success
Code	String	返回码。关于返回码的详细说明，请参见下文ResultObject.SubCode错误码说明。	200
ResultObject.Passed	String	认证结果。取值： T：通过。 F：未通过。说明判断认证结果请以ResultObject.Passed字段为准。	T
ResultObject.SubCode	String	认证结果描述。具体请参见下文ResultObject.SubCode错误码说明。说明判断认证结果请以ResultObject.Passed字段为准。	200
ResultObject.IdentityInfo	String	认证的主体信息，一般的认证场景返回为空。	null
ResultObject.MaterialInfo	String	认证主体附件信息，主要为图片类材料。本参数取值中涉及的字段解释，请参见下文的返回示例。	{"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.Passed字段为准。

返回示例

ResultObject.MaterialInfo的JSON格式示例：

{
    // 是否为攻击：攻击为T，非攻击为F。
    "faceAttack": "T",
    // 是否有脸部遮挡：有脸部遮挡为T，否则为F。
    "faceOcclusion": "F",
    // 认证的照片信息。
    "facialPictureFront": {
         //人脸攻击分。
         "faceAttackScore": 0.00008597839769208804,
        // 照片存放客户上海区域的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",
        // 活体人脸质量分数。
        "qualityScore": 99.93476867675781,
        // 人脸和公安比对分数，阈值可参考下表详细说明。
        "verifyScore": 57.678396649466755
    },
}

ResultObject.SubCode错误码说明

表 1. ResultObject.SubCode错误码说明
错误码	认证描述文案	是否计费	可能原因和处理建议
200	认证通过	是	成功。
201	姓名和身份证不一致	是	可能是用户的信息有误或用户的信息为假信息，建议用户确认后重新操作。若同一身份信息重新发起认证，服务端初始化将会返回417错误。
202	查询不到身份信息	是	可能是用户户口迁移等特殊状态导致，建议预留人工审核入口，进行人工审核。若同一身份信息重新发起认证，服务端初始化将会返回417错误。
203	查询不到照片或照片不可用	是	可能是公安库数据问题导致，建议预留人工审核入口，进行人工审核。若同一身份信息重新发起认证，服务端初始化将会返回417错误。
204	人脸比对不一致	是	可能不是同一人或活体照片质量较低，建议根据业务情况分层处理，若为同一人可重新操作。
205	活体检测存在风险	是	可能存在攻击风险，建议人工审核分层处理，若为真人可重新操作。
206	业务策略限制	是	为了保证认证的安全性，会对认证的设备、身份、人脸等环境进行安全检测，若检测到可能存在风险会判定认证结果不通过。您可以按照如下方法排查处理：提醒用户卸载掉设备上可能安装的各种多开、分身、虚拟环境等软件或插件，恢复设备系统初始安全环境后重试。若是内部测试，可以在白名单设置页面加白处理。
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读写授权，请登录控制台完成授权。具体操作，请参见授权金融级实人认证访问OSS存储空间。
411	RAM无权限	需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。
424	身份认证记录不存在	当前CertifyId还未完成认证，建议您客户端收到认证回调为1000或2006时，再请求查询接口获取详情。说明如果出现CertifyId未认证、认证过程中放弃、认证处理中的情况，均会导致查询接口返回此错误码。
427	业务策略限制	仅在使用ID_PLUS方案时出现，指该身份因触发内部风控策略未完成认证。
500	系统错误	系统内部错误，请通过智能在线联系阿里云工程师协助排查。

SDK使用说明

说明如需其他语言的SDK示例代码，您可以通过OpenAPI在线调试工具调试API接口。该工具会自动生成相应API的SDK调用示例代码。更多信息，请参见：

Java SDK使用示例

Maven依赖：

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.4.3</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-cloudauth</artifactId>
<version>2.0.32</version>
</dependency>

使用示例：

DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",    // 固定为cn-hangzhou。
            "AccessKeyID",      // 您的AccessKey ID。
            "AccessKeySecret");  // 您的AccessKey Secret。

IAcsClient client = new DefaultAcsClient(profile);

InitFaceVerifyRequest request = new InitFaceVerifyRequest();
request.setMetaInfo("MetaInfo环境参数");
request.setCertName("张三");
request.setCertNo("18位身份证号");
// 固定值。
request.setCertType("IDENTITY_CARD");
request.setSceneId(100000xxxxL);
request.setOuterOrderNo("客户请求的唯一标识");
// 固定值。
request.setProductCode("ID_PRO");
// Web SDK请求时为必填。
request.setReturnUrl("http://www.aliyun.com");

InitFaceVerifyResponse response = client.getAcsResponse(request);
System.out.println(response.getCode());
System.out.println(response.getMessage());
System.out.println(response.getRequestId());
System.out.println(response.getResultObject().getCertifyId());

// 等App客户端提交刷脸认证后，在客户端SDK的回调函数中，由客户端通知服务端运行以下代码查询认证结果。
DescribeFaceVerifyRequest request2 = new DescribeFaceVerifyRequest();
request2.setCertifyId("InitFaceVerify接口返回的CertifyId");
request2.setSceneId(100000xxxxL);

DescribeFaceVerifyResponse response2 = client.getAcsResponse(request2);
System.out.println(response2.getCode());
System.out.println(response2.getMessage());
System.out.println(response2.getRequestId());
System.out.println(response2.getResultObject().getPassed());
System.out.println(response2.getResultObject().getSubCode());
System.out.println(response2.getResultObject().getMaterialInfo());
System.out.println(response2.getResultObject().getIdentityInfo());