H5接入说明

H5接入流程

  • 通过get_biz_token API接口，设置参数，并获取biz_token。
  • 页面跳转到FaceID H5页面进入验证流程。
  • 验证流程结束后，可以通过get_result接口获取本次验证流程的详细信息。

下面对各个步骤进行详细的说明。

第1步：获取biz_token

API名称

Get_biz_token

说明

客户服务器端通过此接口可以获得一个biz_token（biz_token唯一且只能使用一次，有效期为1小时，但是您可以在1天内对该结果进行查询）。该请求是POST方法，参数中要包括用户后续验证的相关信息。

API地址

POST https://api.megvii.com/faceid/lite/get_token

参数

参数名可选/必选类型说明
api_key必选String调用此API的api_key
api_secret必选String调用此API的api_key的secret
return_url必选String用户完成或取消验证后网页跳转的目标URL。（回调方法为Post）
notify_url必选String用户完成验证、取消验证、或验证超时后，由FaceID服务器请求客户服务器的URL。（推荐为HTTPS页面，如果为HTTP则用户需要通过签名自行校验数据可信性，回调方法为Post）注：出于安全性考虑，FaceID服务对服务器端回调端口有白名单要求，支持的端口有：443，5000，16003，8883，8028。
biz_no必选String客户业务流水号，该号必须唯一。并会在notify和return时原封不动的返回给您的服务器，以帮助您确认每一笔业务的归属。此字段不超过128字节。
biz_extra_data可选String在调用notify_url和return_url时会返回的额外数据，用户可以用此接口来传递一些额外信息，以帮助您调试和信息传递。此字段不超过4096字节。
web_title可选String验证网页展示用的标题文字。此字段不超过32字节，但考虑到显示效果，建议控制在10个中文字符以内。此参数默认为空，此时系统将采用默认的标题。
liveness_preferences可选String本参数可选，通过一系列配置项来调节活体检测的严格度。目前可用的选项有：
“none”：表示没有特别的选项，此为默认值。
"video_strict"：表示针对上传的视频进行相对严格的活体检测，此设置会提高安全性，但在一定程度上影响通过率。
注意：设置其他值，均会返回400（BAD_ARGUMENTS）。
comparison_type必选Int本次验证服务的类型。
0：表示活体照片和上传照片进行比对(人脸比对)
1：表示活体照片和参考数据进行比对（KYC验证）
idcard_mode条件必选String当comparison_type=1，必须传入此字段。传递参数“0”，“1”，“2”，“3”或“4”，表示获取用户身份证信息的方法。传递其他值调用将识别，返回错误码400（BAD_ARGUMENTS）。
0：不拍摄身份证，而是通过 idcard_name / idcard_number 参数传入；
1：仅拍摄身份证人像面，可获取人像面所有信息；
2：拍摄身份证人像面和身份证国徽面，可获取身份证所有信息；
3：不拍摄身份证，但会要求用户在界面上输入身份证号和姓名；
4：拍摄身份证人像面或用户输入身份证号和姓名，用户可在界面上自行选择身份证录入方法。
idcard_uneditable_field条件可选String选择用户不可编辑的字段。当选择拍摄身份证来获取上面的文字信息时，会由于OCR算法的问题导致文字识别不准确（如：生僻字、形近字），通过该参数可以限制用户对识别得到的结果进行编辑。（如：身份证号的识别都是准确的，可以限制用户不能编辑此字段）。
目前可以选为不可修改的字段有 姓名（idcard_name），身份证号（idcard_number），身份证有效期（idcard_valid_date），签发机关（idcard_issued_by）。传递参数时用逗号隔开，可以同时设置多个参数。例子：idcard_uneditable_field=idcard_number,idcard_valid_date 表示身份证号和过期时间都不可编辑，如果尝试编辑则会提示需要重新拍摄。传入其他值或格式不对，本次调用将失败，返回错误码400（BAD_ARGUMENTS）。
本参数默认值为空，表示所有字段都可以编辑。本参数默认值为空，表示所有字段都可以编辑。
idcard_name条件必选String姓名。当comparison_type=1，必须传入此字段
idcard_number条件必选String身份证号。当comparison_type=1, 必须传入该字段
uuid条件必选String当comparison_type=0时，该字段用于标志本次识别对应的用户的唯一ID，要求不长于128字节。建议对来自同一用户的比对请求使用同样的ID。
image_ref1条件必选File由您自己提供的参照人脸照片，File类型。当comparison_type=0时，必选。
image_ref2可选File由您自己提供的参照人脸照片，File类型
multi_oriented_detection可选String决定对于image_ref[x]参数对应的图片，当检测不出人脸时，是否旋转90度、180度、270度后再检测人脸。本参数取值只能是 “1” 或 "0" （缺省值为“0”）:
“1”：要旋转检测；
“0”：不旋转； 其他值：返回错误码400（BAD_ARGUMENTS）
fmp_mode可选String决定在活体检测结果中，是否进行云端假脸攻击判断，默认值为1。
1：在活体检测结果中，不进行云端假脸攻击判断（合成脸、面具攻击、屏幕翻拍），但返回假脸攻击具体分数。您可以根据自身业务需要，结合云端假脸攻击具体分数设计后续流程。
0：在活体检测结果中，判断云端假脸攻击情况。

返回结果

字段类型说明
request_idString用于标示本次请求的唯一的字符串，总返回该字段
time_usedInt整个请求所花费的时间，单位为毫秒，总返回该字段
tokenString一个字符串，可用于DoVerification接口，调用DoVerification时传入此参数，即可按照上述配置进行活体检测。
（注：每个token只能被使用一次）
biz_idString业务流串号，可以用于反查比对结果。
expired_timeInt一个时间戳，表示token的有效期。
error_messageString错误原因，请求调用失败时返回error字段, 该字段可能的内容参见下面的错误说明。

错误说明

error字段可能的错误包括：

error说明HTTP状态码
IMAGE_ERROR_UNSUPPORTED_FORMAT: 参数对应的图像无法正确解析，有可能不是一个图像文件、或有数据破损。为 image_ref1、 image_ref2中的一个。请注意：只会有一项，即第一个满足条件的名称。400
NO_FACE_FOUND表示上传的 image_ref[x] 的图像中，没有检测到人脸。400
MULTIPLE_FACES表示上传的 image_ref[x] 的图像中，检测到了多张人脸。400
INVALID_NAME_FORMATKYC验证时，idcard_name参数字符数过多（多于32字符）、或者使用错误的编码（姓名要求以UTF-8编码）。400
INVALID_IDCARD_NUMBERKYC验证时，idcard_number参数不是正确的身份证号码格式。身份证号码必定为18位数字，且最后一位可以是X（大小写均可）。400
MISSING_ARGUMENTS:缺少某个必选参数（参数名为key）400
BAD_ARGUMENTS:某个参数（参数名为key）解析出错400
AUTHENTICATION_ERRORapi_key 和 api_secret 不匹配。403
AUTHORIZATION_ERROR:鉴权失败，例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等403
CONCURRENCY_LIMIT_EXCEEDED请求超过并发403
API_NOT_FOUND所调用的API不存在。404
INTERNAL_ERROR内部错误500

示例

返回结果示例：成功

{
    "time_used": 5,
    "token": "34fb21937e47ae719f11cbc719615687",
    "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
    "request_id": "1462257147,3149525e-2c24-4862-8e9f-92040595f0a4",
    "expired_time": 1462257765
}

返回结果示例：return_url没填导致的错误

{
    "error_message": "BAD_ARGUMENTS: return_url",
    "request_id": "1461740007,71eeb124-08f0-47b3-8fc8-ac048cfa1372",
    "time_used": 4
}

第2步：跳转URL

API名称

DoVerification

说明

此接口提供 FaceID Lite 验证服务，通过 GetToken 接口获得 token，可利用此接口转跳到对应的网页验证。

API地址

GET https://api.megvii.com/faceid/lite/do

参数

参数名可选/必选类型说明
token必选string由get_token返回的token。

返回及其他说明

此接口调用返回一个Web页面，所有的错误信息均通过可视化的Web页面返回。

第3步：Return_url 和 Notify_url 回调

说明

客户在GetToken方法中传入的 return_url 和 notify_url 会在完成 FaceID Lite 验证后被系统回调。其中

  1. return_url：会通过Post方法回调，直接通过页面跳转实现；
  2. notify_url：会通过Post方法回调，有FaceID后台发起调用。出于安全性考虑，FaceID服务对服务器端回调端口有白名单要求，支持的端口有：443，5000，16003，8883，8028；（如果回调地址不是HTTPS的，则推荐进行签名校验）

回调的内容为一个Json数据，具体的内容如下表所示。

参数

参数名类型说明
datastring验证返回值，具体见“”FaceID Lite 返回值说明
signstring数据段的签名，签名方法为 sign = sha1(API_SECRET + json_data)，其中sha1返回的字符均为小写。

第4步（可选）：获取验证详细信息

API名称

get_result

说明

验证流程结束后，用户服务器可以调用get_result接口，获取本次验证的详细信息。

API地址

GET https://api.megvii.com/faceid/lite/get_result

参数

参数名可选/必选类型说明
api_key必选String调用此API的api_key；
api_secret必选String调用此API的api_key的secret；
biz_id必选String通过 get_token, notify_url 或者 return_url 返回的活体业务编号。
return_image可选String此参数为可选参数，可在下面三种参数中选择，决定了是否返回活体图像数据：
0（默认）：不需要图像
1：需要返回最佳活体质量图
2：需要返回身份证人像面图像
3：需要返回身份证国徽面图像
4：需要返回所有图像

返回结果

返回值说明

返回值说明见“FaceID Lite 返回值说明”表格。

错误码列表

error说明HTTP状态码
RESULT_NOT_FOUND此错误类型表示传入的业务编号错误。400
IMAGE_ERROR_UNSUPPORTED_FORMAT: 参数对应的图像无法正确解析，有可能不是一个图像文件、或有数据破损。为 image_ref1、 image_ref2中的一个。请注意：只会有一项，即第一个满足条件的名称。400
NO_FACE_FOUND表示上传的 image_ref[x] 的图像中，没有检测到人脸。400
MULTIPLE_FACES表示上传的 image_ref[x] 的图像中，检测到了多张人脸。400
INVALID_NAME_FORMATKYC验证时，idcard_name参数字符数过多（多于32字符）、或者使用错误的编码（姓名要求以UTF-8编码）。400
INVALID_IDCARD_NUMBERKYC验证时，idcard_number参数不是正确的身份证号码格式。身份证号码必定为18位数字，且最后一位可以是X（大小写均可）。400
MISSING_ARGUMENTS:缺少某个必选参数（参数名为key）400
BAD_ARGUMENTS:某个参数（参数名为key）解析出错400
AUTHENTICATION_ERRORapi_key 和 api_secret 不匹配。403
AUTHORIZATION_ERROR:鉴权失败，例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等403
CONCURRENCY_LIMIT_EXCEEDED请求超过并发403
DATA_DESTROYED超过可查询时间或超过最多可查询次数403
NON_ENTERPRISE_CERTIFICATION客户未进行企业认证403
BALANCE_NOT_ENOUGH余额不足403
ACCOUNT_DISABLED账户已停用403
API_NOT_FOUND所调用的API不存在。404
INTERNAL_ERROR内部错误500

附：FaceID Lite返回值说明

字段类型说明
request_idString用于标示本次请求的唯一的字符串，总返回该字段
time_usedInt整个请求所花费的时间，单位为毫秒，总返回该字段
statusString表示目前 FaceID Lite 的使用状态：
NOT_STARTED：get_token 之后，并没有调用过 do 方法，还没有开始验证；
PROCESSING：正在进行 FaceID Lite 验证；
OK：完成了 FaceID Lite 验证（OK并不表示通过了验证，是流程正常结束）；
FAILED：验证流程未完成或出现异常；
CANCELLED：用户主动取消了验证流程；
TIMEOUT：流程超时。传入的biz_token，原样返回
(当处于“NOT_STARTED”或者“PROCESSING”状态时，idcard_info / liveness_result /verify_result字段均不会返回。之前在get_biz_token中设置的biz_no字段，如果没有设置，返回为空字符串
biz_infoJson包含：biz_id, biz_no, biz_extra_data
biz_id：业务流串号，可以用于反查比对结果； biz_no：客户业务流水号，会在notify和return时原封不动的返回给客户； biz_extra_data：在调用 notify_url 和 return_url 时会返回的额外数据，
用户可以用此接口来传递一些额外信息。
idcard_infoJson身份证识别的结果，此字段在 idcard_mode = 0 时不返回；如果用户中途中断了活体流程，则此字段也不返回。
内容包括：
idcard_mode：表示 get_token 时选择的 idcard_mode；
idcard_uneditable_feild：表示 get_token 是选择的 idcard_uneditable_feild；
idcard_mode_user：该字段仅在idcard_mode=4时返回，表示用户选择的身份证信息录入模式 0：选择拍摄身份证人像面； 1：选择手输身份证信息；
idcard_number：表示最终经过用户确认的身份证号 （根据idcard_uneditable_feild可能被修改过）；
idcard_name：表示最终经过用户确认的姓名 （根据idcard_uneditable_feild可能被修改过）；
idcard_valid_date：表示最终经过用户确认的身份证有效期 （根据idcard_uneditable_field可能被修改过，如果不用拍摄身份证国徽面则不返回此字段）；
idcard_issued_by：表示最终经过用户确认的身份证签发机关 （根据idcard_uneditable_field可能被修改过，如果不用拍摄身份证国徽面则不返回此字段）；
front_side：身份证人像面的识别结果（如果不用拍摄身份证人像面则不返回此字段）；
ocr_result：文字识别结果；
upload_times：在FaceID Lite验证流程中身份证人像面上传的次数；
back_side：身份证国徽面的识别结果（如果不用拍摄身份证国徽面则不返回此字段）；
ocr_result：文字识别结果；
upload_times：在FaceID Lite验证流程中身份证国徽面上传的次数；
ocr_front_quality：身份证人像面各字段质量判断及逻辑判断结果；
ocr_back_quality：身份证国徽面各字段质量判断及逻辑判断结果；
liveness_resultJson活体检测结果；如果 face_genuineness：表示对假脸攻击的判定，它包含四组置信度和阈值，均为实数取值［0，1］区间。如果一个置信度大于其对应的阈值，则可以认为存在对应类型的假脸攻击。用户中途中断了活体流程，则此字段不返回。
result：活体检测的结果，返回值分为两类：
PASS：活体检测通过； FAIL：活体检测失败；
注：
当fmp_mode为"0"，该字段会考虑云端假脸攻击情况（即：face_genuineness字段）。当云端假脸攻击被检测出来时，会返回FAIL；
当fmp_mode为"1"，该字段不会考虑云端假脸攻击情况。当云端假脸攻击被检测出来时，会返回PASS。不过，您依然可以根据自身的业务，并结合”face_genuineness“字段所返回的分数进行相关的业务判断。

details：活体检测结果的细节：

UPLOAD_TIMES：<活体视频上传次数>；
FACE_NOT_FOUND：<视频中没有检测到人脸的次数>；
LOW_FACE_QUALITY：<视频中人脸质量太差的次数>；
INVALID_VIDEO_DURATION：<视频时长不对的次数>；
SR_ERROR：<语音识别结果有误的次数>；
NOT_SYNCHRONIZED：<视频唇语识别错误的次数>；
NO_AUDIO：<视频无声音的次数>；
VIDEO_FORMAT_UNSUPPORTED：<视频格式错误的次数>；


face_genuineness：表示对假脸攻击的判定，它包含四组置信度和阈值，均为实数取值［0，1］区间。如果一个置信度大于其对应的阈值，则可以认为存在对应类型的假脸攻击。
synthetic_face_confidence：<合成脸的置信度>
synthetic_face_threshold：<合成脸的阈值>
mask_confidence：<面具的置信度>
mask_threshold：<面具的阈值>
screen_replay_confidence：<屏幕翻拍的置信度>
screen_replay_threshold：<屏幕翻拍的阈值>
verify_resultJson人脸比对结果；如果用户中途中断了活体流程，则此字段不返回。
error_message：在做验证的时候出现错误
null：表示没有出现错误
NO_SUCH_ID_NUMBER：KYC验证时，参考数据中没有此身份证号码的记录。此错误会产生计费。
ID_NUMBER_NAME_NOT_MATCH：KYC验证时，参考数据中存在此身份证 号码，但与提供的姓名不匹配。此错误会产生计费。
IMAGE_ERROR_UNSUPPORTED_FORMAT: data_source：KYC验证时，姓名和身份证号已经通过核查。但图片无法解析、或者没有图片。此错误会产生计费。
DATA_SOURCE_ERROR：KYC验证时调用参考数据发生错误，一般来说是参考数据出错。出现此错误时建议停止业务，并立即联系FaceID客服或商务，待 确定参考数据正常后再开启业务。
INTERNAL_ERROR：服务器内部错误，当此类错误发生时请再次请求，如 果持续出现此类错误，请及时联系FaceID客服或商务。

result_faceid：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_faceid）

result_idcard_photo：活体采集人像与身份证照片上的人脸比对的结果；（同result_faceid）

id_exceptions： 返回身份相关的异常情况，如身份证号码是否曾被冒用来攻击FaceID活体检测、参考数据人像照片是否存在质量不佳等问题。调用者可通过此对象增进对比对结果的解读。本对象仅在KYC验证时（comparison_type == 1)返回，返回包含如下字段：
"id_attacked"：Int类型，判别身份证号码是否曾被冒用来攻击FaceID活体检测， 取值1表示曾被攻击、取值0表示未被攻击。攻击形态包括但不限于戴面具、换人 攻击、软件3D合成人脸等手段。若被判别为“是”，则有可能这个身份证号码目前 存在被利用的风险。注意：判别为“是”不意味身份持有者本人参与攻击，有可能 其身份被他人盗用而本人无感知。
"id_photo_monochrome"：Int类型，参考数据人像照片的色彩判断，取值1表示 是黑白照片、取值0表示是彩色照片。参考数据存在一部分人像照片是黑白的现象， 黑白的照片会影响比对质量，一般来说将降低比对分数。本字段表达这样的异常。
imagesJson活体检测得到的图像，调用时通过 return_image 来选择，或以jpg编码并用base64字符串返回，或返回为null。
只有当 status 返回字段为 "OK" 时，图像才会返回。
image_best：质量最佳的活体图像； image_idcard_back：最后一次上传的身份证国徽面；
image_idcard_front：最后一次上传的身份证人像面。
注意：此字段仅在get_result接口调用时才会返回有图像信息，在notify_url和return_url不返回图片数据信息

当前版本

  • v1.1.0

历史版本

← SDK-错误码说明小程序接入说明 →