H5和微信小程序-接入文档

API

get_biz_token

接口说明

POST方法，用户server端通过此接口设置相关的参数，并获得一个用于验证biz_token。

接口地址

POST https://openapi.faceid.com/lite/v1/get_biz_token

参数

必选／可选参数类型参数说明
必选signString调用此API而生成的签名
必选sign_versionString签名算法版本，当前支持的值：hmac_sha1
必选idcard_nameString姓名, 当参数group为1时，idcard_name和idcard_number将被身份证OCR的结果覆盖
必选idcard_numberString身份证号，当参数group为1时，idcard_name和idcard_number将被身份证OCR的结果覆盖
必选return_urlString用户完成或取消验证后网页跳转的目标URL,必须以http或者人https开头
必选notify_urlString用户完成验证、取消验证、或验证超时后，由FaceID服务器请求客户服务器的URL，我们将会把比对结果同时完整发送至客户服务器（必须以http或者人https开头，推荐为HTTPS链接，回调方法为Post）
必选comparison_typeInt验证类型，当前只支持：1
可选groupInt验证前是否先进行身份证OCR识别，默认值为0，表示不做身份证OCR识别；1表示做身份证OCR识别
可选idcard_thresholdIntgroup=1时有效。表示身份证识别的阈值，默认值为0.8。如果ID_Photo分数大于该阈值，则继续进行人脸识别流程。如果ID_Photo值小于该阈值，则认为是非法身份证，提示用户重新拍摄
可选idcard_retry_timeIntgroup=1时有效。表示身份证识别分数小于阈值，重新拍摄的最大次数。默认值为3。
可选idcard_sideIntgroup=1时有效。表示拍摄身份证的方式是双面拍摄还是只拍人像面，默认值为0，表示双面拍摄。1表示只拍摄人像面
必选liveness_typeString活体类型，目前仅支持以下值：video_number
可选biz_noString"默认为空"。客户业务流水号，建议设置为您的业务相关的流水串号并且唯一。并会在return时原封不动的返回给您的服务器，以帮助您确认对应业务的归属。此字段不超过128字节。
可选verboseInt表示返回数据的详细程度。取值如下：0：默认值，仅返回结论；1：返回结论与摘要信息；
可选security_levelInt表示对比对结果的严格程度限制，请根据您的场景，选择安全规则，越严格，准确性要求越高，通过率也会相应下降。0:非常宽松，针对特殊用户开启; 1:宽松; 2:常规; 3:严格; 4:非常严格，针对特殊用户开启

返回值说明

字段类型说明
biz_tokenString生成的biz_token，该字段后续用于调用H5页面/小程序。
errorString当请求失败时才会返回此字符串，具体返回内容见后续错误信息章节。否则此字段不存在。
request_idString用于区分每一次请求的唯一的字符串
time_usedInt整个请求所花费的时间，单位为毫秒

请求示例

示例：KYC验证

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=1
-F idcard_name=姓名
-F idcard_number=<18位身份号>

返回结果示例：成功

{
    "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": "BAD_ARGUMENTS:return_url",
}

错误码列表

HTTP 状态代码错误信息说明
400MISSING_ARGUMENTS: <key>缺少某个必选参数。
400BAD_ARGUMENTS: <key>某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长，或者身份证号不符合规范等）。
403AUTHORIZATION_ERROR: <reason>api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。取值：AUTHENTICATION_FAIL：签名无效，鉴权失败；IP_DENIED:不允许访问的IP（预留设计）NON_ENTERPRISE_CERTIFICATION:客户未进行企业认证；BALANCE_NOT_ENOUGH:余额不足
404NOT_FOUND所调用的API不存在。
413Request Entity Too Large客户发送的请求大小超过了20MB限制。该错误的返回格式为纯文本，不是json格式。
429TOO_MANY_REQUESTS并发数超过限制。
500INTERNAL_ERROR服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务。

Lite URL

接口说明

用户server端在获取到biz_token后，按以下规则拼接url，并返回给客户H5页面/小程序。

规则

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

get_result

接口说明

GET方法，用户server端可以通过该API查询验证的结果。

接口地址

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

参数

必选/可选参数类型参数说明
必选signString调用此API而生成的签名
必选sign_versionString签名算法版本，当前支持的值：hmac_sha1
必选biz_tokenStringFaceID回调给客户的biz_token信息
可选verboseint表示返回数据的详细程度，取值如下：
0：默认值，仅返回结论；
1：返回结论与摘要信息；

返回结果：

参数类型说明
request_idstringAPI 调用的流水号
biz_nostring本次请求的用户业务流水号，在用户调用sdk时曾经传入
time_usedint整个请求所花费的时间，单位为毫秒
biz_tokenstring和输入参数一致
result_codeint表示本次验证的结果状态码, 参见错误码说明
result_messagestring开发者可通过此字段信息知晓具体的原因, 参见错误码说明
verificationjson当“verbose=1”且“result状态码为1000、2000系列”时，本字段才会返回。 本字段内容为：
"idcard": 包括confidence和thresholds两个字段
-- "confidence"： Float类型，取值［0，100］， 数字越大表示风险越小,仅在error无返回值时才会返回此结果。
-- “thresholds”：一组用于参考的置信度阈值，Object类型，包含三个字段，均为Float类型、取值［0，100］：
----“1e-3”：误识率为千分之一的置信度阈值；
----“1e-4”：误识率为万分之一的置信度阈值；
----“1e-5”：误识率为十万分之一的置信度阈值;
----“1e-6”：误识率为百万分之一的置信度阈值 ；
actionlist当该次流程结束时，如果用户发生了视频上传，这里会依次列出每一次的result_message
imagesjson返回image_best，即视频中获取的最优截图，是base64编码的图片。
idcard_resultjson当验证前有身份证OCR识别流程时，此字段才返回，表示身份证识别的结果信息，参见下面的idcard_result表格
errorstring当请求失败时才会返回此字符串，具体返回内容见后续错误信息章节。

请求示例：

data = {
    'sign': 'xxxx',
    'sign_version': 'xxxxxx',
    'biz_token': 'xxxxxxx',
    'verbose': 1
}
URL = "https://openapi.faceid.com/lite/v1/get_result"
res = requests.get(URL, data=data)

返回结果示例：成功

{
    "request_id": "1462257147,3149525e-2c24-4862-8e9f-92040595f0a4",
    "time_used": 5,
    "biz_no" : 124323,
    "biz_token": "34fb21937e47ae719f11cbc719615687",
    "result_code":1000,
    "result_message":"SUCCESS",
    "images": {
      "image_bese": "......",
    },
    "verification"{
        "source"{
            "confidence":77.6,
            "thresholds":77
        }
    }
    "action":{
        "FACE_QUALITY_TOO_LOW",
        "VIDEO_OK"
    }
    "idcard_result":
    {
        "name": "张三",
        "number": "12356",
        "gender": "男",
        "nationality": "汉"，
        "birthday": "2008-06-21",
        "address": "地址",
        "portrait": 头像的坐标位置,
        "issued_by": "xxx公安局",
        "valid_date_start": "2011-01-01",
        "valid_date_end": "2021-01-01",
        "frontside_legality": // 人像五分类概率结果, 参见idcard_result表格
        "backside_legality": 国徽面的五分类概率结果, 参见idcard_result表格
        "frontside_completeness": 0   //人像面的完整性结果,
        "backside_completeness": 0   // 国徽面的完整性结果,
        "image_frontside": 人像面照片,
        "image_backside": 国徽面照片,
        "image_portrait": 身份证人像抠图图像,
    }
}

idcard_result表格

key类型说明
namestring姓名
numberstring身份证号
genderstring性别，取值：男，女
nationalitystring民族
birthdaystring出生日期，如：2008-06-01
addressstring地址
portraitdict头像的坐标信息
issued_bystring发证机关
valid_date_startstring有效期的起始时间
valid_date_endstring有效期的结束时间
frontside_legalitydict人像面的五分类概率结果。
表示对身份证照片的五种分类的结果。它为一个结构体，包含五个key-value pair，每个key表示一种分类类型，每个value为此类型的概率值（取［0，1］区间实数，取3位有效数字，五个value总和为1）。这五个key是：
ID_Photo：正式身份证照片
Temporary_ID_Photo：临时身份证照片
Photocopy：正式身份证的复印件
Screen：手机或电脑屏幕翻拍的照片
Edited：用工具合成或者编辑过的身份证图片
ID_Photo_Threshold：表示判断为正式身份证照片的阈值，通常来说，如果ID_Photo的值不低于该阈值，可以认定为真实什么证的实拍；
backside_legalitydict国徽面的五分类概率结果。
表示对身份证照片的五种分类的结果。它为一个结构体，包含五个key-value pair，每个key表示一种分类类型，每个value为此类型的概率值（取［0，1］区间实数，取3位有效数字，五个value总和为1）。这五个key是：
ID_Photo：正式身份证照片
Temporary_ID_Photo：临时身份证照片
Photocopy：正式身份证的复印件
Screen：手机或电脑屏幕翻拍的照片
Edited：用工具合成或者编辑过的身份证图片
ID_Photo_Threshold：表示判断为正式身份证照片的阈值，通常来说，如果ID_Photo的值不低于该阈值，可以认定为真实什么证的实拍；
frontside_completenessint人像面的完整性结果,表示身份证图片的完整性，平整性；0:表示身份证部分是完整的；1:表示身份证不完整，但是内容区域全部都在图片内；2:表示身份证不完整，且部分内容在区域外
backside_completenessint国徽面的完整性结果,表示身份证图片的完整性，平整性；0:表示身份证部分是完整的；1:表示身份证不完整，但是内容区域全部都在图片内；2:表示身份证不完整，且部分内容在区域外
image_frontsidestring人像面照片(base64编码)
image_backsidestring国徽面照片(base64编码)
image_portraitstring身份证人像抠图图像(base64编码)

错误码列表

result_coderesult_message含义解释
1000SUCCESS待比对照片与参考数据照片或参考照对比均是同一个人
2000PASS_LIVING_NOT_THE_SAME通过了活体检测，但是经过验证，待比对照片与参考数据照片，或上传照片中的至少一张，不是同一个人；
3000NO_ID_CARD_NUMBER参考数据无此身份证号
3000ID_NUMBER_NAME_NOT_MATCH身份证号，姓名不匹配；
3000NO_FACE_FOUND参考数据照片中找不到人脸
3000NO_ID_PHOTO无法获取参考数据照片
3000PHOTO_FORMAT_ERROR参考数据照片格式错误
3000DATA_SOURCE_ERROR其他参考数据照片错误
3100IDCARD_PHOTO_FRONTSIDE身份证人像面照片模糊,无法识别信息
3100NO_FACE_FOUND_IDCARD身份证人像面照片模糊,找不到人脸
3100IDCARD_PHOTO_BACKSIDE身份证国徽面照片模糊，无法识别信息
3100IDCARD_PHOTO_NOTFRONTSIDE身份证照片不是人像面
3100IDCARD_PHOTO_NOTBACKSIDE身份证照片不是国徽面
3100IDCARD_FRONTSIDE_MANY_TIMES身份证人像面拍摄次数过多
3100IDCARD_BACKSIDE_MANY_TIMES身份证国徽面拍摄次数过多
3100IDCARD_PROCESS_ERROR拍摄身份证流程错误，如未拍摄人像面就拍摄了国徽面
3200FAIL_OCR_FAKE_IDCARD身份证检测不通过，可能的原因：是一张假证件
4100FAIL_LIVING_FACE_ATTACK未经过活体判断，可能的原因：是假脸攻击
4100CHANGE_FACE_ATTACK视频过程发生了换脸攻击，视频中不是同一个人。
4200NO_FACE_FOUND视频中没有检测到人脸；
4200FACE_QUALITY_TOO_LOW视频中的人脸质量太差，导致不可用；
4200INVALID_VIDEO_DURATION视频时长小不合格（2s～20s）；
4200SR_ERROR用户读数语音不符合要求；
4200NOT_SYNCHRONIZED用户读数过程唇语不符合要求；
4200NO_AUDIO无声音；
4200VIDEO_FORMAT_UNSUPPORTED视频格式无法识别；
4200LIP_VOICE_NOT_SYNC视频中语音唇语不同步；
4200VIDEO_INTERNAL_ERROR视频处理流程错误；
4200VIDEO_MANY_TIMES视频上传次数过多；
4300BIZ_TOKEN_DENIED传入的 biz_token 不符合要求；
4300USER_CANCELED活体失败，原因可能如下：用户取消了
4300VERIFICATION_FAILURE活体失败，原因可能如下：验证过程超时等原因；
4300NO_FACE_FOUND活体失败，原因可能如下：未找到人脸；
5000IP_DENIED不允许访问的IP
5000NON_ENTERPRISE_CERTIFICATION客户未进行企业认证
5000BALANCE_NOT_ENOUGH余额不足
5000ACCOUNT_DISABLED用户帐号已停用
9000LIVING_NOT_START活体验证没有开始
9000LIVING_IN_PROGRESS正在进行验证
9000LIVING_OVERTIME操作超时，由于用户在长时间没有进行操作

ERROR

HTTP 状态码错误信息说明
404API_NOT_FOUND所调用的API不存在。
403AUTHORIZATION_ERROR:api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。取值：AUTHENTICATION_FAIL：签名无效，鉴权失败；IP_DENIED：不允许访问的IP（预留设计）BALANCE_NOT_ENOUGH：余额不足；NON_ENTERPRISE_CERTIFICATION：未进行企业认证。
400BAD_ARGUMENTS:某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长）
429CONCURRENCY_LIMIT_EXCEEDED并发数超过限制
500INTERNAL_ERROR服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务
400MISSING_ARGUMENTS:缺少某个必选参数。
413Request Entity Too Large客户发送的请求大小超过了20MB限制。该错误的返回格式为纯文本，不是json格式。

接入方法

H5接入方法

开发者先在网站创建api-key，生成签名，然后通过get_biz_token接口配置参数并获得biz_token，将得到的biz_token拼接入url https://openapi.faceid.com/lite/v1/do/biz_token, 跳转到该url即可进入FaceID H5页面。

小程序接入方法

  1. 开发者可在下载中心 下载KYC验证微信小程序包，解压得到 faceid-components文件夹。
  2. 将faceid-components文件夹添加至项目文件根目录。 目录结构如下: 1
  3. 在需要引用组件的页面集成，组件有2个入参，token、bind:onFinish

小程序接入实例

例如需要在index页面添加组件:

  • 在index目录下打开index.json（如果没有，则新建同名的json文件，本实例为index.json）添加如下配置（请根据faceid-components目录的相对路径修改）：
{
    "usingComponents": {
        "faceid-verify": "../../faceid-components/components/index/index"
    }
}
  • 在index.js 中添加完成验证的回调函数, 即在index.js中Page内添加onFinish:
Page({
    ...,
    onFinish: function (event) {
        //验证完成回调,只会回传token
        //验证结果需要调用https://openapi.faceid.com/lite/v1/get_result获取
        // event 中包括token和status，status包括：“complete”，”tokenError", 建议当status为complete时调用get_result接口获取进一步信息，为tokenError时调用get_biz_token接口重新申请token
        console.log(event.detail.token)
        console.log(event.detail.status)
    }
})

<faceid-verify
    token="{{token}}"
    bind:onFinish="onFinish"
/>
  • 正式环境需要在微信公众平台配置小程序的服务器域名 将https://openapi.faceid.com 添加到服务器域名列表中，测试环境可以打开微信开发者工具内 不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书

1