接入文档
H5 lite方案
API接口
Plus版
获取比对结果
获取比对结果
# 调用URL
GET https://api.yljz.com/finauth/lite/plus/get_result
注意:在生产环境中,请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路,存在安全风险,请勿在生产环境中使用。在生产环境中使用HTTP方式的,将无法得到服务可靠性保障。
说明:此接口提供活体结果反查功能,可以以biz_id为索引对 FinAuth H5验证结果进行反查。该接口的调用信息保存有效期为一天,且仅支持3次调用。第4次或超过有效期调用则会返回错误信息,建议在每笔业务结束之后及时的取回数据。
# 参数
| 必选/可选 | 参数 | 类型 | 参数说明 |
|---|---|---|---|
| 必选 | sign | String | 调用此API客户的签名,具体的签名产生方式请查阅鉴权说明 |
| 必选 | sign_version | String |
签名算法版本
|
| 必选 | biz_id | String | 通过get_token, notify_url或者return_url返回的活体业务编号 |
# 返回值说明
| 参数 | 类型 | 说明 | 示例 |
|---|---|---|---|
| request_id | String | API 调用的流水号 |
"1462259763, e2d2f8d6-204b-4c43 -92ea-1d62b071f83c" |
| biz_info | Json |
包含:biz_id, biz_no, biz_extra_data
|
{
"biz_extra_data": "...", "biz_id": "1462259748, 52b13fb5-8dfb-4537 -a62b-a641d5e929f1", "biz_no": "cc47190f-5502-44a2 -ab74-ea4f0f649f61" } |
| time_used | Int | 整个请求所花费的时间,单位为毫秒,此字段必定返回 | 100 |
| result_code | Int |
表示本次验证的结果状态码;可结合result_code和result_message字段知晓具体的结果及原因:
|
1000 |
| result_message | String | 可通过此字段信息知晓具体的原因。具体见:result_code & result_message 对照表 | SUCCESS |
| idcard_info | Json |
身份证识别的结果,此字段在idcard_mode = 0时不返回;如果用户中途中断了活体流程,则此字段也不返回
内容包括:
|
{
"idcard_number": "idcard_name": "陈AB", "idcard_valid_date": "2010.11.13-2020.11.13", "idcard_issued_by": "北京市公安局", "front_side": { "ocr_result": { "address": "北京市海淀区XXXX", "birthday": { "day": "2", "month": "6", "year": "1991" }, "gender": "男", "id_card_number": "xxxxxx19910602xxxx", "name": "陈XX", "race": "汉", "legality": { "ID Photo": 0.855, "Temporary ID Photo ":0, "Photocopy": 0.049, "Screen": 0.096, "Edited": 0 } }, "upload_times": 1 }, "back_side": { "ocr_result": { "issued_by": " 北京市公安局海淀分局", "valid_date": "2010.11.13-2020.11.13", "legality": { "ID Photo": 0.855, "Temporary ID Photo ": 0, "Photocopy": 0.049, "Screen": 0.096, "Edited": 0 } }, "upload_times": 2 }, "ocr_front_quality": { "gender": { "quality": 0.925, "logic": 0, "result": "男" }, "address": { "quality": 0.958, "logic": 0, "result": "xxx" }, "idcard_number": { "quality": 0.995, "logic": 0, "result": "xxxx" }, "name": { "quality": 0.996, "logic": 0, "result": "张三" }, "birth_month": { "quality": 0.971, "logic": 0, "result": "8" }, "birth_day": { "quality": 0.975, "logic": 0, "result": "31" }, "nationality": { "quality": 0.959, "logic": 0, "result": "汉" }, "birth_year": { "quality": 0.942, "logic": 0, "result": "1996" } }, "ocr_back_quality": { "issued_by": { "quality": 0.994, "logic": 0, "result": "xxxxx" }, "valid_date_end": { "quality": 0.995, "logic": 0, "result": "xxxx" }, "valid_date_start": { "quality": 0.995, "logic": 0, "result": "20140515" } } } |
| liveness_result | Json |
活体检测结果;如果用户中途中断了活体流程,则此字段不返回
|
"liveness_result": {
"procedure_type": "flash", "result": false, "score": 0, "threshold": 0.5 } |
| verify_result | Json |
人脸比对结果;如果用户中途中断了活体流程或comparison_type为-1(仅活体不比对)等情况,则此字段不返回
|
{
"verify_time": 1462259763, "result_kyc": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_ref1": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_idcard_photo": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_idcard _datasource": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } } } |
| images | Json |
活体检测得到的图像,调用时通过 return_image 来选择,或以jpg编码并用base64字符串返回,或返回为null;
当存在比对结果且比对结果中error_message为计费字段时,图像才会返回
|
{ "image_idcard_back": "data:image/jpeg; base64,...", "image_idcard_front": "data:image/jpeg; base64,...", "image_best": "data:image/jpeg; base64,..." } |
| video | String |
视频下载地址 地址返回说明 说明:该链接用于下载活体的留存的视频;可下载有效期1天 如果未收到notify回调或者下载地址未生成等场景调取get_result接口,视频地址会返回空字符串,如:"video":"" 为保证数据安全,该地址访问有白名单限制,如需使用该功能请联系我方相关人员; 地址下载请求说明 入参:请用get的方式进行请求 出参:一个加密文件,解密后获取相应视频文件 加解密说明 加密方式:对称加密 AES-ECB 32位; 加密秘钥:取api_secret前32位作为加密密钥,正常secret长度为32位,如果长度不够则用空格进行补位; 加密内容:视频数据前1024位,若不足则空格补位;将加密后的数据替换视频数据的前1024位; |
{ "video": "http://XXX" } |
| verify_risk_info | Json |
visual_attributes:性别年龄预估结果:
"verify_info_tags":Json类型;表示活体图与比对图的比对风险
|
"visual_attributes": {
"gender": 0, "age": 31, "age_image_ref1": 22, "gender_image_ref1": 0 }, "verify_risk_info": { "verify_info_tags": { "is_gender_risk": 0, "is_age_risk": 0 } } |
| device_risk_info | Json |
设备风险检测结果: device_info_level:string类型 none:表示未检测到风险 middle:表示中风险 需要人工复核 high:表示高风险 直接拦截 device_info_tags:
|
"device_risk_info": {
"device_info_level": "none", "device_info_tags": { "is_cookies_disabled": "0", "is_higher_device_risk_threshold": "0", "is_debug_mode": "0", "is_virtual_browser": "0", "is_code_tampered": "0" } } |
成功示例
{
"biz_info": {
"biz_extra_data": "",
"biz_id": "1774270732,5fcf3520-cd58-448a-8126-b03a1c4ed92f",
"biz_no": "litetest"
},
"idcard_info": {
"back_side": {
"ocr_result": {
"issued_by": "北京市公安局xx分局",
"legality": {
"Edited": 0,
"ID Photo": 0.012,
"Photocopy": 0,
"Screen": 0.988,
"Temporary ID Photo": 0
},
"valid_date": "2020.01.10-2030.01.10"
}
},
"front_side": {
"ocr_result": {
"address": "北京市海淀区xxx道xxx号xxx室",
"birthday": {
"day": "11",
"month": "1",
"year": "2000"
},
"gender": "男",
"id_card_number": "110101xxxxxxxx2712",
"legality": {
"Edited": 0,
"ID Photo": 0.001,
"Photocopy": 0,
"Screen": 0.999,
"Temporary ID Photo": 0
},
"name": "张三",
"race": "汉"
}
},
"idcard_issued_by": "北京市公安局xx分局",
"idcard_name": "张三",
"idcard_number": "110101xxxxxxxx2712",
"idcard_valid_date": "2020.01.10-2030.01.10",
"ocr_back_quality": null,
"ocr_front_quality": null
},
"images": {
"image_best": "data:image/jpeg;base64,xxxxxxxxxxxxx",
"image_idcard_back": "data:image/jpeg;base64,xxxxxxxxxxxxx",
"image_best3": "data:image/jpeg;base64,xxxxxxxxxxxxx",
"image_best2": "data:image/jpeg;base64,xxxxxxxxxxxxx",
"image_face_shot": "data:image/jpeg;base64,xxxxxxxxxxxxx",
"image_idcard_front": "data:image/jpeg;base64,xxxxxxxxxxxxx"
},
"liveness_result": {
"procedure_type": "flash",
"result": false,
"score": 0,
"threshold": 0.5
},
"request_id": "1774270886,78fe1a8d-b45c-4435-b08a-ddf5e031e57f",
"result_code": "1000",
"result_message": "SUCCESS",
"time_used": 284,
"verify_result": {
"result_idcard_datasource": {
"confidence": 85.532,
"thresholds": {
"1e-3": 62.169,
"1e-4": 69.315,
"1e-5": 74.399,
"1e-6": 78.038
}
},
"result_idcard_photo": {
"confidence": 79.131,
"thresholds": {
"1e-3": 62.169,
"1e-4": 69.315,
"1e-5": 74.399,
"1e-6": 78.038
}
},
"result_kyc": {
"confidence": 85.532,
"thresholds": {
"1e-3": 62.169,
"1e-4": 69.315,
"1e-5": 74.399,
"1e-6": 78.038
}
},
"result_ref1": {
"confidence": 82.716,
"thresholds": {
"1e-3": 62.169,
"1e-4": 69.315,
"1e-5": 74.399,
"1e-6": 78.038
}
},
"result_ref2": {
"confidence": 82.893,
"thresholds": {
"1e-3": 62.169,
"1e-4": 69.315,
"1e-5": 74.399,
"1e-6": 78.038
}
},
"verify_time": 1774270832
},
"verify_risk_info": {
"verify_info_tags": {
"is_age_risk": 0,
"is_gender_risk": 0
},
"visual_attributes": {
"age": 22,
"gender": 0
}
},
"video": "http://XXX"
}
失败示例
{
"error_message": "RESULT_NOT_FOUND",
"request_id": "1462259901,fa79992d-ca61-48de-aa50-ea337c6aad42",
"time_used": 4
}
# result_code & result_message 对照表
| result_code | result_message | 含义解释 | 是否计费 |
|---|---|---|---|
| 1000 | SUCCESS | 验证成功 | 是,详细计费请咨询商务 |
| 2000 | PASS_LIVING_NOT_THE_SAME | 通过了活体检测,但是经过验证,待比对照片与其他照片中的至少一张,不是同一个人 | 是 |
| 3000 | NO_ID_CARD_NUMBER | 无此身份证号 | 是 |
| 3000 | ID_NUMBER_NAME_NOT_MATCH | 证件号码和姓名不匹配 | 是 |
| 3000 | NO_FACE_FOUND | 姓名和身份证号码正确,但照片没有检测到人脸 | 是 |
| 3000 | NO_ID_PHOTO | 找不到参考照片 | 是 |
| 3000 | PHOTO_FORMAT_ERROR | 参考照片格式错误 | 是 |
| 3000 | DATA_SOURCE_ERROR | 参考数据出现错误 | 否 |
| 3000 | INTERNAL_ERROR | 服务器内部错误 | 否 |
| 4000 | FAIL_LIVING_FACE_ATTACK | 活体验证失败 | 是 |
| 6000 | NOT_STARTED | 验证未开始 | 否 |
| 6000 | PROCESSING | 验证进行中 | 否 |
| 6000 | FAILED | 验证流程异常结束 | 否 |
| 6000 | CANCELLED | 用户主动取消 | 否 |
| 6000 | TIMEOUT | 验证超时 | 否 |
| 6100 | SUPPORT_ERROR | 浏览器不支持webRTC API | 否 |
| 6100 | PERMISSIONS_ERROR | 用户拒绝摄像头权限或浏览器(APP)不支持唤起摄像头权限 | 否 |
| 6100 | OTHER_ERROR | 其他异常导致的webRTC连接错误 | 否 |
# 错误码列表
GetResult 特有的 ERROR_MESSAGE
| HTTP状态代码 | 错误信息 | 说明 |
|---|---|---|
| 400 | RESULT_NOT_FOUND | 此错误类型表示传入的业务编号错误 |
| 400 | VIDEO_FACE_OCCLUDE | 上传的视频中人脸被遮挡 |
通用的ERROR_MESSAGE
| HTTP状态代码 | 错误信息 | 说明 |
|---|---|---|
| 403 | AUTHENTICATION_ERROR | api_key和api_secret不匹配 |
| 403 | AUTHORIZATION_ERROR:<reason> | api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限。目前的<reason>有:
|
| 400 | MESSAGE_ENCRYPTION_ERROR | 云端对敏感信息加密失败 |
| 403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 |
| 400 | MISSING_ARGUMENTS:<key> | 缺少某个必选参数 |
| 403 | DATA_DESTROYED | 超过可查询时间或超过最多可查询次数 |
| 400 | BAD_ARGUMENTS:<key> | 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长,etc.) |
| 404 | API_NOT_FOUND | 所调用的API不存在 |
| 500 | INTERNAL_ERROR | 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FinAuth客服或商务 |