本文介绍通过纯服务端(API)接入ID Verification的流程。
接口说明
接口名:EkycVerify
请求方法:HTTPS POST
接口说明:通过传入图片资料等信息进行eKYC认证。
QPS限量:API独享QPS限量,详情请参见ID Verification服务端API QPS限量说明。
服务地址:
说明内网指的是阿里云同地域产品之间的内部通信网络,如果您的业务服务器部署在阿里云的对应地域,可以通过内网域名访问 ID Verification 服务,以获得更安全、稳定的网络通信质量。
中国香港
公网:
cloudauth-intl.cn-hongkong.aliyuncs.com内网:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
在线调试和集成
在调试和集成前,请确保您已完整阅读使用OpenAPI调试和集成服务端API文档,充分了解API接口在OpenAPI平台的调用方式和SDK及其代码的获取方式。
您可以在OpenAPI Explorer中直接运行本接口进行调试,并生成本接口的SDK代码示例。
传入图片格式要求
图片格式:JPG、JPEG、PNG。
图片大小:推荐50~100 KB,最大不超过1 MB。
图片分辨率:不超过1920*1080(高*宽),至少为640*480(高*宽),推荐短边缩放到720像素,压缩率大于0.9。照片高大于宽,如果传入的照片宽大于高,可能会影响检测效果。
说明图片转base64格式后,通常会导致数据体积增加。如您需要使用base64格式传参,请保证原始图片的体积不超过0.6MB,以满足1MB的最大数据传输限制。
图片质量建议:
人脸面部需要完整清晰无遮挡,正对摄像头,推荐通过前置摄像头采集的人脸图片。
人脸大小占比图片中面积需要>60%,若人脸较小会影响检测的准确性。
若图片中存在多个人脸,算法默认截取较大的人脸,建议避免传入多人脸图片。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
ProductCode | String | 是 | 要接入的产品方案。取值eKYC_MIN。 | eKYC_MIN |
SceneCode | String | 否 | 您自定义的认证场景ID,用于后续控制台输入此场景ID查询相关记录。支持长度为10位的字母、数字或下划线的组合。 | 1234567890 |
MerchantBizId | String | 是 | 自定义的业务唯一标识,用于后续定位排查问题使用。支持长度为32位的字母和数字的组合,请确保唯一。 | e0c34a77f5ac40a5aa5e6ed20c35**** |
MerchantUserId | String | 是 | 您自定义的用户ID,或者其他可以识别特定用户的标识,例如手机号码、邮箱地址等。强烈建议对该字段的值进行预先脱敏,例如对值进行哈希处理。 | Y |
DocType | String | 是 | 证件类型,以8位数字组合作为唯一标识。更多说明,请参见证件类型列表。 | 01000000 |
DocName | String | 否 | 用户的真实姓名。 说明 当Authorize=T且证件类型为中国内地居民身份证时,以下证件关键信息与证件图片必须输入至少一组:
| 张三 |
DocNo | String | 否 | 用户的证件号码。 说明 当Authorize=T且证件类型为中国内地居民身份证时,以下证件关键信息与证件图片必须输入至少一组:
| 411xxxxxxxxxxx0001 |
IdOcrPictureBase64 | String | 否 说明 IdOcrPictureBase64和IdOcrPictureUrl二选一。 | 证件图片Base64编码。 说明 如果您选择该方式传入证件图片,请检查照片大小,不要传入过大的照片。 | base64编码 |
IdOcrPictureUrl | String | 否 | 证件图片地址,公网可访问的HTTP、HTTPS链接。 | https://*** |
FacePictureBase64 | String | 否 说明 FacePictureBase64和FacePictureUrl二选一。 | 人像图片Base64编码。 说明 如果您选择该方式传入证件图片,请检查照片大小,不要传入过大的照片。 | base64编码 |
FacePictureUrl | String | 否 | 人像地址,公网可访问的HTTP、HTTPS链接。 | https://*** |
Crop | String | 否 | 是否允许裁剪人脸图片:
| F |
Authorize | String | 否 | 是否开启官方数据库身份核验:
说明 目前仅适用于中国内地第二代居民身份证。 | F |
IdThreshold | String | 否 | 自定义OCR质量检测阈值模式:
| 0 |
证件类型列表
DocType | 对应证件 |
01000000 | 全球护照 |
00000006 | 香港居民身份证(2003版) |
00000008 | 香港居民身份证(2018版) |
00000007 | 往来港澳通行证 |
00000009 | 港澳居民来往内地通行证 |
000000011 | 澳门身份证 |
000000012 | 台湾居民来往大陆通行证 |
00000001 | 中国内地第二代居民身份证 |
返回数据
名称 | 类型 | 描述 | 示例值 | |
HTTP Status Code | Integer | HTTP状态码。 | 200 | |
HTTP Body | RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF0**** |
Code | String | Success | ||
Message | String | 返回Code的详细描述。 | success | |
Result.Passed | String | 认证最终结果,取值:
| Y | |
Result.SubCode | String | 认证结果描述。更多信息,请参见ResultObject.SubCode错误码说明。 | 200 | |
Result.ExtFaceInfo | String | 活体人脸验证相关结果信息。关于JSON格式,请参见右侧示例。更多信息,请参见ExtFaceInfo。 | | |
Result.ExtIdInfo | String | 证件识别相关结果信息。 关于JSON格式,请参见右侧示例。更多信息,请参见ExtIdInfo。 | | |
返回Code
HTTP状态码 | Code | Message说明 |
200 | Success | 请求成功。 |
400 | MissingParameter | 参数不能为空。 |
InvalidParameter | 非法参数。 | |
401 | UnqualifiedPhoto | 传入的图片不可读,或图片分辨率不符合要求,建议更换图片。 需确保照片清晰、曝光正常,完整无遮挡,角度无太大偏差。 |
DataDuplication | 同时传入Base64编码的图片和Url图片地址,此二参数任选其一即可。 | |
ToolargeImage | 图片尺寸过大,建议压缩图片或更换图片上传方式。 | |
DownloadTimeout | URL图片下载超时。 | |
NoFaceDetected | 传入图片无人脸。 | |
403 | Forbidden.RAMUserAccessDenied | 需要给RAM用户授予 AliyunAntCloudAuthFullAccess 操作权限。更多信息,请参见授权RAM用户访问服务。 |
Forbidden.AccountAccessDenied | 确保您开通了ID verifycation,并且保证账户未欠费。 | |
Throttling.Api | API限流拦截。 | |
500 | InternalError | 系统内部错误,请反馈给工程师排查。 |
ResultObject.SubCode错误码说明
错误码 | 是否计费 | 描述和原因建议 |
200 | Yes | 认证通过。 |
201 | Yes | 官方数据库中姓名和身份证不一致。可能是用户的信息有误或用户的信息为假信息,建议用户确认后重新操作。 |
202 | Yes | 官方数据库查询不到身份信息。建议预留人工审核入口,进行人工审核。 |
203 | Yes | 查询不到照片或照片不可用。可能原因:权威比对源未留存底库照片。建议预留人工审核入口,进行人工审核。 |
204 | Yes | 人脸比对不一致。可能不是同一人或活体照片质量较低。 |
205 | Yes | 活体检测存在风险。 |
207 | Yes | 上传人脸与官方数据库中的人脸比对不一致。可能不是同一人或人脸照片质量较低。 |
209 | Yes | 权威比对源异常。 |
212 | Yes | 证件防伪检测存在风险。可能存在翻拍、篡改、复印等高风险操作。 |
ExtFaceInfo
名称 | 类型 | 描述 | 示例值 |
facePassed | String | 扫脸阶段的活体人脸验证最终结果:
| Y |
faceComparisonScore | Double | 采集人脸和证件人像比对分。比对分取值范围0~100。 | 99.99 |
faceAttack | String | 采集人脸是否涉及活体攻击:
| N |
authorityComparisonScore | Double | 采集人脸和官方权威数据源比对分。比对分取值范围0~100。 | 99.99 |
ExtIdInfo
名称 | 类型 | 描述 | 示例值 |
idPassed | String | 证件OCR识别阶段的最终结果:
| N |
ocrIdInfo | String | 证件OCR字段信息。 说明 如果证件OCR流程失败,则该字段值为空。 | |
spoofInfo | String | 证件防伪检测结果,包括风险判定结果和风险类型:
| |