接入文档
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 是否开启传输数据加密,详细说明见:加密说明
  • 0: 不开启
  • 1: SM2
  • 2: RSA
  • 必选 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字段知晓具体的结果及原因:
    • 1000系列状态码表示比对完成,比对通过
    • 2000系列状态码表示比对完成,比对失败
    • 3000系列状态码表示在比对的时候,参考数据调用情况
    • 3100系列状态码表示参考数据调用出错
    • 其他结果,请预留处理方案,对于未来可能的错误,我们可能持续增加错误码
    #状态码描述 result_message String 可通过此字段信息知晓具体的原因。具体见:result_code & result_message 对照表
    #比对结果 verification Json
  • "idcard":KYC验证的综合分数
    • "confidence":Float类型,取值[0,100],数字越大表示风险越小
    • “thresholds”:一组用于参考的置信度阈值,Object类型,包含三个字段,均为Float类型、取值[0,100]:
      • “1e-3”:风险为千分之一的置信度阈值
      • “1e-4”:风险为万分之一的置信度阈值
      • “1e-5”:风险为十万分之一的置信度阈值
      • “1e-6”:风险为百万分之一的置信度阈值
  • ref1:活体采集人像与上传的image_ref1的比对结果(仅当verify中存在image_ref1时返回,返回结果同idcard字段)
  • #附加返回信息
    face Json 当选用image方式时返回待验证图片image的属性:
    • "quality":人脸质量
    • "quality_threshold":人脸质量阈值
    • "rect":人脸坐标点,json类型
    • "orientation":人脸方向

    # 返回值示例

    正确请求返回示例

    {
       "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>取值:
    • API_KEY_BE_DISCONTINUED:api_key被停用
    • IP_NOT_ALLOWED:不允许访问的IP(预留设计)
    • LIMIT_REACHED:这个api_key对当前API的调用量达到上限。仅当api_key为测试key
    • MORE_RETRY_TIMES:比对重试次数达到上限
    • DENIED:无权限调用当前API
    • EXPIRED_SIGN:签名已过期
    • INVALID_SIGN:无效签名
    • 其他可能的错误码,请预留处理方案
    403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制
    404 API_NOT_FOUND 所调用的API不存在
    413 Request Entity Too Large 客户发送的请求大小超过了20MB限制或单张照片大小超过了2MB。该错误的返回格式为纯文本,不是json格式
    500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FinAuth客服或商务