asynccheckresult

2025-04-18 03:20

概览

API URL：/api/v1/zoloz/idrecognition/asynccheckresult
API 描述：该接口用于异步获取证件验证结果，调用时需传入asyncrecognize API返回的事务ID。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

transactionId

String

64B

是

asyncrecognize API返回的事务ID。

"G000000005FID2020030400000000000157****"

extraImageControlList

List<String>

否

null

指定是否返回额外的图片。支持的图片类型如下：

CROPPED_FACE_FROM_DOC：从证件图片中裁剪出脸部区域并返回。
说明：仅当frontPageImage中传入的证件图片含有人脸且裁剪成功时，才会返回额外的图片；否则extraImages将返回空字符串 ""。

[

"CROPPED_FACE_FROM_DOC"

]

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "Success" }
transactionId	String	是	事务ID。	"G000000005FID2020030400000000000157****"
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`：未知错误。	1
recognitionResult	String	否	证件识别总结果。 `Y`：证件识别成功。 `N`：证件识别失败。	"Y"
recognitionErrorCode	String	否	证件识别不通过明细。 `NO_REQUIRED_ID`：证件图片不符合指定的证件类型。 `BLUR`：证件图片模糊。 `NO_FACE_DETECTED`：未检测到证件上的人脸。 `NOT_REAL_DOC`：证件防伪检测不通过。 `EXPOSURE`：证件图片过度曝光。 `UNKNOWN`：其他错误。	"BLUR"
recognitionErrorDescription	String	否	证件识别失败的原因。	"passport country code check failed."
ocrResult	Map	否	OCR识别结果，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。	{ "ID_NUMBER": "xxxx", "COUNTRY": "xxxxx", "SEX": "M", "LAST_NAME": "xxxxx", "DATE_OF_BIRTH": "xxxxx", "FIRST_NAME": "xxxxx" }
ocrResultFormat	Map	否	标准化后的OCR输出结果，详见Notification on the Standardization of OCR Output Field Names。	{ "NUMBER": "12345", "GENDER": "M" }
ocrResultDetail	Map<String, OcrResultDetail>	否	OCR识别结果详情，当在API请求中传入`mrzVisualConsistencyCheck`时才返回该字段。	参考返回示例
countryCode	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" }
extraImages	Map<String,String>	否	在`extraImageControlList`中指定的额外需要返回的图片。 Key是在`extraImageControlList`中指定的值。 Value是以Base64编码的图片内容。如果未找到请求的图片，则该值为“”。	{ "CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA=" }

Result字段说明

字段名称	数据类型	必须返回	描述	示例值
resultCode	String	是	结果码。 INVALID_ARGUMENT：`transactionId`为null或空字符串。 PROCESSING：正在处理中。 SUCCESS：成功。 SYSTEM_ERROR：其他内部错误。	"SUCCESS"
resultStatus	String	是	结果状态。	"S"
resultMessage	String	是	结果信息。	"Success"

spoofResult字段说明

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

代码示例

请求示例

copy
POST /api/v1/zoloz/idrecognition/asynccheckresult HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2024-01-04T12:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxx

{
  "transactionId": "G000000005FID2020030400000000000157****",
  "extraImageControlList":[
      "CROPPED_FACE_FROM_DOC"
  ]
}

返回示例

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15-0800
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx

{
  "transactionId": "G000000005FID2020030400000000000157****",
  "certType": "00600000001",
  "docCategory": "PASSPORT",
  "docEdition": 1,
  "ocrResult": {
    "COUNTRY_CODE_IN_ISO": "Y",
    "LOCAL_NAME": "xxxx",
    "ID_NUMBER": "xxxx",
    "MAC_ID": "",
    "COUNTRY": "xxxx",
    "SEX": "M",
    "LAST_NAME": "xxxx",
    "HK_ID": "",
    "DATE_OF_BIRTH": "xxxx",
    "FIRST_NAME": "xxxx",
    "EXPIRY_DATE": "xxxx",
    "COUNTRY_CODE": "xxxx"
  },
  "ocrResultFormat": {
    "NUMBER": "12345",
    "GENDER": "M"
  },
  "ocrResultDetail": {
    "MRZ_MAC_ID": {
      "name": "MAC_ID",
      "source": "MRZ",
      "value": ""
    },
    "MRZ_COUNTRY_CODE_IN_ISO": {
      "name": "COUNTRY_CODE_IN_ISO",
      "source": "MRZ",
      "value": "Y"
    },
    "MRZ_ID_NUMBER": {
      "name": "ID_NUMBER",
      "source": "MRZ",
      "value": "xxxx"
    },
    "VISUAL_ID_NUMBER": {
      "name": "ID_NUMBER",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_DATE_OF_BIRTH": {
      "name": "DATE_OF_BIRTH",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_COUNTRY_CODE": {
      "name": "COUNTRY_CODE",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_EXPIRY_DATE": {
      "name": "EXPIRY_DATE",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_FIRST_NAME": {
      "name": "FIRST_NAME",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_HK_ID": {
      "name": "HK_ID",
      "source": "MRZ",
      "value": ""
    },
    "MRZ_SEX": {
      "name": "SEX",
      "source": "MRZ",
      "value": "M"
    },
    "VISUAL_LOCAL_NAME": {
      "name": "LOCAL_NAME",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "VISUAL_EXPIRY_DATE": {
      "name": "EXPIRY_DATE",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_LAST_NAME": {
      "name": "LAST_NAME",
      "source": "MRZ",
      "value": "xxxx"
    },
    "VISUAL_COUNTRY_CODE": {
      "name": "COUNTRY_CODE",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_COUNTRY": {
      "name": "COUNTRY",
      "source": "MRZ",
      "value": "xxxx"
    }
  },
  "countryCode": "CHN",
  "recognitionResult": "Y",
  "recognitionErrorCode": "BLUR",
  "recognitionErrorDescription": "passport country code check failed.",
  "spoofResult": {
    "TAMPER_CHECK": "Y",
    "SECURITY_FEATURE_CHECK": "Y",
    "MATERIAL_CHECK": "Y",
    "INFORMATION_CHECK": "Y",
    "SCREEN_RECAPTURE_CHECK": "Y"
  },
  "extraImages": {
      "CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA="
  },
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
  }
}