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

发起认证请求

接口名:InitFaceVerify

服务地址:cloudauth.aliyuncs.com。

请求方法:HTTPS POST和GET。

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

请求参数

名称 类型 是否必选 描述 示例值
SceneId Long 认证场景ID。 1000000006
OuterOrderNo String 客户请求的唯一标识。

值为32位长度的字母数字组合。前面几位字符是客户自定义的简称,中间可以使用一段时间,后段可以使用一个随机或递增序列。

e0c34a77f5ac40a5aa5e6ed20c353888
ProductCode String 固定值:ID_PRO。 ID_PRO
CertType String 证件类型。

当前支持身份证,必须传入IDENTITY_CARD。

IDENTITY_CARD
CertName String 真实姓名。 张三
CertNo String 证件号码。 330103xxxxxxxxxxxx
ReturnUrl String 客户业务页面回跳的目标地址 http://www.aliyun.com
MetaInfo String metainfo环境参数,需要通过JS获取。 {"zimVer":"3.0.0","appVersion": "1","bioMetaInfo": "4.1.0:11501568,0","appName": "com.aliyun.antcloudauth","deviceType": "ios","osVersion": "iOS 10.3.2","apdidToken": "","deviceModel": "iPhone9,1"}
Mobile String 用户手机号码。 130xxxxxxxx
Ip String 用户IP。 114.xxx.xxx.xxx
UserId String 客户业务自定义的用户ID,请保持唯一。 123456789

返回参数

名称 类型 是否必选 描述 示例值
RequestId String 请求ID。 130A2C10-B9EE-4D84-88E3-5384FF039795
Message String 错误信息。 success
Code String 返回码:200为成功,其他为失败。 200
ResultObject.CertifyId String 实人认证唯一标识。 91707dc296d469ad38e4c5efa6a0f24b
ResultObject.CertifyUrl String Web认证URL,认证结束后根据入参ReturnUrl进行跳转。 ResultObject.CertifyUrl

返回Code和Message说明

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

查询认证结果

接口名:DescribeFaceVerify

服务地址:cloudauth.aliyuncs.com。

请求方法:HTTPS POST和GET。

接口说明:当接入方移动端收到回调之后,其服务端可以调用此接口,来获取相应的认证状态和认证资料。

请求参数

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

返回参数

名称 类型 是否必选 描述 示例值
RequestId String 请求ID。 130A2C10-B9EE-4D84-88E3-5384FF039795
Message String 错误信息。 success
Code String 返回码,200指接口响应成功。详细认证结果判断请参考ResultObject.SubCode。 200
ResultObject.Passed String 认证结果。取值:
  • T:通过
  • F:未通过
T
ResultObject.SubCode String 认证结果描述。具体请参见下文SubCode说明。 200
ResultObject.IdentityInfo String 认证的主体信息,一般的认证场景返回为空。 null
ResultObject.MaterialInfo String 认证主体附件信息,主要为图片类材料。JSON格式,具体请参见下文示例。
说明 图片URL拼接耗时较久,若首次查询未能获取图片地址,您可以间隔2~3秒后重新查询。
{"faceAttack": "F","facialPictureFront": {"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.SubCode字段为准。

返回示例

ResultObject.MaterialInfo的JSON格式示例

{
    // 是否为攻击:攻击为T,非攻击为F。
    "faceAttack": "T",
    // 认证的照片信息。
    "facialPictureFront": {
        // 照片存放客户上海区域的OSS里,此为照片的bucket名。
        "ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779",
        // 照片存放客户上海区域的OSS里,此为照片的文件名。
        "ossObjectName": "verify/1260051251634779/03a081bd96328aedf83f635f39a50c57_0.jpeg",
        // 照片https地址,有效期15分钟,从查询时开始计时 。
        // 图片URL拼接耗时较久,若首次查询未能获取图片地址,您可以间隔2~3秒后重新查询。
        "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错误码说明

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

阈值说明

千分之一误识率 万分之五误识率 万分之一误识率 十万分之五误识率 十万分之一误识率
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无权限 需要给子账号授予AliyunAntCloudAuthFullAccess的操作权限。
424 身份认证记录不存在 该certifyId还没有对应的身份认证提交记录。
500 系统错误 系统内部错误。

SDK使用说明

说明 如需其他语言的SDK示例代码,您可以通过OpenAPI Explorer在线调试工具调试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.14</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("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());