接入文档
FaceID高级版
H5接入
API调用
回调说明
回调说明

# 1、Return_url 和 Notify_url 回调

说明:客户在GetToken方法中传入的 return_url 和 notify_url 会在完成 FaceID Lite 人脸核身后被系统回调。其中

return_url:可通过设置action_http_method选择Post方法或者Get方法回调,直接通过页面跳转实现;

notify_url:会通过Post方法回调,由FaceID后台发起调用。出于安全性考虑,FaceID验证服务对服务器端回调端口有白名单要求,支持的端口有:443,5000,16003,8883,8028(如果回调地址不是HTTPS的,则推荐进行签名校验)。

1.1、采用Post回调的内容为一个form格式数据,具体的内容如下表所示:

字段 类型 说明 示例
data String 人脸核身返回值(json格式),具体见返回值说明
sign String 数据段的签名,签名方法为 sign = sha1(API_SECRET + json_data),其中sha1返回的字符均为小写 ac041f49940c5afb2640a251633a8029ae69c1d5

# 返回值说明

返回值 类型 说明 示例 return_url notify_url
status String 表示目前FaceID Lite的使用状态:
  • NOT_STARTED:get_token 之后,并没有调用过do方法,还没有开始验证
  • PROCESSING:正在进行FaceID Lite验证
  • WEBRTC_UNSUPPORTED:表示浏览器不支持引起失败
  • OK:完成了FaceID Lite验证(OK并不表示通过了验证,是流程正常结束)
  • FAILED:验证流程未完成或出现异常
  • CANCELLED:用户主动取消了验证流程
  • TIMEOUT:流程超时
(当处于“NOT_STARTED”或者“PROCESSING”状态时,idcard_info / liveness_result /verify_result字段均不会返回
"OK"
fail_reason String 当“get_fail_reason”=1时,可获取“WEBRTC_UNSUPPORTED”失败原因
  • NETWORK_ERROR:因为网络问题无法连接
  • PERMISSIONS_ERROR :用户拒绝摄像头权限或浏览器(APP)不支持唤起摄像头权限
  • SUPPORT_ERROR:浏览器不支持webRTC API 等
“NETWORK_ERROR”
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"
}
idcard
_info
Json 身份证识别的结果,此字段在idcard_mode = 0时不返回;如果用户中途中断了活体流程,则此字段也不返回 内容包括:
  • idcard_mode:表示get_token时选择的idcard_mode
  • idcard_uneditable_field:表示get_token是选择的idcard_uneditable_field
  • idcard_mode_user:该字段仅在idcard_mode=4时返回,表示用户选择的身份证信息录入模式
    • 0:选择拍摄身份证人像面
    • 1:选择手输身份证信息
  • 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:文字识别结果,详见【FaceID Ocridcard API】
    • upload_times:在FaceID Lite 人脸核身流程中身份证人像面上传的次数
  • back_side:身份证国徽面的识别结果(如果不用拍摄身份证国徽面则不返回此字段)
    • ocr_result:文字识别结果,详见【FaceID Ocridcard API】
    • upload_times:在FaceID Lite 人脸核身流程中身份证国徽面上传的次数
  • ocr_front_quality:身份证人像面各字段质量判断及逻辑判断结果(该字段仅在lite2.0下进行返回)
  • ocr_back_quality:身份证国徽面各字段质量判断及逻辑判断结果(该字段仅在lite2.0下进行返回)
{
 "idcard_mode": "1",
 "idcard_uneditable_field": "idcard_number,
 idcard_valid_date",
 "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 活体检测结果;如果用户中途中断了活体流程,则此字段不返回
  • result:活体检测的结果,返回值分为两类:
    • PASS:活体检测通过
    • FAIL:活体检测失败
  • procedure_type:返回本次活体所使用的活体验证方式:
    • will:通过意愿确认方式进行活体验证
  • details:活体检测结果的细节:
    • 当procedure_type取值为"will"时:
      • FACE_NOT_FOUND:<未检测到人脸次数>
      • SIDE_FACE:<未正对摄像头次数(侧脸)>
      • UPDOWN_FACE:<未正对摄像头次数(仰脸或低头)>
      • EYE_OCCLUSION:<遮挡眼部次数>
      • MOUTH_OCCLUSION:<遮挡嘴部次数>
      • AWAY_FROM_CAMERA:<过于远离摄像头次数>
      • CLOSE_TO_CAMERA:<过于靠近摄像头次数>
      • FACE_OUT_OF_CAMERA:<未正视摄像头次数>
      • HIGH_BRIGHTNESS:<光线过亮的次数>
      • LOW_BRIGHTNESS:<光线过暗的次数>
      • LOW_FACE_QUALITY:<视频中人脸质量太差的次数>
  • face_genuineness:表示对假脸攻击的判定,它包含四组置信度和阈值,均为实数取值[0,1]区间。如果一个置信度大于其对应的阈值,则可以认为存在对应类型的假脸攻击
    • synthetic_face_confidence:<合成脸的置信度>
    • synthetic_face_threshold:<合成脸的阈值>
    • mask_confidence:<面具的置信度>
    • mask_threshold:<面具的阈值>
    • screen_replay_confidence:<屏幕翻拍的置信度>
      • screen_replay_threshold:<屏幕翻拍的阈值>
{
"result": "PASS/FAIL",
"procedure_type": "will",
"details": {
 "UPLOAD_TIMES": 5,
 "FACE_NOT
 _FOUND": 0,
 "LOW_FACE
 _QUALITY": 0,
 "INVALID_VIDEO
 _DURATION": 1,
 "SR_ERROR": 2,
 "NOT_SYNCHRONIZED":
 1,
 "VIDEO_FORMAT
 _UNSUPPORTED": 0,
 "NO_AUDIO": 0
},
"face_genuineness": {
 "synthetic_face
 _confidence": 0.88,
 "synthetic_face
 _threshold": 0.5,
 "mask_confidence": 0.32,
 "mask_threshold": 0.5,
 "screen_replay
 _confidence": 0,
 "screen_replay
 _threshold": 0.5
} }
verify
_result
Json 人脸比对结果;如果用户中途中断了活体流程,则此字段不返回
  • error_message:在做人脸比对的时候出现错误
    • null:表示没有出现错误
    • NO_SUCH_ID_NUMBER:没有此身份证号码的记录。此错误会产生计费
    • ID_NUMBER_NAME_NOT_MATCH:身份证号码与提供的姓名不匹配。此错误会产生计费
    • IMAGE_ERROR_UNSUPPORTED_FORMAT: 姓名和身份证号正确,但图片无法解析或者没有可比对图片。此错误会产生计费
    • NO_FACE_FOUND:对应的图像没有检测到人脸。此错误会产生计费
    • DATA_SOURCE_ERROR:调用比对数据发生错误,一般来说是数据出错。出现此错误时建议停止业务,并立即联系FaceID客服或商务,待确认后再开启业务
    • INTERNAL_ERROR:服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务
  • result_faceid:人脸核身的综合分数
    • "confidence":综合分数的置信度,Float类型,取值[0,100],数字越大表示风险越小
    • “thresholds”:一组用于参考的置信度阈值,Object类型, 包含四个字段,均为Float类型、取值[0,100]:
      • “1e-3”:风险为千分之一的置信度阈值
      • “1e-4”:风险为万分之一的置信度阈值
      • “1e-5”:风险为十万分之一的置信度阈值 
      • “1e-6”:风险为百万分之一的置信度阈值
  • result_ref[x]:活体采集人像与上传的image_ref[x]的比对结果(同result_faceid)
  • result_idcard_photo:活体采集人像与身份证照片上的人脸比对的结果(同result_faceid)
  • result_idcard_datasource:身份证照片上的人脸和参考比对数据照片比对的结果(同result_faceid)
  • id_exceptions:
    • 返回人脸核身相关的异常情况,如证件号码是否曾被冒用来攻击FaceID活体检测等问题。调用者可通过此对象增进对比对结果的解读 本对象仅在人脸核身时(comparison_type == 1)返回,返回包含如下字段:
      • "id_attacked":Int类型,判别证件号码是否曾被冒用来攻击FaceID活体检测, 取值1表示曾被攻击、取值0表示未被攻击。攻击形态包括但不限于戴面具、换人 攻击、软件3D合成人脸等手段。若被判别为“是”,则有可能这个身份证号码目前 存在被利用的风险。注意:判别为“是”不意味证件持有者本人参与攻击,有可能 其证件被他人盗用而本人无感知
      • "id_photo_monochrome":Int类型,参考照片的色彩判断,取值1表示 是黑白照片、取值0表示是彩色照片。参考数据存在一部分人像照片是黑白的现象, 黑白的照片会影响比对质量,一般来说将降低比对分数。本字段表达这样的异常
      • verify_time:验证发生的时间戳(单位:秒),仅当return_verify_time=1时返回该字段
{
"verify_time": 1462259763,
"result_faceid": {
 "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
 }
},
"id_exceptions": {
 "id_attacked": 0,
 "id_photo_
 monochrome": 0
 }
}
will_result Json 意愿活体结果;未开通意愿核身高级版、意愿比对高级版SKU或procedure_type不为will,则此字段不返回
  • result:意愿认证问答的结果
    • PASS:意愿认证通过
    • FAIL:意愿认证失败
  • will_error_message:在意愿确认时出现的错误
    • ANSWER_INCONSISTENT:意愿表达与标准答案不一致
    • NO_AUDIO:意愿确认用户回答音频无声音
    • FUNASR_ERR:语音识别服务异常
    • ACTION_FAIL:动作检测失败
    • NOT_STARTED:未开始当前问题的意愿认证
通过
"will_result": [
  { "will_error_message": "",
   "result": "PASS"
  }]
失败"
will_result": [
  { "result": "FAIL",
   "will_error_message": "ACTION_FAIL"
  }]
multifaces_tag String 仅当return_multifaces_tag参数为1时,返回此字段
  • 0:单人脸
  • 1:多人脸
0

1.2、采用Get回调时会在return_url地址拼接biz_id参数,请提取地址中拼接的biz_id用于作为get_result的入参。

示例:

●https://yourdomainname/xxx?biz_id=xxx

●https://yourdomainname/xxx?xxx=xxx&biz_id=xxx

●https://yourdomainname/xxx?biz_id=xxx&xxx=xxx#xxx

参数 类型 说明 示例
biz_id String 通过get_token返回的活体业务编号 146225974852b13fb5-8dfb-4537-a62b-a641d5e929f1
该文档未解决您的疑问?查看常见问题