checkresult v1a

2024-11-05 07:22

概览

API URL：/api/v1a/zoloz/facecapture/checkresult
API 描述：该接口用于获取人脸采集的结果。

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

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。	"2017839040588699"
transactionId	String	64	是	-	事务ID，由ZOLOZ Face Capture initialize API在初始化人脸采集时的响应消息中返回。	"G006600016CN20190114000000009572520355"
isReturnImage	String	1	否	N	是否在响应中返回图片数据。取值如下： `Y`：在响应中返回图片数据。 `N`：不在响应中返回图片数据。	"Y"
extraImageControlList	List<String>	-	否	[]	指定需要返回的额外的图片。支持的图片类型如下： `FACE_EYE_CLOSE`：返回闭眼的人脸图片。 `CROPPED_FACE`：返回裁剪后的人脸图片。说明：当isReturnImage为Y时，该参数才生效。 `FACE_EYE_CLOSE`仅在特定serviceLevel（例如`FACECAPTURE0010`）下生效，请参见initialize API。 `CROPPED_FACE`仅在initialize API中指定cropFaceImage参数为`Y`时生效，请参见initialize API。	["FACE_EYE_CLOSE"]

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }
extInfo	ExtInfo	否	人脸采集的详细信息。详细信息，请参见ExtInfo。说明：当result.resultCode的值为`SUCCESS`时，才返回该字段。	{ "imageContent": "base64string.....", "faceAttack": false, "rect": { "top": 233, "left": 165, "bottom": 479, "right": 410 }, "quality": "99.41563014552693" }
faceCaptureResult	String	是	人脸采集总结果。人脸采集总结果将以Success、Failure、VoidTimeout、InProcess的形式返回。 `Success`：人脸质量总结果及活体检测均通过。 `Failure`：本次认证存在较高风险，建议拒绝。人脸质量总结果或人脸活体检测不通过。 `VoidTimeout`：未获得人脸采集结果，人脸采集超时。 `InProcess`：未获得人脸采集结果，正在采集中。	"Success"

ExtInfo字段说明

字段名称	数据类型	必须返回	描述	示例值
imageContent	String	否	采集到的人脸图片，采用Base64编码格式。	"base64string....."
faceAttack	Boolean	否	通过人脸活体检测算法检测当前的人脸采集图片是否属于假脸攻击。 `true`：假脸攻击。 `false`：非假脸攻击。说明：当qualityPassed的值为false时，该字段的返回值为null。	false
rect	Map	否	人脸图片的坐标数据。	{"top": 233, "left": 165, "bottom": 479, "right": 410}
quality	String	否	图片质量分，取值范围0-100。	"99.41563014552693"
qualityPassed	Boolean	是	人脸质量总结果。人脸质量总结果将以true和false的形式返回。人脸质量检测支持检测多个模块，包含人脸质量分、口罩检测、遮挡检测，默认检测人脸质量分（人脸是否清晰、完整等），可根据您的实际业务需求开启更多检测项。 `true`：人脸质量分和其他检测模块均通过。当未定义其他模块时，默认检测人脸质量分。 `false`：质量检测不通过。人脸质量分或其他检测模块存在不通过项。	true
extraImages	Map<String,String>	否	在extraImageControlList中指定的额外需要返回的人脸图片。 Key是在extraImageControlList中指定的值。 Value是以Base64编码的图片内容。如果未找到请求的图片，则该值为“”。	{ "FACE_EYE_CLOSE": "base64string....." }
deviceRisk	DeviceRisk	否	返回的设备风险信息。当您购买了Deeper产品，且initialize API中的`CheckDeviceRisk`为`Y`或`deeperMode`不为`CLOSED`时，才返回该字段，详见DeviceRisk。	{ "riskLevel": 0 }
deeperResult	String	否	返回的Deeper结果。当`deeperMode`不设置为`CLOSED`时才返回该参数，具体返回的参数值如下： `Success`：Deeper检测通过，未检测到AIGC攻击风险。 `Failure`：Deeper检测失败，检测到有AIGC攻击风险。	"Success"
deeperResultDescription	String	否	Deeper检测结果的详细描述，当`deeperMode`不设置为`CLOSED`，且`deeperResult`为`Failure`时才返回该参数。	""

DeviceRisk类型说明

字段名称

数据类型

必须返回

描述

示例值

riskLevel

Integer

否

风险等级及对应的处理建议如下：

-1：无法识别人脸注入风险。建议您基于其他情况进行进一步判断。
说明：新加坡站点暂不支持该能力，riskLevel将返回-1。
0：无风险，未检测到人脸注入风险。建议继续进行。
1：低风险。建议标记和观察。
2：中风险。建议添加安全检查方法，例如短信验证等。
3：高风险，建议直接拦截。

处理结果

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

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

API通用结果码

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

API特有结果码

Face Capture checkresult API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API调用成功。
PROCESSING	S	正在采集人脸图片。
INVALID_ARGUMENT	F	输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。
UNUSABLE	F	ZOLOZ SDK返回的元信息未通过可用性检查，用户无法使用人脸采集功能。
SYSTEM_ERROR	F	其他内部错误。有关错误详情，请查看返回的resultMessage。
LIMIT_EXCEEDED	F	超过最大次数限制。

代码示例

请求示例

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

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G006600016CN20190114000000009572520355",
    "isReturnImage": "Y",
    "extraImageControlList": ["FACE_EYE_CLOSE"]
}

返回示例

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

copy
{
  "faceCaptureResult":"Success",
  "extInfo": {
    "imageContent": "base64string.....",
    "faceAttack": false,
    "deeperResult":"Success",
    "deeperResultDescription":"",
    "deviceRisk":{
      "riskLevel": 0
    },
    "rect": {
      "top": 233,
      "left": 165,
      "bottom": 479,
      "right": 410
    },
    "quality": "99.41563014552693",
    "qualityPassed": true,
    "extraImages": { "FACE_EYE_CLOSE": "base64string....." }
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}