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://openapi.faceid.com/lite/v1/get_biz_token

参数

参数名可选/必选类型说明
sign必选String根据API_KEY和API_SECRET生成的签名，签名算法参见相关文档
sign_version必选String签名算法版本，当前仅支持：hmac_sha1
return_url必选String流程结束后跳转到客户定义的页面（回调方法为get return_url?biz_token=xxx），URL限定为http或https且非内网地址
notify_url必选String流程结束后，FaceID会通知客户服务器，post请求到该url，必须以http或者https开头, post的参数名是data，data的值是一个json字符串，内容包括：biz_token, error_code，error_msg。biz_token是get_biz_token接口获得的，error_code和error_msg参见后文详述
biz_no可选String"默认为空"。客户业务流水号，建议设置为您的业务相关的流水串号并且唯一。此字段不超过128字节
comparison_type必选Int本次验证服务的类型。
0：表示活体照片和上传照片进行比对(人脸比对)
liveness_type必选String表示活体检测的类型，当前仅支持：video_number
security_level可选Int表示对比对结果的严格程度限制，默认值为2，可以根据您的场景，选择相应的安全规则，越严格，准确性要求越高，通过率也会相应下降。支持：1(宽松),2(常规),3(严格)
liveness_preferences可选Int1：默认值，表示视频活体采用宽松模式（4个数字对3个就能通过）; 2：表示视频活体采用严格模式（4个数字完全正确才通过）
liveness_retry_count可选Int当视频验证出错时，视频允许上传最大重试次数，默认为3次，用户可以通过该参数设置为1～5
uuid条件必选String当comparison_type=0时，该字段用于标志本次识别对应的用户的唯一ID，要求不长于128字节。建议对来自同一用户的比对请求使用同样的ID。
image_ref1条件必选File由您自己提供的参照人脸照片，File类型。当comparison_type=0时，必选。
image_ref2可选File由您自己提供的参照人脸照片，File类型

返回结果

字段类型说明
biz_tokenString生成的biz_token，该字段后续用于调用H5页面。请求调用成功时会返回biz_token字段
request_idString用于标示本次请求的唯一的字符串，总返回该字段
time_usedInt整个请求所花费的时间，单位为毫秒，总返回该字段
errorString错误原因，请求调用失败时返回error字段, 该字段可能的内容参见下面的错误说明

错误说明

error字段可能的错误包括：

error说明HTTP状态码
MISSING_ARGUMENTS:缺少某个必选参数（参数名为key）400
BAD_ARGUMENTS:某个参数（参数名为key）解析出错400
AUTHORIZATION_ERROR:鉴权失败，例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等403
CONCURRENCY_LIMIT_EXCEEDED请求超过并发429
INTERNAL_ERROR内部错误500
Request Entity Too Large客户发送的请求大小超过了20MB限制413

示例

示例：仅做核验

curl -X POST "https://openapi.faceid.com/lite/v1/get_biz_token"
-F sign=<sign>
-F sign_version=hmac_sha1
-F return_url=<return_url>
-F notify_url=<notify_url>
-F liveness_type=video_number
-F comparison_type=0

返回结果示例：成功

{
    "request_id": "1462257147,3149525e-2c24-4862-8e9f-92040595f0a4",
    "time_used": 5,
    "biz_token":"1462257147,34fb21937e47ae719f11cbc719615687",
}

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

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

第2步：拼接URL并调用

客户服务器端调用get_biz_token后，获得了biz_token。请按照以下规则拼接成H5 URL，客户页面跳转到该URL，进入验证流程。

Lite URL

https://openapi.faceid.com/lite/v1/do/biz_token

其中biz_token是上文中提到的get_biz_token的返回值，例如：biz_token为1462257147,34fb21937e47ae719f11cbc719615687，那么上面的url就是： https://openapi.faceid.com/lite/v1/do/1462257147,34fb21937e47ae719f11cbc719615687

说明

  • 进入Lite URL后，就开始进入了FaceID 验证的流程。
  • 如果流程结束(验证过程完成)，或者过程中发生了不可重试的错误（例如余额不足，超过重试次数，等等），Lite会跳转到用户之前定义的return url中。建议用户通过get_result接口查询本次验证的详情。同时，我们还会向之前设置的notify_url发送一个post请求，data中包括以下字段：biz_token，error_code，error_msg。处理notify的示例代码如下：
public class ParamController {
    /**
    * notify_url 使用 JavaSpring MVC 框架接受post过来的表单参数
    */
    @RequestMapping(method = RequestMethod.POST, value = "/notify")
    @ResponseBody

    public String toNotify(HttpServletRequest request){
        //获取notify过来的json
        String data = request.getParameter("data");
        System.out.println(String.format("%s",data));
        return String.format("%s",data);
    }
}

页面中典型错误提示和说明

错误提示说明
无效请求，或当前请求已过期Token过期，或者无效token
视频中没有检测到人脸，请重试活体验证过程中，录入的视频中找不到人脸
视频过长，请重试活体验证过程中，录入的视频过大（最大值为20M）
视频质量太差，请重试活体验证过程中，录入的视频质量太差，无法进行识别
未通过念数字识别，请重试活体验证过程未数字语音识别
没有声音，请重试活体验证过程中，录入的视频没有声音，可能的原因是用户手机中未开启该浏览器的语音权限
视频格式无法识别，请重试活体验证过程中，录入的视频格式无法识别

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

API名称

get_result

说明

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

API地址

GET https://openapi.faceid.com/lite/v1/get_result

参数

参数名可选/必选类型说明
sign必选String根据API_KEY和API_SECRET生成的签名，签名算法参见相关文档
sign_version必选String签名算法版本，当前仅支持：hmac_sha1
biz_token必选Stringget_biz_token接口返回的biz_token
verbose可选Int表示返回数据的详细程度，取值如下：
0：仅返回结论；
1：默认值，返回结论与摘要信息

返回结果

字段类型说明
request_idString用于标示本次请求的唯一的字符串，总返回该字段
time_usedInt整个请求所花费的时间，单位为毫秒，总返回该字段
errorString错误原因，请求调用失败时返回error字段, 该字段可能的内容参见下面的错误说明
biz_tokenString传入的biz_token，原样返回
biz_noString之前在get_biz_token中设置的biz_no字段，如果没有设置，返回为空字符串
result_codeInt结果码
result_messageString结果信息
actionString当前该字段为空列表
imagesJson字段如下：
image_best: 活体检测获得的最优照片，base64编码。该照片会和用户上传的上传照片进行比对。
verificationJson人脸比对的详细结果，可能的字段如下：
- ref1: Json类型，表示活体照片和image_ref1的比对结果
-- confidence: 比对结果的置信度，Float类型，取值［0，100］，数字越大表示风险越小。
-- thresholds: 一组用于参考的置信度阈值，Json类型，包含三个字段，均为Float类型、取值［0，100］:
--- 1e-3: 误识率为千分之一的置信度阈值;
--- 1e-4: 误识率为万分之一的置信度阈值;
--- 1e-5: 误识率为十万分之一的置信度阈值;
--- 1e-6: 误识率为百万分之一的置信度阈值;

- ref2: Json类型，表示活体照片和image_ref2的比对结果，字段和上面的相同。

结果码说明

result_coderesult_message说明
1000SUCCESS待比对照片与上传照片对比是同一个人
2000PASS_LIVING_NOT_THE_SAME待比对照片与上传照片对比不是同一个人
4100FAIL_LIVING_FACE_ATTACK云端活体验证失败
4100CHANGE_FACE_ATTACK活体验证视频中发生了换脸攻击（视频中不是同一个人）
4200NO_FACE_FOUND活体验证视频中没有检测到人脸
4200FACE_QUALITY_TOO_LOW活体验证视频中质量太差
4200INVALID_VIDEO_DURATION活体验证视频中长度不符合要求（2s～20s）
4200VIDEO_TOO_LARGE活体验证视频过大
4200SR_ERROR活体验证视频中，用户读数语音不符合要求
4200NOT_SYNCHRONIZED活体验证视频中，用户读数唇语不符合要求
4200NO_AUDIO活体验证视频无声音
4200VIDEO_FORMAT_UNSUPPORTED活体验证视频格式无法识别
4200LIP_VOICE_NOT_SYNC活体验证视频中语音唇语不同步
4200VIDEO_OK活体验证视频可用
4200VIDEO_MANY_TIMES活体验证视频上传超过阈值（默认为3，get_biz_token接口中liveness_retry_count参数可以设置）
4200VIDEO_INTERNAL_ERROR活体验证内部错误
5000NON_ENTERPRISE_CERTIFICATION客户未进行企业认证
5000BALANCE_NOT_ENOUGH余额不足
5000ACCOUNT_DISABLED账户已停用
6000USER_CANCEL用户主动退出流程
9000LIVING_NOT_START验证流程尚未开始

错误说明

error字段可能的错误包括：

HTTP状态码error说明
400MISSING_ARGUMENTS:缺少某个必选参数（参数名为key）
400BAD_ARGUMENTS:某个参数（参数名为key）解析出错
400BIZ_TOKEN_USEDbiz_token 已使用
403AUTHORIZATION_ERROR:鉴权失败，例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等
403DATA_DESTROYED超过可查询时间或超过最多可查询次数
429TOO_MANY_REQUESTS请求超过并发
500INTERNAL_ERROR内部错误
413Request Entity Too Large客户发送的请求大小超过了20MB限制

verification示例

人脸比对(comparison_type=0), 传入了image_ref1, image_ref2

"verification": {
    "ref1": {  ## 活体照片和上传照片1的比对结果
        "confidence": 86.4735,
        "thresholds": {
            "1e-3": 62.168713,
            "1e-4": 69.31534,
            "1e-5": 74.39926,
            "1e-6": 78.038055
        },
    "ref2": {  ## 活体照片和上传照片2的比对结果
          "confidence": 86.4735,
          "thresholds": {
              "1e-3": 62.168713,
              "1e-4": 69.31534,
              "1e-5": 74.39926,
              "1e-6": 78.038055
          }
      }
    }
}

当前版本

  • v1.0.0

历史版本