SDK-查询接口

get_result

接口说明

供 FaceID KYC验证 SDK 查询比对的结果。

接口地址

GET  https://openapi.faceid.com/face/v1.2/sdk/get_result

参数

参数名必选/可选类型参数说明
sign必选String调用此API而生成的签名 ； 生成签名本身可能存在特殊字符，需要对此参数进行 urlencode
sign_version必选String签名算法版本号，目前仅支持："hmac_sha1"
biz_token必选Stringget_biz_token接口获得的biz_token
verbose可选int表示返回数据的详细程度，取值如下：
0：仅返回结论；
1：默认值，返回结论与摘要信息

Python 请求示例

import requests
data = {
    "sign": "XXXXX",
    "sign_version": "hmac_sha1",
    "biz_token": "XXXXX",
    "verbose": 1,
    }
url = "https://openapi.faceid.com/face/v1.2/sdk/get_result"
res = requests.get(url=url, data=data)
print(res.json())

返回值

参数类型说明
request_idString用于区分每一次请求的唯一的字符串。此字符串可以用于后续数据反查。此字段必定返回。
biz_noStringget_biz_token 接口传入的业务流水号
time_usedInt整个请求所花费的时间，单位为毫秒。此字段必定返回。
biz_tokenString通过get_biz_token获取的唯一串码
result_codeInt表示本次验证的结果状态码，参见下面详述
result_messageString开发者可通过此字段信息知晓具体的原因，参见下面详述
verificationJson人脸比对的详细结果，可能的字段如下：
- idcard: Json类型, 表示活体照片和参考数据比对的结果，具体包括以下字段：
-- confidence: 比对结果的置信度，Float类型，取值［0，100］，数字越大表示风险越小。
-- thresholds: 一组用于参考的置信度阈值，Json类型，包含三个字段，均为Float类型、取值［0，100］:
--- 1e-3: 误识率为千分之一的置信度阈值;
--- 1e-4: 误识率为万分之一的置信度阈值;
--- 1e-5: 误识率为十万分之一的置信度阈值;
--- 1e-6: 误识率为百万分之一的置信度阈值;
- ref1: Json类型，表示活体照片和image_ref1的比对结果，字段和上面的相同。
- ref2: Json类型，表示活体照片和image_ref2的比对结果，字段和上面的相同。
imagesJson活体照片, 字段如下：
image_best: 活体检测获得的最优照片，base64编码。该照片会和参考数据照片或者用户上传的上传照片进行比对。
errorStringHTTP status code非200时返回，参见下面详述(HTTP状态码和对应的ERROR字段说明)

返回结果示例：成功(comparison_type=1，并且传入的image_ref1)

{
    "biz_token": "1532485677,fb241f74-e4e0-4396-ad74-eb8c1764aa1b",
    "images": {
        "image_best": "XXXX"   # base64编码的活体照片
    },
    "verification": {
        "idcard": {
            "confidence": 83.23666,
            "thresholds": {
                "1e-3": 62.168713,
                "1e-5": 74.39926,
                "1e-4": 69.31534,
                "1e-6": 78.038055
            }
        },
        "ref1": {
            "confidence": 82.93322,
            "thresholds": {
                "1e-3": 62.168713,
                "1e-5": 74.39926,
                "1e-4": 69.31534,
                "1e-6": 78.038055
            }
        }
    },
    "request_id": "1532487162,7fb9b4af-4c6e-47a0-bb53-9de273368bc9",
    "time_used": 108,
    "biz_no": "1234567890",
    "result_message": "SUCCESS",
    "result_code": 1000
}

返回结果示例：成功(comparison_type=0，并且传入的image_ref1,image_ref2)

{
    "biz_token": "1533092645,4bb3469c-6d3e-428f-82ef-bca002495420",
    "images": {
        "image_best": "XXXX"   # base64编码的活体照片
    },
    "verification": {
        "ref1": {
            "confidence": 83.23666,
            "thresholds": {
                "1e-3": 62.168713,
                "1e-5": 74.39926,
                "1e-4": 69.31534,
                "1e-6": 78.038055
            }
        },
        "ref2": {
            "confidence": 82.93322,
            "thresholds": {
                "1e-3": 62.168713,
                "1e-5": 74.39926,
                "1e-4": 69.31534,
                "1e-6": 78.038055
            }
        }
    },
    "request_id": "1532488142,7fb9b5af-7c6e-47b0-cb51-9de273368bc9",
    "time_used": 108,
    "biz_no": "1234567890",
    "result_message": "SUCCESS",
    "result_code": 1000
}

返回结果示例：失败

{
    "error": "MISSING_ARGUMENTS:sign",
    "request_id": "1532412061,8e001d6b-8396-401a-86a1-108d13c66c80",
    "time_used": 196
}

错误码说明：

Result_code&result_message说明

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其他参考数据照片错误
4100FAIL_LIVING_FACE_ATTACK未经过活体判断，可能的原因：是假脸攻击
4100REPLACED_FACE_ATTACK发生换脸攻击，在做活体过程中出现两张不相同的人脸
4200BIZ_TOKEN_DENIED传入的 biz_token 不符合要求
4200AUTHENTICATION_FAIL鉴权失败
4200MOBILE_PHONE_NOT_SUPPORT手机在不支持列表里
4200SDK_TOO_OLDSDK版本过旧，已经不被支持
4200MOBILE_PHONE_NO_AUTHORITY没有权限（运动传感器、存储、相机）
4200USER_CANCELLATION用户活体失败，可能原因：用户取消了
4200USER_TIMEOUT用户活体失败，可能原因：验证过程超时
4200VERIFICATION_FAILURE用户活体失败，可能原因：验证失败
4200UNDETECTED_FACE用户活体失败，可能原因：未检测到人脸
4200ACTION_ERROR用户活体失败，可能原因：用户动作错误；
5000API_KEY_BE_DISCONTINUEDapi_key被停用
5000IP_NOT_ALLOWED不允许访问的IP
5000NON_ENTERPRISE_CERTIFICATION客户未进行企业认证
5000BALANCE_NOT_ENOUGH余额不足
5000MORE_RETRY_TIMES获取服务器配置时超过重试次数
5000ACCOUNT_DISCONTINUED用户帐号已停用
5000EXPIRED_SIGN签名过期
5000INVALID_SIGN无效的签名
5000REPLAY_ATTACK重放攻击，单次有效的签名被多次使用
6000USER_CANCEL用户取消
6000NO_CAMERA_PERMISSION没有打开相机的权限，请开启权限后重试
6000ILLEGAL_PARAMETER传入参数不合法
6000DEVICE_NOT_SUPPORT无法启动相机，请确认摄像头功能完好
6000INVALID_BUNDLE_ID信息验证失败，请重启程序或设备后重试
6000NETWORK_ERROR连不上互联网，请连接上互联网后重试
6000FACE_INIT_FAIL无法启动人脸识别，请稍后重试
6000LIVENESS_DETECT_FAILED活体检测不通过
6000NO_SENSOR_PERMISSION无法读取运动数据的权限，请开启权限后重试
6000INIT_FAILED初始化失败
9000LIVING_NOT_START活体验证没有开始
9000LIVING_IN_PROGRESS正在进行验证
9000LIVING_OVERTIME操作超时，由于用户在长时间没有进行操作

HTTP状态码和对应的ERROR字段说明

HTTP状态码ERROR字段说明
403INVALID_SIGN无效签名
403AUTHENTICATION_ERRORapi_key 和 api_secret 不匹配。
403AUTHORIZATION_ERROR:<reason>api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。
reason>取值：
API_KEY_BE_DISCONTINUED:api_key被停用
IP_NOT_ALLOWED：不允许访问的IP（预留设计）
其他可能的错误码，请预留处理方案。
429TOO_MANY_REQUESTS并发数超过限制
400MISSING_ARGUMENTS:<key>缺少某个必选参数。
400BAD_ARGUMENTS:<key>某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长）
400BIZ_TOKEN_USEDbiz_token 已使用
400MEGLIVE_DATA_ERROR内部数据包错误。如果持续出现此类错误，请及时联系 FaceID 客服或商务。
404API_NOT_FOUND所调用的API不存在。
413Request Entity Too Large客户发送的请求大小超过了20MB限制。该错误的返回格式为纯文本，不是json格式。
500INTERNAL_ERROR服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务

当前版本

  • v1.2.0

历史版本