查询核身结果

最近更新时间:2024-06-17 17:09:41

我的收藏
当您的用户完成核身认证后,如果您需要拉取人脸核身的视频和图片用于存证等其他需要,您可以调用查询核身结果接口来获取。 重要提示:
1. 您需要在前端完成刷脸的回调后,再来调用查询核身结果接口获取刷脸视频和照片。
2. 人脸核身完成后的相关业务数据请尽快拉取,超过人脸核身服务必须最短缓存时间的业务数据将完全清理。
注意
当您的 App 接入的是我们的基础版或增强版 SDK 服务时,SDK 回调中只有当 domain=WBFaceErrorDomainCompareServer 时表示用户完成了刷脸,可以通过查询核身结果接口去拉取刷脸结果。其他 domain 表示用户刷脸中途退出或命中了风控逻辑,查询核身结果接口无法查询到刷脸结果。
步骤如下:

合作方后台生成签名

准备步骤

前置条件:请合作方确保 SIGN ticket 已经正常获取,获取方式请参见 获取 SIGN ticket 。
合作方为人脸核身服务生成签名,需要具有以下参数:
参数
说明
来源
appId
业务流程唯一标识
参考 获取 WBappid 指引在人脸核身控制台内申请
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;如果不上送参数或者参数为空,默认不返回视频和照片信息。
由于照片和视频信息有可能超过 1M,考虑传输的影响,建议合作伙伴在使用时注意,建议获取比对结果用于后续流程处理和存证使用分开调用。避免网络传输带来的影响。
如果合作方是完成人脸核身流程后马上去拉取视频/照片,建议在查询接口加上一个查询机制:判断图片是否存在,轮询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天的订单返回无此查询结果。
响应参数请勿做强校验,后续可能会有扩展。

服务端响应码

详情请参见 SaaS 服务错误码