备案控制台
文档
产品文档
输入文档关键字查找
首页 实人认证 金融级实人认证 开发参考 金融级活体人脸验证方案 PC或移动端H5网页接入 服务端集成

服务端集成

更新时间：
一键部署
产品详情
相关技术圈
我的收藏
重要

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

在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。

请求参数

名称

类型

是否必选

描述

示例值

SceneId

Long

是

要接入的认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景，请参见添加认证场景。

10000******

OuterOrderNo

String

是

您自定义的业务唯一标识，用于后续定位和排查问题。

支持长度为32位的字母和数字组合，请确保唯一。

e0c34a77f5ac40a5aa5e6ed2******

ProductCode

String

是

要接入的认证方案。

唯一取值：PV_FV。

PV_FV

Model

String

是

要进行活体检测的类型。

  • LIVENESS：默认，眨眼动作活体检测。

  • MULTI_ACTION：多动作活体检测，眨眼+任意摇头检测（顺序随机）。

  • MULTI_FAPTCHA：多动作活体检测，眨眼+形迹判断（顺序随机）。

    说明

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

MULTI_ACTION

CertType

String

是

用户证件类型。

不同证件类型，取值均为IDENTITY_CARD。

IDENTITY_CARD

CertName

String

是

您的终端用户的真实姓名。

张三

CertNo

String

是

您的终端用户的证件号码。

330103xxxxxxxxxxxx

ReturnUrl

String

是

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

https://www.aliyun.com

MetaInfo

String

是

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

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

FaceContrastPicture

String

是

说明

您需要在下述四种传入人脸照片方式中，选择其中一种：

  • FaceContrastPicture

  • FaceContrastPictureUrl

  • CertifyId

  • OSS

如果您选择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

Mobile

String

否

您终端用户的手机号码。

130xxxxxxxx

Ip

String

否

您终端用户的IP。

47.100.XX.XX

UserId

String

否

您自定义的用户ID，请保持唯一。

123456789

CallbackUrl

String

否

认证结果的回调通知地址，回调请求方式默认为GET，回调地址必须以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

CertifyUrlStyle

String

否

返回CertifyUrl类型，包括：

  • L：HTTPS，原始长链。

  • S：HTTP，短链。

L

Crop

String

否

是否允许裁剪人脸图片，默认不允许。

  • T：表示允许剪裁。

  • F：表示不允许剪裁。

说明

  • 若您请求的图片并非来自标准活体检测SDK采集，建议您允许裁剪人脸图片。

  • 开启该功能后，将会对请求的图片先进行人脸裁剪与矫正，完成后会发起请求服务。

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

返回参数

名称

类型

描述

示例值

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

刷脸失败次数过多

当天刷脸认证次数过多，请T+1日再试。

419

传入图片不可用

图片无法下载、图片内容为空或图片分辨率不符合要求。

420

数据重复

图片传入方式超过了一种。 支持以下四种传入人脸照片的方式，必须且只能使用其中一种：

  • FaceContrastPicture

  • FaceContrastPictureUrl

  • Oss

  • CertifyId

421

传入图片过大

图片超过了1 MB，建议压缩图片或更换图片上传方式。

422

下载图片超时

图片下载超过了3秒，请排查网络后重新操作。

423

状态错误

传入的CertifyId认证状态需要为T（认证通过），您也可以更换其他方式传入图片。

500

系统错误

系统内部错误，请反馈工程师进行排查。

DescribeFaceVerify-获取认证结果

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

请求参数

名称

类型

是否必选

描述

示例值

SceneId

Long

是

认证场景ID。

100000******

CertifyId

String

是

实人认证唯一标识。

91707dc296d469ad38e4c5ef******

返回参数

名称

类型

描述

示例值

Passed

String

认证结果。取值：

  • T：通过。

  • F：不通过。

判断认证结果请以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格式。

无。

上一篇：PC或移动端H5网页接入下一篇：PC或移动端H5网页SDK集成
文档推荐
  • 本页导读