本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
在PC或移动端H5网面接入金融级活体人脸验证方案时,开发者需要在后端服务器集成SDK,以便调用InitFaceVerify接口获取用于浏览器进行实人认证的认证链接CertifyUrl。本文介绍发起实人认证请求和查询实人认证结果的服务端接口说明。
InitFaceVerify-发起认证请求
每次开始认证前通过调用本接口获取用于浏览器进行实人认证的认证链接CertifyUrl。您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
接口说明
接口名:InitFaceVerify。
全局接入地址:cloudauth.aliyuncs.com(IPv4)或cloudauth-dualstack.aliyuncs.com(IPv6)
请求方法:POST和GET。
传输协议:HTTPS。
接口说明:每次开始认证前通过调用本接口获取用于PC或移动端网页进行实人认证的认证链接CertifyUrl。
QPS限量:API独享QPS限量,详情请参见服务端接口QPS限量说明。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 要接入的认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景,请参见添加认证场景。 | 10000****** |
OuterOrderNo | String | 是 | 您自定义的业务唯一标识,用于后续定位和排查问题。 支持长度为32位的字母和数字组合,请确保唯一。 | e0c34a77f5ac40a5aa5e6ed2****** |
ProductCode | String | 是 | 要接入的认证方案。 唯一取值:PV_FV。 | PV_FV |
Model | String | 是 | 要进行活体检测的类型。
| PHOTINUS_LIVENESS |
CertType | String | 是 | 用户证件类型。 不同证件类型,取值均为IDENTITY_CARD。 | IDENTITY_CARD |
CertName | String | 否 | 您的终端用户的真实姓名。 | 张三 |
CertNo | String | 否 | 您的终端用户的证件号码。 | 330103xxxxxxxxxxxx |
ReturnUrl | String | 是 | 您的业务页面回跳的目标地址。 | https://www.aliyun.com |
MetaInfo | String | 是 | MetaInfo环境参数。实际环境需要通过JS文件,调用函数 |
说明 该示例仅供参考,实际集成中不能直接应用,否则会导致无法正常获取认证URL。 |
FaceContrastPicture | String | 是 说明 您需要在下述四种传入人脸照片方式中,选择其中一种:
如果您选择OSS方式传入人脸照片,您必须传入OssBucketName和OssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和Object。 | 照片Base64编码。如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。 | /9j/4AAQSkZJRgABAQAASxxxxxxx |
FaceContrastPictureUrl | String | 人像地址,公网可访问的HTTP、HTTPS链接。 | https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg | |
CertifyId | String | 之前实人认证通过的CertifyId,认证时的照片作为比对照片。您需要确保传入CertifyId关联的图片正常存储在授权的OSS Bucket中。 | 0bfa7c493f850e5178b9f8613634**** | |
OssBucketName | String | 已授权OSS空间的Bucket名称。 | cn-shanghai-aliyun-cloudauth-xxxxx | |
OssObjectName | String | 已授权OSS空间的Object名称。 | verify/xxxxx/xxxxxx.jpeg | |
UserId | String | 是 | 您自定义的用户ID,请保持唯一。 | 123456789 |
Mobile | String | 否 | 您终端用户的手机号码。 | 130xxxxxxxx |
Ip | String | 否 | 您终端用户的IP。 | 47.100.XX.XX |
CallbackUrl | String | 否 | 认证结果的回调通知地址,回调请求方式默认为GET,回调地址必须以 说明 仅当认证完成(包含认证通过和认证未通过)时才会触发回调,若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时,若有需要可通过查询接口获取认证详情信息。 | https://www.aliyun.com |
CallbackToken | CallbackToken | 否 | 安全Token,由您自行生成,用于防重复、防篡改校验。 如果设置了该值,会在回调地址中显示CallbackToken字段。 | NMjvQanQgplBSaEI0sL86WnQplB |
CertifyUrlType | String | 否 | Web SDK设备类型。取值WEB或者H5。 说明 只支持Web SDK设备类型。 | WEB |
CertifyUrlStyle | String | 否 | 返回CertifyUrl类型,包括:
| L |
Crop | String | 否 | 是否允许裁剪人脸图片,默认不允许。
说明
| T |
AuthId | String | 否 | 用户授权ID,最大长度为64位字符。 | 92d46b9e9e2d703f2897f350d5bd4149 |
EncryptType | String | 否 | 加密类型。为空表示不加密。 如开启加密传输,需传入加密算法。目前仅支持SM2国密算法。 如需传入加密算法,需对CertName和CertNo进行加密,并传入加密后的密文。有关参数加密的更多信息,请参见参数加密说明。 | SM2 |
FaceGuardOutput | String | 否 | 人脸保镖标签种类。 DeviceRisk:设备风险标签。
说明 | DeviceRisk |
uiCustomUrl | String | 否 | UI配置文件URL。关于Web SDK自定义UI说明,请参见Web SDK UI自定义配置说明。 | www.aliyundoc.com |
VideoEvidence | String | 否 | 是否开启视频存证。
说明 因为视频文件较大,当网络不稳定时系统会丢弃视频文件优先保障认证必要图片传输,建议您业务上设置为弱依赖视频。 | false |
返回参数
名称 | 类型 | 描述 | 示例值 |
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进行跳转。 警告
| https://t.aliyun.com/**** |
返回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 | 刷脸失败次数过多 | 当天刷脸认证次数过多,请T+1日再试。 |
419 | 传入图片不可用 | 图片无法下载、图片内容为空或图片分辨率不符合要求。 |
420 | 数据重复 | 图片传入方式超过了一种。 支持以下四种传入人脸照片的方式,必须且只能使用其中一种:
|
421 | 传入图片过大 | 图片超过了1 MB,建议压缩图片或更换图片上传方式。 |
422 | 下载图片超时 | 图片下载超过了3秒,请排查网络后重新操作。 |
423 | 状态错误 | 传入的CertifyId认证状态需要为T(认证通过),您也可以更换其他方式传入图片。 |
500 | 系统错误 | 系统内部错误,请反馈工程师进行排查。 |
DescribeFaceVerify-获取认证结果
当您收到回调通知之后,可以在服务端通过该接口获取相应的认证状态和认证资料。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 认证场景ID。 | 100000****** |
CertifyId | String | 是 | 实人认证唯一标识。 | 91707dc296d469ad38e4c5ef****** |
返回参数
名称 | 类型 | 描述 | 示例值 |
Passed | String | 认证结果。取值:
判断认证结果请以ResultObject.Passed字段为准。 | T |
SubCode | String | 认证结果描述。更多信息,请参见ResultObject.SubCode错误码说明。 说明 判断认证结果请以Passed字段为准。 | 200 |
IdentityInfo | String | 认证的主体信息,一般的认证场景返回为空。 | 无。 |
DeviceToken | String | 设备Token。 | McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOABBF**** |
ResultObject.DeviceRisk | String | 设备风险标签。 | ROOT,VPN,HOOK 说明 多个设备风险标签以半角逗号(,)分隔。如需了解更多设备风险标签及其含义,请参见人脸保镖标签说明。 |
MaterialInfo | String | 认证主体附件信息,主要为图片类材料。JSON格式。 | 无。 |