checkresult

2025-08-06 06:37

概览

API URL：/api/v1/zoloz/idrecognition/checkresult
API 描述：该接口用于获取证件识别进程的运行状态和相关的验证结果，包括证件验证结果及详细信息。

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

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。	"2017839040588699"
transactionId	String	64	是	-	事务ID，由ZOLOZ ID Recognition initialize API的响应消息中返回。	"G000000005FID20200304000000000001570702"
isReturnImage	String	1	否	Y	是否在响应中返回图片数据。取值： `Y`：在响应中返回图片数据。 `N`：不在响应中返回图片数据。	"Y"
extraImageControlList	List<String>	-	否	[]	指定是否返回额外的证件图片。支持的图片类型如下： `DOC_FRONT_ANGLE`：返回从倾斜角度拍摄的证件首页图片。 `DOC_FRONT_FLASH`：返回在闪光灯照射下拍摄的证件首页图片。 `DOC_BACK_ANGLE`：返回从倾斜角度拍摄的证件背面图片。 `DOC_BACK_FLASH`：返回在闪光灯照射下拍摄的证件背面图片。 `CROPPED_FACE_FROM_DOC`：返回从采集的证件图片中裁剪出脸部区域的人脸图片。注意：是否返回额外的图片还取决于这些图片是否已被成功采集，这由initialize API中的以下参数共同决定： SDK类型 `serviceLevel` 证件所支持的页数及需要采集的`pages` productConfig中的`cropFaceImageFromDoc`	[ "DOC_FRONT_ANGLE", "DOC_FRONT_FLASH" ]

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

API请求结果，包含结果状态、结果码和结果消息。

{

"resultCode": "SUCCESS", "resultMessage": "success", "resultStatus": "S"

}

extInfo

ExtIdInfo

否

证件验证的详细信息。更多信息，请参见ExtIdInfo。

说明：当result.resultStatus的值为S时，才返回该字段。

参考返回示例

ExtIdInfo字段说明

字段名称	数据类型	必须返回	描述	示例值
recognitionResult	String	否	证件验证的结果。 `Y`：证件验证成功。 `N`：证件验证失败。说明：当证件验证完成时，才返回该字段。	"N"
certType	String	否	证件类型，当证件验证完成时才返回`certType`字段。	"00600000001"
docCategory	String	否	证件类别。 `PASSPORT`：护照 `DRIVING_LICENSE`：驾照 `ID_CARD`：身份证 `RESIDENCE_PERMIT`：居住证 `VISA`：签证 `OTHERS`：其他	"PASSPORT"
docEdition	Integer	否	身份证件的版本。 `1`~`3`：身份证件的版本，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。 `0`：无法对身份证件进行分类或证件类型错误。 `-1`：未知错误。	2
imageContent	List<String>	否	经过Base64编码的证件图片（如果有）。说明：当`isReturnImage`为空或设置为`Y`，且`recognitionResult`返回值也为`Y`时，才返回该参数。	["base64string.....", "base64string....."]
extraImages	Map<String,String>	否	在`extraImageControlList`中指定的额外需要返回的证件图片。`extraImages`由一个键值对组成：键：在`extraImageControlList`中指定的值。值：以Base64编码的图片内容。如果未找到请求的图片，该参数将返回空字符串（""）。当`cropDocImage`和`isReturnImage`均设置为`Y`时，`extraImages`中还会包含以下两个字段： `CROPPED_FRONT`：经过背景裁剪的证件正面图片。 `CROPPED_BACK`：经过背景裁剪的证件背面图片。	{ "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA=", "CROPPED_FRONT": "/9j/4AA..[omitted]..PxA=", "CROPPED_BACK": "/9j/4AA..[omitted]..PxA=" }
ocrResult	Map	否	OCR识别结果，结果中包含身份相关的信息。不同的身份证件类型识别出来的身份信息集不同，详细请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。说明：当recognitionResult的值为Y时，才返回该字段。	{ "ID_NUMBER": "12345", "COUNTRY": "xxxxx", "SEX": "M" }
ocrResultFormat	Map	否	标准化后的OCR输出结果，详见Notification on the Standardization of OCR Output Field Names。	{ "NUMBER": "12345", "GENDER": "M" }
ocrResultDetail	Map<String, OcrResultDetail>	否	OCR识别结果详情，当在initialize API中传入`mrzVisualConsistencyCheck`时才返回该字段。	参考返回示例
countryCode	List<String>	否	OCR识别出来的国家代码，仅当`docCategory`为`PASSPORT`时返回。	"CHN"
spoofResult	Map	否	证件防伪分项检测结果，包含篡改、材质和屏幕翻拍等检测结果。详细信息，请参见spoofResult。	{ "TAMPER_CHECK": "Y", "MATERIAL_CHECK": "Y", "SCREEN_RECAPTURE_CHECK": "Y", "INFORMATION_CHECK": "Y", "SECURITY_FEATURE_CHECK": "Y" }
extraSpoofResultDetails	List<ExtraSpoofResultDetail>	否	证件防伪检测结果详情，详见ExtraSpoofResultDetail。	参考返回示例
recognitionErrorCode	String	否	证件识别不通过明细。 `NO_REQUIRED_ID`：证件图片不符合指定的证件类型。 `BLUR`：证件图片模糊。 `NO_FACE_DETECTED`：未检测到证件上的人脸。 `NOT_REAL_DOC`：证件防伪检测不通过。 `EXPOSURE`：证件图片过度曝光。 `UNKNOWN`：其他错误。	"NO_REQUIRED_ID"
recognitionErrorDescription	String	否	证件识别失败的原因。	"Passport country code check failed."
uploadEnabledResult	String	否	返回最终用户是否选择了上传模式。 `Y`：已选择上传模式。 `N`：未选择上传模式。注意：即使initialize API中的`enableUpload`设置为`Y`，最终用户仍可能不会选择上传模式。	"N"
deeperResult	String	否	返回的Deeper证件检测结果，仅当`deeperMode`不为`CLOSED`时返回。返回值如下： `Y`：未检测到AIGC攻击风险。 `N`：检测到AIGC攻击风险。	"N"
deeperResultDescription	String	否	Deeper证件检测结果的详细描述，仅当`deeperMode`不为`CLOSED`且`deeperResult`为`N`时返回。	"deepfake risk, AIGC feature blacklib"

spoofResult字段说明

字段名称	数据类型	必须返回	描述	示例值
TAMPER_CHECK	String	是	身份证件是否通过了篡改检测。 `Y`：通过，即检测结果为未被篡改。 `N`：不通过，即检测结果为被篡改。	"Y"
MATERIAL_CHECK	String	是	身份证件是否通过了材质检测。 `Y`：通过。 `N`：不通过，例如检测结果为黑白材质。	"Y"
SCREEN_RECAPTURE_CHECK	String	是	身份证件是否通过了屏幕翻拍检测。 `Y`：通过。 `N`：不通过，即上传的证件被检测为从屏幕上翻拍的证件。	"Y"
SECURITY_FEATURE_CHECK	String	否	身份证件是否通过了防伪安全特征检测。 `Y`：通过。 `N`：不通过。说明：目前仅支持中国香港身份证，用来验证身份证上的一些安全特征以识别假证。	"Y"
INFORMATION_CHECK	String	否	身份证件是否通过了信息校验检测。 `Y`：通过。 `N`：不通过。说明：目前仅支持中国香港身份证，根据政府规定验证身份证上的信息，例如身份证号码。	"Y"

ExtraSpoofResultDetail类型说明

字段名称	数据类型	必须返回	描述	示例值
name	String	是	扩展证件防伪检测名称。	"landmarkCheck"
result	String	是	扩展证件防伪检测结果。 `Y`：检测通过。 `N`：检测失败。	"Y"
spoofType	String	是	扩展证件防伪检测所属的分项类别。 TAMPER_CHECK MATERIAL_CHECK SCREEN_RECAPTURE_CHECK INFORMATION_CHECK SECURITY_FEATURE_CHECK	"SECURITY_FEATURE_CHECK"
components	Array	是	扩展证件防伪检测细项的检查结果。该字段一定会被返回。如果只指定了一个细项检查，则数组将只返回一个元素。	[ { "name": "hologram", "subResult": "Y" } ]
components.name	String	是	扩展证件防伪检测细项的检查名称，详见证件防伪检测组件。	"kadPengenalan"
components.subResult	String	是	扩展证件防伪检测单个检测细项的检查结果。 `Y`：检查通过。 `N`：检查失败。	"Y"

处理结果

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

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

API通用结果码

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

API特有结果码

ID Recognition checkresult API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API调用成功。
PROCESSING	S	流程正在进行中。
INVALID_ARGUMENT	F	输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。
SYSTEM_ERROR	F	其他内部错误。有关错误详情，请查看返回的resultMessage。
UNUSABLE	F	用户被冻结策略阻塞。
LIMIT_EXCEEDED	F	超过最大次数限制。

代码示例

请求示例

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

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G000000005FID20200304000000000001570702",
    "isReturnImage": "Y",
    "extraImageControlList": [
        "DOC_FRONT_ANGLE",
        "DOC_FRONT_FLASH"
    ]
}

返回示例

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

copy
{
  "extInfo": {
    "certType":"00600000001",
    "docCategory": "PASSPORT",
    "docEdition":2,
    "imageContent": ["base64string.....", "base64string....."],
    "ocrResult": {
      "ID_NUMBER": "12345",
      "COUNTRY": "xxxxx",
      "SEX": "M"
    },
    "ocrResultFormat": {
      "NUMBER": "12345",
      "GENDER": "M"
    },
    "ocrResultDetail": {
      "MRZ_ID_NUMBER": {
        "name": "ID_NUMBER",
        "source": "MRZ",
        "value": "xxxx"
      },
      "VISUAL_ID_NUMBER": {
        "name": "ID_NUMBER",
        "source": "VISUAL",
        "value": "xxxx"
      },
      "MRZ_SEX": {
        "name": "SEX",
        "source": "MRZ",
        "value": "M"
      },
      "MRZ_COUNTRY": {
        "name": "COUNTRY",
        "source": "MRZ",
        "value": "xxxx"
      }
    },
    "countryCode": "CHN",
    "spoofResult": {
      "TAMPER_CHECK": "Y",
      "MATERIAL_CHECK": "Y",
      "SCREEN_RECAPTURE_CHECK": "Y",
      "INFORMATION_CHECK": "Y",
      "SECURITY_FEATURE_CHECK": "Y"
    },
    "extraSpoofResultDetails": [
      {
        "name": "landmarkCheck",
        "result": "Y",
        "spoofType": "SECURITY_FEATURE_CHECK",
        "components": [
          {
            "name": "kadPengenalan",
            "subResult": "Y"
          },
          {
            "name": "mykadLogo",
            "subResult": "Y"
          },
          {
            "name": "flagLogo",
            "subResult": "Y"
          },
          {
            "name": "mscLogo",
            "subResult": "Y"
          },
          {
            "name": "ghostFace",
            "subResult": "Y"
          },
          {
            "name": "hibiscusLogo",
            "subResult": "Y"
          },
          {
            "name": "coatOfArm",
            "subResult": "Y"
          },
          {
            "name": "twinTower",
            "subResult": "Y"
          }
        ]
      },
      {
        "name": "hologramCheck",
        "result": "Y",
        "spoofType": "SECURITY_FEATURE_CHECK",
        "components": [
          {
            "name": "hologram",
            "subResult": "Y"
          }
        ]
      },
      {
        "name": "pageInfoCheck",
        "result": "Y",
        "spoofType": "INFORMATION_CHECK",
        "components": [
          {
            "name": "id",
            "subResult": "Y"
          },
          {
            "name": "symbol",
            "subResult": "Y"
          },
          {
            "name": "name",
            "subResult": "Y"
          }
        ]
      },
      {
        "result": "N",
        "components": [
          {
            "subResult": "N",
            "name": "ID_NUMBER"
          }
        ],
        "spoofType": "INFORMATION_CHECK",
        "name": "commonConsistencyCheck"
      },
      {
        "result": "N",
        "components": [
          {
            "subResult": "N",
            "name": "NAME"
          },
          {
            "subResult": "Y",
            "name": "SEX"
          }
        ],
        "spoofType": "INFORMATION_CHECK",
        "name": "mrzVisualConsistencyCheck"
      }
    ], 
    "recognitionErrorCode": "NO_REQUIRED_ID",
    "recognitionErrorDescription": "Passport country code check failed.",
    "recognitionResult": "N",
    "deeperResult": "N",
    "deeperResultDescription": "deepfake risk, AIGC feature blacklib",
    "uploadEnabledResult": "N",
    "extraImages": {
      "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA=",
      "CROPPED_FRONT": "/9j/4AA..[omitted]..PxA=",
      "CROPPED_BACK": "/9j/4AA..[omitted]..PxA="
    }
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}