接入文档
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 签名算法版本
  • hmac_sha1
  • hmac_sha256
必选 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_id:业务流串号,可以用于反查比对结果
  • biz_no:客户业务流水号,会在notify和return时原封不动的返回给客户
  • biz_extra_data:在调用 notify_url 和 return_url 时会返回的额外数据
用户可以用此接口来传递一些额外信息。
{
 "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系列状态码表示比对完成,活体验证通过,比对通过
  • 2000系列状态码表示比对完成,活体验证通过,比对不通过
  • 3000系列状态码表示在比对的时候,数据源调用情况
  • 4000系列状态码表示活体验证不通过
  • 6000系列状态码表示流程状态相关错误
  • 其他结果,请预留处理方案,对于未来可能的错误,我们可能持续增加错误码
1000
result_message String 可通过此字段信息知晓具体的原因。具体见:result_code & result_message 对照表 SUCCESS
idcard_info Json 身份证识别的结果,此字段在idcard_mode = 0时不返回;如果用户中途中断了活体流程,则此字段也不返回 内容包括:
  • idcard_number:表示最终经过用户确认的身份证号 (根据idcard_uneditable_field可能被修改过)
  • idcard_name:表示最终经过用户确认的姓名 (根据idcard_uneditable_field可能被修改过)
  • idcard_valid_date:表示最终经过用户确认的身份证有效期 (根据idcard_uneditable_field可能被修改过,如果不用拍摄身份证国徽面则不返回此字段)  
  • idcard_issued_by:表示最终经过用户确认的身份证签发机关
    (根据idcard_uneditable_field可能被修改过,如果不用拍摄身份证国徽面则不返回此字段)
  • front_side:身份证人像面的识别结果(如果不用拍摄身份证人像面则不返回此字段)
    • ocr_result:文字识别结果,详见【FinAuth Ocridcard API】
  • back_side:身份证国徽面的识别结果(如果不用拍摄身份证国徽面则不返回此字段)
    • ocr_result:文字识别结果,详见【FinAuth Ocridcard API】
  • ocr_front_quality:身份证人像面各字段质量判断及逻辑判断结果
  • ocr_back_quality:身份证国徽面各字段质量判断及逻辑判断结果
{
 "idcard_number":  "xxxxxx19910602xxxx",
 "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 活体检测结果;如果用户中途中断了活体流程,则此字段不返回
  • procedure_type:返回本次活体所使用的活体验证方式:
    • flash:通过炫彩活体方式进行活体验证
    • active_flash:通过灵动活体方式进行活体验证
    • distance:通过距离活体方式进行活体验证
    • still:通过实时静默活体方式进行活体验证
    • video:通过自拍有声视频方式进行活体验证
    • still_record:通过自拍一段人脸视频进行活体认证
  • "result":Bool类型,取值True或者False。代表云端攻击判断的结果,False代表不是攻击,True代表是攻击
  • "score":Float类型,取值[0,1]。代表攻击的分数,分数越高表明攻击的可能性越大
  • "threshold":Float类型,取值[0,1]。代表攻击的阈值
  • 注:
    • 云端采用默认策略是判断score >= threshold时,代表此次可能是攻击
"liveness_result": {
 "procedure_type": "flash",
 "result": false,
 "score": 0,
 "threshold": 0.5
}
verify_result Json 人脸比对结果;如果用户中途中断了活体流程或comparison_type为-1(仅活体不比对)等情况,则此字段不返回
  • result_kyc:人脸核身的综合分数
    • "confidence":综合分数的置信度,Float类型,取值[0,100],数字越大表示风险越小
    • “thresholds”:一组用于参考的置信度阈值,Object类型, 包含四个字段,均为Float类型、取值[0,100]:
      • “1e-3”:风险为千分之一的置信度阈值
      • “1e-4”:风险为万分之一的置信度阈值
      • “1e-5”:风险为十万分之一的置信度阈值 
      • “1e-6”:风险为百万分之一的置信度阈值
  • result_ref[x]:活体采集人像与上传的image_ref[x]的比对结果(同result_kyc)
  • result_idcard_photo:活体采集人像与身份证照片上的人脸比对的结果(同result_kyc)
  • result_idcard_datasource:身份证照片上的人脸和参考比对数据照片比对的结果(同result_kyc)
  • verify_time:验证发生的时间戳(单位:秒),仅当return_verify_time=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_best:质量最佳的活体图像
  • image_best2:通过质量检测的第二张活体图像(未配置不返回)
  • image_best3:通过质量检测的第三张活体图像(未配置不返回)
  • image_idcard_back:最后一次上传的身份证国徽面
  • image_idcard_front:最后一次上传的身份证人像面
  • image_face_shot:人脸大头照(仅开启多人大头照裁剪时返回)
  • image_multifaces:包含多人脸的图像(仅开启多人脸检测时返回)
{
 "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:性别年龄预估结果:
  • “age”:预估核验人活体图年龄
  • “gender”:预估核验人活体图性别
  • “age_image_ref1”:预估比对参照人脸图年龄(仅comparison_type=0时返回)
  • “gender_image_ref1”:预估比对参照人脸图性别(仅comparison_type=0时返回)
比对风险提示结果:
"verify_info_tags":Json类型;表示活体图与比对图的比对风险
  • "is_gender_risk":String类型,0:表示活体图与比对图性别一致;1:表示活体图与比对图性别不一致(comparison_type=1,则活体图与身份证性别比对;comparison_type=0,则活体图与ref1图性别比对,comparison_type=-1,则返回为空);
  • "is_age_risk":String类型,0:表示活体图与比对图年龄差异不大(10岁以内);1:表示活体图与比对图年龄差异较大(一般指的是年龄差距在10岁及以上,具体根据阈值设定。comparison_type=1,则活体图与身份证年龄比对;comparison_type=0,则活体图与ref1图年龄比对,comparison_type=-1,则返回为空);
“multifaces_tag”:String类型,表示是否检测到多人脸
  • 0:单人脸
  • 1:多人脸
"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:
  • is_cookies_disabled COOKIES 被禁用
  • is_code_tampered 代码被篡改
  • is_virtual_browser 虚拟浏览器
  • is_debug_mode 调试模式
  • is_higher_device_risk_threshold 高于设备风险阈值
"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>有:
  • API_KEY_BE_DISCONTINUED:api_key被停用
  • LIMIT_REACHED:这个api_key对当前API的调用量达到上限。仅当api_key为测试key
  • DENIED:无权限调用当前API
  • EXPIRED_SIGN:签名已过期
  • INVALID_SIGN:无效签名
  • NO_DATA_SOURCE_PERMISSION:没有KYC验证的权限,但是本次请求依然尝试调用了
  • 其他可能的错误码,请预留处理方案
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客服或商务