文档

服务端接入

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

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

发起认证请求

接口名:InitFaceVerify

服务地址:cloudauth.aliyuncs.com(IPv4)或cloudauth-dualstack.aliyuncs.com(IPv6)

请求方法:POST和GET。

传输协议:HTTPS。

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

请求参数

名称

类型

是否必选

描述

示例值

SceneId

Long

认证场景ID。您可以在控制台创建认证场景后获得的场景ID,具体操作,请参见添加认证场景

100000****

OuterOrderNo

String

客户服务端自定义的业务唯一标识,用于后续定位排查问题使用。值最长为32位长度的字母数字组合,请确保唯一。

e0c34a77f5ac40a5aa5e6ed20c******

ProductCode

String

认证方案。

唯一取值:LR_FR

LR_FR

Model

String

要进行活体检测的类型。

  • LIVENESS:默认,眨眼动作活体检测。

  • MULTI_ACTION:多动作活体检测,眨眼+任意摇头检测(顺序随机)。

  • MULTI_FAPTCHA:多动作活体检测,眨眼+形迹判断(顺序随机)。

    说明

    形迹判断是一种动作活体的检测方式,按规则移动鼻尖完成指定动作。形迹判断通过增加随机性,提升了安全能力。

MULTI_ACTION

ReturnUrl

String

客户业务页面回跳的目标地址。

http://www.aliyun.com

MetaInfo

String

MetaInfo环境参数。实际环境需要通过JS文件,调用函数getMetaInfo()获取,详情请参见PC或移动端H5网页接入

{"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。

114.XX.XX.XX

UserId

String

客户业务自定义的用户ID,请保持唯一。

12345****

CallbackUrl

String

认证结果的回调通知地址,回调请求方式默认为GET,回调地址必须以https开头。平台在完成认证后会回调该地址,并自动添加certifyIdpassed字段,passed字段值返回的是subcode值,示例:https://www.aliyun.com?callbackToken=1000004826&certifyId=shaxxxx&passed=200

说明

仅当认证完成(包含认证通过和认证未通过)时才会触发回调,若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时,若有需要可通过查询接口获取认证详情信息。

https://www.aliyun.com

CallbackToken

CallbackToken

安全Token,由您自行生成,用于防重复、防篡改校验。

如果设置了该值会在回调地址显示CallbackToken字段。

NMjvQanQgplBSaEI0sL86******

CertifyUrlType

String

Web SDK设备类型。取值WEB或者H5

说明

只支持Web SDK设备类型。

WEB

CertifyUrlStyle

String

返回certifyUrl类型,包括:

  • L:Https,原始长链。

  • S:Http,短链。

L

ProcedurePriority

String

移动端H5方式认证出现WebRTC或者Webassembly不兼容时的降级配置。默认值:url

  • keep:不支持降级,直接返回。

  • url:支持降级,返回认证URL,用户使用此URL打开或者切换浏览器进行认证。

  • video:支持降级,使用系统相机录制一段3~5秒的眨眼视频进行认证。

说明

仅移动端H5认证方式支持降级。

本功能目前处于试用阶段,此配置默认不生效,如果您想试用此功能,请通过智能在线联系阿里云工程师。

url

FaceGuardOutput

String

人脸保镖标签种类。

DeviceRisk:设备风险标签。

    说明
    • 选择输出人脸保镖会产生额外的费用,具体费用,请参见计费概述

    • 如果不需要输出人脸保镖标签,可以不传递参数或者传入空值。

DeviceRisk

返回数据

名称

类型

描述

示例值

RequestId

String

请求ID。

130A2C10-B9EE-4D84-88E3-5384FF******

Message

String

请求参数的响应信息。

success

Code

String

返回码:200为成功,其他为失败。

200

ResultObject.CertifyId

String

实人认证唯一标识。

警告

CertifyId字段为计费统计字段,为了方便后续核对账单,请您在本地留存该字段信息。

初始化接口返回的认证CertifyId在30分钟有效仅能认证提交一次,请您在有效期内应用,避免重复使用。

91707dc296d469ad38e4c5efa6******

ResultObject.CertifyUrl

String

Web认证URL,当您完成服务端初始化,阿里云会将Web认证URL返回给您。认证结束后根据请求参数中设置的ReturnUrl进行跳转。

说明

初始化接口返回的认证CertifyUrl在30分钟有效仅能认证提交一次,请您在有效期内应用,避免重复使用。

http://www.test.com

返回Code和Message说明

Code

Message

描述

200

success

成功。

400

参数不能为空

参数不能为空。

401

参数非法

非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。

402

应用配置不存在

应用配置不存在。

404

认证场景配置不存在

认证场景配置不存在,请先在控制台上创建认证场景。

410

未开通服务

未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。关于开通OSS产品和完成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.DeviceRisk

String

设备风险标签。

VirtualBrowser

说明

多个设备风险标签以半角逗号(,)分隔。如需了解更多设备风险标签及其含义,请参见人脸保镖标签说明

ResultObject.MaterialInfo

String

认证主体附件信息,主要为图片类材料。

本参数取值中涉及的字段解释,请参见下文的返回示例。

{"faceAttack": "F","faceOcclusion":"F","facialPictureFront": {"faceAttackScore": 0.00008597839769208804,"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","qualityScore": 99.93476867675781}}

返回示例

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
    },
}

ResultObject.SubCode错误码说明

错误码

认证描述文案

是否计费

可能原因和处理建议

200

认证通过

成功。

205

活体检测存在风险

可能存在攻击风险,建议人工审核分层处理,若为真人可重新操作。

206

业务策略限制

为了保证认证的安全性,会对认证的设备、身份、人脸等环境进行安全检测,若检测到可能存在风险会判定认证结果不通过。您可以按照如下方法排查处理:

  • 提醒用户卸载掉设备上可能安装的各种多开、分身、虚拟环境等软件或插件,恢复设备系统初始安全环境后重试。

  • 若是内部测试,可以在白名单设置页面加白处理。

说明

如果您有个性化需求,您可以根据业务情况,参考返回的比对分和阈值,自定义认证结果。

返回Code和Message说明

Code

Message

描述

200

success

成功。

400

参数不能为空

参数不能为空。

401

参数非法

非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。

403

认证未完成

认证未完成。

404

认证场景配置不存在

认证场景配置不存在,请先在控制台上创建认证场景。

406

无效的CertifyId

无效的CertifyId。

410

未开通服务

未开通OSS产品或未完成OSS读写授权。

411

RAM无权限

需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。

424

身份认证记录不存在

当前CertifyId还未完成认证,建议您客户端收到认证回调为1000或2006时,再请求查询接口获取详情。

说明

如果出现CertifyId未认证、认证过程中放弃、认证处理中的情况,均会导致查询接口返回此错误码。

500

系统错误

系统内部错误。

  • 本页导读
文档反馈