概覽

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中設定的`serviceLevel`的值決定。	[ "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"
docEdition	Integer	否	身份證件的版本。 `1`~`3`：身份證件的版本，詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。 `0`：無法對身份證件進行分類或證件類型錯誤。 `-1`：未知錯誤。	2
imageContent	List<String>	否	經過Base64編碼的身份證件圖片（如果有）。說明：當recognitionResult的值為Y時，才返回該欄位。	["base64string.....", "base64string....."]
extraImages	Map<String,String>	否	在`extraImageControlList`中指定的額外需要返回的證件圖片。 Key是在`extraImageControlList`中指定的值。 Value是以Base64編碼的圖片內容。如果未找到請求的圖片，則該值為“”。	{ "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA=" }
ocrResult	Map	否	OCR識別結果，結果中包含身份相關的資訊。不同的身份證件類型識別出來的身份資訊集不同，詳細請參見Real ID和ID Recognition支援的證件類型和返回的OCR結果。說明：當recognitionResult的值為Y時，才返回該欄位。	{ "ID_NUMBER": "xxxx", "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" }
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`：非案頭上傳檔案的方式擷取。	"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"

處理結果

根據請求結果執行下一步的響應動作，具體如下：

當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	超過最大次數限制。

程式碼範例

請求樣本

商戶服務端發送的請求程式碼範例。

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

返回樣本

ZOLOZ伺服器返回的響應程式碼範例。

{
  "extInfo": {
    "certType":"00600000001",
    "docEdition":2,
    "imageContent": ["base64string.....", "base64string....."],
    "ocrResult": {
      "ID_NUMBER": "xxxx",
      "COUNTRY": "xxxxx",
      "SEX": "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"
      }
    },
    "spoofResult": {
      "TAMPER_CHECK": "Y",
      "MATERIAL_CHECK": "Y",
      "SCREEN_RECAPTURE_CHECK": "Y"
    },
    "recognitionErrorCode": "",
    "recognitionErrorDescription": "xxxxx",
    "recognitionResult": "Y",
    "extraImages": {
      "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA="
    }
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}