checkresult

2024-11-05 07:22

概览

API URL：/api/v1/zoloz/connect/checkresult
API 描述：该接口用于获取人脸验证的结果。

说明：该接口支持重复调用，即符合幂等性。

请求参数

字段名称

数据类型

最大长度

是否必填

描述

示例值

bizId

String

是

业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。

说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。

"2017839040588699"

transactionId

String

是

事务ID，由ZOLOZ Connect initialize API在初始化人脸验证进程时的响应消息中返回。

"G006600016CN20190114000000009572520355"

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }
connectResult	String	是	人脸验证总结果，将以`Success`、`Failure`、`VoidTimeout`、`InProcess`的形式返回。 `Success`：人脸质量总结果和活体检测结果均通过。如果已购买并启用了Deeper功能，则表示人脸质量总结果、活体检测结果和Deeper检测结果均通过。 `Failure`：本次认证存在较高风险，建议拒绝。人脸质量总结果或人脸活体检测不通过。 `VoidTimeout`：未获得人脸验证结果，人脸验证超时。 `InProcess`：未获得人脸验证结果，正在验证中。	"Success"
extFaceInfo	ExtFaceInfo	否	人脸验证的详细信息，请参见ExtFaceInfo。说明：当result.resultCode的值为`SUCCESS`或`NOT_SAME_PERSON`时，才返回该字段。	{ "aliveImage": "#ALIVE_FACE_BASE64_CONTENT#", "refImage": "#REFERENCE_FACE_BASE64_CONTENT#", "faceScore": 89.1, "faceAttack": false, "deeperResult":"Success", "deeperResultDescription":"" }

ExtFaceInfo字段说明

说明：当人脸采集完成时，才返回aliveImage、refImage和faceScore字段。

字段名称	数据类型	必须返回	描述	示例值
aliveImage	String	否	采用Base64编码的人脸图片。	"#ALIVE_FACE_BASE64_CONTENT#"
refImage	String	否	采用Base64编码的人脸注册图片。	"#REFERENCE_FACE_BASE64_CONTENT#"
faceScore	Double	否	人脸比对分数，取值范围0-100。该分数是将活体人脸与注册人脸进行比对得出的结果。	89.1
faceAttack	Boolean	否	通过人脸活体检测算法检测当前的人脸图片是否为假脸攻击。 `false`：非假脸攻击。 `true`：假脸攻击。	false
deeperResult	String	否	返回的Deeper结果。当`deeperMode`不设置为`CLOSED`时才返回该参数，具体返回的参数值如下： `Success`：Deeper检测通过，未检测到AIGC攻击风险。 `Failure`：Deeper检测失败，检测到有AIGC攻击风险。	"Success"
deeperResultDescription	String	否	Deeper检测结果的详细描述，当`deeperMode`不设置为`CLOSED`，且`deeperResult`为`Failure`时才返回该参数。	""

处理结果

根据请求结果执行下一步的响应动作，具体如下：

当result.resultCode的值为SUCCESS或NOT_SAME_PERSON时，表示调用ZOLOZ Connect checkresult API成功，并返回人脸验证结果SUCCESS或NOT_SAME_PERSON。
当result.resultCode的值非SUCCESS或NOT_SAME_PERSON时，表示调用ZOLOZ Connect checkresult API失败。请检查错误码获取有关该错误的更多信息，并分析导致该错误的原因。

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

Connect checkresult API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API调用成功。
INVALID_ARGUMENT	F	输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。
SYSTEM_ERROR	F	其他内部错误。有关错误详情，请查看返回的resultMessage。
NOT_SAME_PERSON	F	人脸验证失败。可能原因如下：人脸比对分数低于阈值。检测到欺诈或高风险行为。 Deeper检测不通过。
UNABLE_GET_IMAGE	F	注册的图片不可用或无效。
PROCESSING	F	正在进行人脸验证。

代码示例

请求示例

商户服务端发送的请求代码示例。

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G006600016CN20190114000000009572520355"
}

返回示例

ZOLOZ服务器返回的响应代码示例。

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "connectResult": "Success",
  "extFaceInfo": {
    "aliveImage": "#ALIVE_FACE_BASE64_CONTENT#",
    "refImage": "#REFERENCE_FACE_BASE64_CONTENT#",
    "faceScore": 89.1,
    "faceAttack": false,
    "deeperResult":"Success",
    "deeperResultDescription":""
  }
}