当您的用户完成核身认证后,如果您需要拉取人脸核身的视频和图片用于存证等其他需要,您可以调用查询核身结果接口来获取。
重要提示:
1. 您需要在前端完成刷脸的回调后,再来调用查询核身结果接口获取刷脸视频和照片。
2. 人脸核身完成后的相关业务数据请尽快拉取,超过人脸核身服务必须最短缓存时间的业务数据将完全清理。
注意
当您的 App 接入的是我们的基础版或增强版 SDK 服务时,SDK 回调中只有当 domain=WBFaceErrorDomainCompareServer 时表示用户完成了刷脸,可以通过查询核身结果接口去拉取刷脸结果。其他 domain 表示用户刷脸中途退出或命中了风控逻辑,查询核身结果接口无法查询到刷脸结果。
步骤如下:
合作方后台生成签名
准备步骤
前置条件:请合作方确保 SIGN ticket 已经正常获取,获取方式请参见 获取 SIGN ticket 。
合作方为人脸核身服务生成签名,需要具有以下参数:
参数 | 说明 | 来源 |
appId | 业务流程唯一标识 | |
orderNo | 订单号,字母/数字组成的字符串,本次人脸核身合作伙伴上送的订单号,唯一标识 | 合作方自行分配,不要带有特殊字符 |
version | 默认值:1.0.0 | - |
ticket | 合作伙伴服务端缓存的 ticket,注意是 SIGN 类型 | 获取方式请参见 获取 SIGN ticket |
nonce | 32位随机字符串,由字母和数字组成 | 合作方自行生成,不要带有特殊字符 |
基本步骤
1. 生成一个32位的随机字符串 nonce(由字母和数字组成,登录时也要用到)。
2. 将 appId、orderNo、version、ticket、nonce 共5个参数的值进行字典序排序。
3. 将排序后的所有参数字符串拼接成一个字符串。
4. 将排序后的字符串进行 SHA1 编码,编码后的40位字符串作为签名(sign)。
注意
人脸核身结果查询接口(升级)
请求
请求 URL:
https://kyc1.qcloud.com/api/v2/base/queryfacerecord?orderNo=xxx
注意
为方便查询耗时,该请求url后面请拼接 orderNo 订单号参数。
请求方法:POST
报文格式:Content-Type: application/json
请求参数:
参数 | 说明 | 类型 | 长度(字节) | 是否必填 |
appId | 腾讯云控制台申请的 appid | String | 8 | 是 |
version | 版本号,默认值:1.0.0 | String | 20 | 是 |
nonce | 随机数 | String | 32 | 是 |
orderNo | 订单号,字母/数字组成的字符串,是您需要查询结果的人脸核身订单号 | String | 32 | 是 |
sign | 签名值,使用本页第一步生成的签名 | String | 40 | 是 |
getFile | 是否需要获取人脸识别的视频和文件,值为1则返回视频和照片、值为2则返回照片、值为3则返回视频;其他则不返回 | String | 1 | 否 |
queryVersion | 查询接口版本号(传1.0则返回 sdk 版本号和 trtc 标识) | String | 8 | 否 |
响应
响应参数:
参数 | 类型 | 说明 |
code | String | 0:表示身份验证成功且认证为同一人 |
msg | String | 返回结果描述 |
bizSeqNo | String | 业务流水号 |
transactionTime | String | 请求接口的时间 |
orderNo | String | 订单编号 |
liveRate | String | 活体检测得分 |
similarity | String | 人脸比对得分 |
occurredTime | String | 进行刷脸的时间 |
photo | Base 64 string | 人脸核身时的照片,base64 位编码 |
video | Base 64 string | 人脸核身时的视频,base64 位编码 |
sdkVersion | String | 人脸核身时的 sdk 版本号 |
trtcFlag | String | Trtc 渠道刷脸则标识"Y" |
appId | String | 腾讯云控制台申请的 appid |
响应示例:
{"code":"0","msg":"请求成功","bizSeqNo":"22032920001184453211174015790894","result":{"orderNo":"1617091885609174325769165852","liveRate":"99","similarity":"88.01","occurredTime":"20220329104717","appId":"IDAXXXXX","photo":"******","video":"******","bizSeqNo":"22032920001184453211174015790894","sdkVersion":"1.12.12","trtcFlag":"Y"},"transactionTime":"20220329111740"}
code 非 0 时,有时不返回图片和视频。
注意事项
照片和视频信息作为存证,合作伙伴可以通过此接口拉取视频等文件,需要注意请求参数的 get_file 需要设置为 1;如果不上送参数或者参数为空,默认不返回视频和照片信息。为确保用户操作整体流程顺利完成,部分情况下获取视频和照片会有1秒左右的延迟。
由于照片和视频信息有可能超过 1M,考虑传输的影响,建议合作伙伴在使用时注意,建议获取比对结果用于后续流程处理和存证使用分开调用。避免网络传输带来的影响。目前我们的查询接口是异步查询,返回的文件可能会有1/2 s的延迟。
如果合作方是完成人脸核身流程后马上去拉取视频/照片,建议在查询接口加上一个查询机制:判断图片是否存在,轮询3次,每次2s。
照片和视频均为 base64 位编码,其中照片解码后格式一般为 JPG 和 PNG。视频格式解码后一般为 MP4。
服务端验证结果接口返回66660011无此查询结果的可能原因:
1.1 66660017 验证次数超限后被风控,风控后的订单为无效,查询结果为无此查询结果。
1.2 用户中途退出刷脸,没有完成人脸验证的流程,没有比对,查询结果为无此查询结果。
1.3 66660018 操作超时,请退出重试 无此 ID 的用户身份信息,H5faceid 5分钟有效期,失效后无法进入刷脸流程,查询结果为无此查询结果。
1.4 66660016 视频格式或大小不合法 文件或视频不合法,无法进行比对,查询结果为无此查询结果。
1.5 400604 上传的视频非实时录制,被时间戳校验拦截,查询结果为无此查询结果。
1.6 查询超过3天的订单返回无此查询结果。
响应参数请勿做强校验,后续可能会有扩展。