一、准备步骤
·前置条件:请合作方确保 SIGN ticket 已经正常获取,获取方式见 获取 SIGN ticket 。
·SIGN 类型的 ticket,其有效期为60分钟,且可多次使用。
·合作方为人脸核身服务生成签名,需要具有以下参数:
| 参数 | 说明 | 来源 |
| appId | 业务流程唯一标识 | 参考 获取 WBappid 指引在人脸核身控制台内申请 |
| userId | 用户唯一标识,同一个用户的 userId 请保持一致,不同用户请不要使用同一个 userId,我们会根据 userId 来做登录态校验 | 合作方自行分配,需跟用户绑定,32位以内,不包含特殊字符 |
| version | 参数值为:1.0.0 | – |
| ticket | 合作伙伴服务端获取的 ticket,注意是 SIGN 类型 | 获取方式请参见 获取 SIGN ticket |
| nonce | 必须是32位随机数 | 合作方自行生成 |
注意:参与签名的数据需要与使用该签名的 SDK 中的请求参数保持一致。
二、基本步骤
3. 将排序后的所有参数字符串拼接成一个字符串。
4. 将排序后的字符串进行 SHA1 编码,编码后的40位字符串作为签名(sign)。
注意:Java 签名算法可参考 签名算法说明 。
三、参考示例
·请求参数:
| 参数 | 参数值 |
| appId | IDAXXXXX |
| userId | userID19959248596551 |
| nonce | kHoSxvLZGxSoFsjxlbzEoUzh5PAnTU7T |
| version | 1.0.0 |
| ticket | XO99Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS |
·字典排序后的参数为:
[1.0.0, IDAXXXXX, XO99Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS, kHoSxvLZGxSoFsjxlbzEoUzh5PAnTU7T, userID19959248596551]
·拼接后的字符串为:
1.0.0IDAXXXXXXO99Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMSkHoSxvLZGxSoFsjxlbzEoUzh5PAnTU7TuserID19959248596551
·计算 SHA1 得到签名:
该字符串就是最终生成的签名(40位),不区分大小写。
D7606F1741DDCF90757DA924EDCF152A200AC7F0
四、请求
·请求 URL:https://kyc1.qcloud.com/api/server/getAdvFaceId?orderNo=xxx
注意:为方便查询耗时,该请求 URL 后面请拼接 orderNo 订单号参数。
·请求方法:POST
·报文格式:Content-Type: application/json
·请求参数:
| 参数 | 说明 | 类型 | 长度(字节) | 是否必填 |
| appId | 业务流程唯一标识,即 WBappid,可参考 获取 WBappid 指引在人脸核身控制台内申请 | String | 8 | 是 |
| orderNo | 订单号,字母/数字组成的字符串,由合作方上传,每次唯一,不能超过32位 | String | 不能超过 32 位 | 是 |
| name | 姓名 | String | – | 使用权威源比对时:姓名+证件号必须输入使用自带源比对时:姓名+证件号可不输入 |
| idNo | 证件号码 | String | – | 使用权威源比对时:姓名+证件号必须输入使用自带源比对时:姓名+证件号可不输入 |
| userId | 用户 ID ,用户的唯一标识(不能带有特殊字符),需要跟生成签名的 userId 保持一致。同一个用户的 userId 请保持一致,不同用户请不要使用同一个 userId,我们会根据 userId 来做登录态校验 | String | 不能超过 32 位 | 是 |
| sourcePhotoStr | 比对源照片,注意:原始图片不能超过500k,且必须为 JPG 或 PNG、BMP 格式。参数有值:使用合作伙伴提供的比对源照片进行比对,必须注意是正脸可信照片,照片质量由合作方保证参数为空 :根据身份证号 + 姓名使用权威数据源比对 | BASE64String | 1048576 | 否,非必填请使用标准的图片转 BASE64方法,base64编码不可包含换行符,不需要加前缀 |
| sourcePhotoType | 比对源照片类型参数值为1 时是:水纹正脸照参数值为 2 时是:高清正脸照重要提示:照片上无水波纹的为高清照,请勿传错,否则影响比对准确率。如有疑问,请联系腾讯云技术支持线下确认 | String | 1 | 否,提供比对源照片需要传 |
| liveInterType | 活体交互模式参数值为1时,表示仅使用实时检测模式,不兼容的情况下回调错误码3005参数值非1或不入参,表示优先使用实时检测模式,如遇不兼容情况,自动降级为视频录制模式 | String | 1 | 否 |
| version | 默认参数值为:1.0.0 | String | 20 | 是 |
| sign | 签名:使用上面生成的签名 | String | 40 | 是 |
| nonce | 随机数 | String | 32 | 是 |
| url | H5 人脸核身完成后回调的第三方 URL,需要第三方提供完整 URL 且做 URL Encode。完整 URL Encode 示例:原 URL(https://cloud.tencent.com) Encode 后: (https%3a%2f%2fcloud.tencent.com) | String | – | 是 |
| resultType | 是否显示结果页面,参数值为“1”时直接跳转到 url 回调地址,null 或其他值跳转提供的结果页面 | String | – | 否,非必填 |
| from | browser :表示在浏览器启动刷脸 app :表示在 app 里启动刷脸默认值为 app | String | – | 是 |
| redirectType | 跳转模式,参数值为“1”时,刷脸页面使用 replace 方式跳转,不在浏览器 history 中留下记录;不传或其他值则正常跳转 | String | – | 否,非必填 |
五、响应
响应参数:
| 参数 | 类型 | 说明 |
| code | String | 0:成功 非0:失败 详情请参见 SaaS 服务错误码 |
| msg | String | 请求结果描述 |
| bizSeqNo | String | 请求业务流水号 |
| orderNo | String | 订单编号 |
| faceId | String | 此次刷脸用户标识 |
| transactionTime | String | 接口请求的时间 |
| optimalDomain | String | 启动 H5 人脸核身步骤中调用 login 接口使用的域名 |
响应示例:
{"code":"0","msg":"请求成功","bizSeqNo":"21062120001184438418322908010297","result":{ "bizSeqNo":"21062120001184438418322908010297", "transactionTime":"20210621183229", "orderNo":"1617091885609174325769165850", "faceId":"tx0375fa5243984381ea7b7013f13795", "optimalDomain":"kyc1.qcloud.com", "success":false },"transactionTime":"20210621183229"}
注意:说明:
注意:success:false 无意义,合作伙伴可忽略,无需处理。
注意:faceId 有效期为5分钟,每次进行人脸核身都需要重新获取。