接入文档
SDK方案
FinAuth轻量版
人脸核身
人脸核身
# 版本
5.0.0
# 描述
此接口用于将FinAuth轻量版SDK采集人脸图片或者渠道人脸图片数据进行上传,并获取权威数据比对结果
# 调用URL
https://api.yljz.com/finauth/v5/identity
注意:在生产环境中,请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路,存在安全风险,请勿在生产环境中使用。在生产环境中使用HTTP方式的,将无法得到服务可靠性保障。
# 调用方法
POST 注意:用 form-data 格式请求
# 权限
仅当用户接入FinAuth产品后,才能调用FinAuth各API。接入FinAuth的流程请咨询FinAuth商务人员。
# 参数
必选/可选 | 参数 | 类型 | 参数说明 |
必选 | sign | String | 调用此API客户的签名,具体的签名产生方式请查阅App-鉴权说明 |
必选 | sign_version | String | 签名算法版本号,请传递:hmac_sha1 |
可选 | biz_no | String | “默认为空”。客户业务流水号,建议设置为您的业务相关的流水串号并且唯一,会在return时原封不动的返回给您的服务器,以帮助您确认对应业务的归属。此字段不超过128字节 |
必选 | identity_id | String | identity场景id:本次验证请求相关配置在控制台可设置,并将生成的id号在接口中使用 |
必选 | encryption_type | String |
是否开启传输数据加密,详细说明见:加密说明 |
必选 | image | File | 传入轻量版SDK采集到的照片或者自有渠道照片进行认证 |
必选 | idcard_name | String | 需要核实对象的姓名,使用UTF-8编码 |
必选 | idcard_number | String | 需要核实对象的证件号码,也就是一个18位长度的字符串 |
可选 | image_ref1 | File | 由应用方提供的参照人脸照片。如果在图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对 |
# 返回值说明
参数类别 | 参数 | 类型 | 参数说明 |
#基础返回信息 | request_id | String | API 调用的流水号 |
biz_no | String | 传入的业务流水号,原封不动地返回 | |
time_used | Int | 整个请求所花费的时间,单位为毫秒。此字段必定返回 | |
error | String | 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节,否则此字段不存在 | |
result_code | Int |
表示本次验证的结果状态码。可结合result_code和result_message字段知晓具体的结果及原因:
|
|
#状态码描述 | result_message | String | 可通过此字段信息知晓具体的原因。具体见:result_code & result_message 对照表 |
#比对结果 | verification | Json |
|
#附加返回信息 | |||
face | Json |
当选用image方式时返回待验证图片image的属性:
|
# 返回值示例
正确请求返回示例
{
"request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
"biz_no":"",
"time_used":,
"result_code":1000,
"result_message":"SUCCESS",
"verification":{
"idcard":{
"confidence":86.63057,
"thresholds":{
"1e-3":62.168713,
"1e-5":74.39926,
"1e-4":69.31534,
"1e-6":78.038055
}
}
},
"face":{
"quality":38.221,
"quality_threshold":30.1,
"rect":{
"left":0.18,
"top":0.18,
"width":0.596,
"height":0.596
},
"orientation":90
}
}
失败请求返回示例
{
"error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}
# 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 | 参考数据出现错误 | 否 |
# 错误码列表
HTTP状态代码 | 错误信息 | 说明 |
---|---|---|
400 | MISSING_ARGUMENTS:<key> | 缺少某个必选参数 |
400 | IMAGE_ERROR_UNSUPPORTED_FORMAT:<param> | 参数<param>对应的图像无法解析,有可能不是图像文件、或有数据破损。<param>为 image_ref1、image中的一个。请注意:<param>只会有一项,即第一个满足条件的名称 |
400 | NO_FACE_FOUND:<param> | 表示上传的 image_ref 的图像中,没有检测到人脸。<param>为 image_ref1、image中的一个。请注意:<param>只会有一项,即第一个满足条件的名称 |
400 | INVALID_IMAGE_SIZE:<param> | 客户上传的图像太大,具体是指像素尺寸的长或宽超过4096像素。<param>为 image_ref1、 image中的一个。请注意:<param>只会有一项,即第一个满足条件的名称 |
400 | LOW_QUALITY | image图片质量太差 |
400 | MULTIPLE_FACES | image图片中有多张人脸 |
400 | FMP_CONTENT_TYPE_ERROR | 视频错误,请重试或更换手机重试 |
400 | KEY_NOT_FOUND | encryption_type开启加密,但未配置加密公钥和解密私钥 |
403 | AUTHENTICATION_ERROR | 无效签名 |
403 | AUTHORIZATION_ERROR:<reason> |
api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限 <reason>取值:
|
403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 |
404 | API_NOT_FOUND | 所调用的API不存在 |
413 | Request Entity Too Large | 客户发送的请求大小超过了20MB限制或单张照片大小超过了2MB。该错误的返回格式为纯文本,不是json格式 |
500 | INTERNAL_ERROR | 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FinAuth客服或商务 |