Financial Intelligence Engine：recognize

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

bizId

String

32B

是

-

業務ID，業務的唯一標識，用於追蹤業務。

"trans-abc-1234"

docType

String

32B

是

-

證件類型。

• 支援的C類證件，請參見RealID和ID Recognition支援的證件類型和返回的OCR結果。

• 支援的B類證件，請參見ID Recognition支援的企業類證件和返回的OCR結果。

"00000001003"

autoDocTypes

List<String>

200

否

null

證件類型列表。docType和autoDocTypes不能同時傳入，需選擇其中一個傳入。

• 如果傳入autoDocTypes，ZOLOZ將自動對上傳的證件進行分類。

  說明：

• 目前護照不支援自動分類。

• 新加坡證件00650000001和00650000002將統一歸類為00650000001。

• 如果ZOLOZ無法對上傳的證件進行分類或分類的證件類型不在autoDocTypes中，此時將返回NO_REQUIRED_ID。

支援的證件類型，請參見RealID和ID Recognition支援的證件類型和返回的OCR結果。

["08520000001","08520000002"]

frontPageImage

String

5MB

是

-

證件的正面照，支援Base64編碼的JPG格式。

"/9j/4AA..[omitted]..PxA="

backPageImage

String

5MB

否

null

證件的背面照，支援Base64編碼的JPG格式。

"/9j/4AA..[omitted]..PxA="

operationMode

String

32

否

STANDARD

為身分識別驗證配置操作模式。取值如下：

• CLOSED：所有的演算法和風控規則都未開啟。該操作模式可用於測試情境，測試進程不受演算法和風控規則的影響。

• STANDARD：推薦的標準模式。

• LOOSE：相對寬鬆的模式，可用於低風險情境。

• STRICT：相對嚴格的模式，可用於高風險情境。

"STANDARD"

sceneCode

String

64

否

null

情境碼，用於為資料分析指定不同的業務情境。

當需要區分不同業務情境中的資料表現時，建議根據業務用途為sceneCode欄位設定不同的值，例如login、riskVerify、payment、changePassword。該設定不會影響業務的正常運行。

"changePassword"

userId

String

64

否

null

商戶的使用者ID或其他可用於識別某一使用者的標識，例如手機號碼、電子郵件地址等。

建議對userId欄位的值進行預脫敏，例如進行雜湊處理。

"123456abcd"

extraImageControlList

List<String>

-

否

null

指定是否返回額外的圖片。支援的圖片類型如下：

• CROPPED_FACE_FROM_DOC：從證件圖片中裁剪出臉部地區並返回。

  說明：僅當frontPageImage中傳入的證件圖片含有人臉且裁剪成功時，才會返回額外的圖片；否則，extraImages將返回Null 字元串 ""。

[

"CROPPED_FACE_FROM_DOC"

]

productConfig

ProductConfig

-

否

null

為IDR產品提供更精細化的控制。詳細資料，請參見ProductConfig。

{

   "consistencyCheck": [

     {

       "type": "commonConsistencyCheck"

     },

     {

       "details": [

         "NAME",

         "SEX"

       ],

       "type": "mrzVisualConsistencyCheck"

     }

   ]

 }

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

pageInfoCheck

Array

-

否

null

在證件防偽檢測中進行頁面資訊檢查，詳細檢查項，請參見證件防偽檢測組件。

說明：頁面資訊檢查僅適用於中國香港身份證。

[

     {"name":"id"},

     {"name":"symbol"},

     {"name":"name"}

   ]

consistencyCheck

List<ConsistencyCheckItem>

-

否

null

是否進行一致性檢查。一致性檢查僅適用於部分證件的特定欄位，詳見ConsistencyCheckItem。

[

     {

       "type": "commonConsistencyCheck"

     },

     {

       "details": [

         "NAME",

         "SEX"

       ],

       "type": "mrzVisualConsistencyCheck"

     }

   ]

allowExpiredDocument

String

-

否

不同的證件類型有不同的預設值：

• Y：除護照（docType=00000001003）外的所有證件

• N：護照（docType=00000001003）

已到期的證件是否可以通過驗證。取值：

• Y：已到期的證件可以通過驗證。

• N：已到期的證件不能通過驗證。當檢測到證件到期時，IDR流程會失敗。

說明：

• 如果傳入除Y和N之外的值，系統將返回INVALID_ARGUMENT。

• 對於中國香港一代身份證（docType=08520000001），其到期攔截邏輯將嚴格依據香港政府身份證換領計劃執行。

"N"

cropFaceImageFromDoc

String

1

否

N

是否從採集的證件圖片中裁剪出人臉圖片。取值如下：

• Y：是

• N：否

"Y"

enableOCR

String

-

否

N

是否開啟OCR功能。取值如下：

• Y：開啟

• N：不開啟

"Y"

spoofMode

String

10

否

CLOSED

證件防偽等級。取值如下：

• CLOSED：所有的防偽演算法都未開啟。該等級可用於測試情境，測試進程不受演算法的影響。

• STANDARD：推薦的標準等級。

• LOOSE：預留等級，暫不支援使用。

• STRICT：預留等級，暫不支援使用。

"STANDARD"

deeperMode

String

10

否

CLOSED

AIGC攻擊檢測的Deeper等級，Deeper檢測功能的詳細介紹，請參見什麼是Deeper。該參數支援以下取值：

• CLOSED：Deeper的所有能力均不開啟，例如AIGC檢測演算法、終端風險檢測等。如果業務情境不需要AIGC攻擊檢測，則無需開啟。

• STANDARD：推薦的標準等級。

• LOOSE：相對寬鬆的等級，可用於低風險情境。

• STRICT：相對嚴格的等級，可用於高風險情境。

注意：需要先購買Deeper產品，才能使用該功能。

"STANDARD"

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型

OCR一致性檢查支援欄位

type

String

commonConsistencyCheck

對證件防偽檢測中的OCR欄位進行一致性檢查。

大馬卡 / 馬來西亞 / 00600000001

• 證件正面：ID_NUMBER

• 證件背面：ID_NUMBER_BACK前12位元字

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型

OCR一致性檢查支援欄位

type

String

mrzVisualConsistencyCheck

對證件防偽檢測中機讀區和視讀區的OCR欄位進行一致性檢查。

-

-

details

List<String>

請參見RealID和ID Recognition支援的證件類型和返回的OCR結果。

在詳細資料中指定OCR欄位進行一致性檢查。

• 當type設定為mrzVisualConsistencyCheck時，必須傳入details欄位，且details不可為空。

• 僅允許傳入證件類型所支援的OCR欄位。

MyVisa / 馬來西亞 / 00600000011

• NAME

• SEX

護照（含機讀區和視讀區）/ 中國大陸、中國香港、中國台灣、中國澳門、菲律賓、新加坡、馬來西亞 / 00000001006

• ID_NUMBER

• COUNTRY_CODE

• EXPIRY_DATE

• DATE_OF_BIRTH

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型 / OCR一致性檢查支援欄位 / 預設國家代碼

type

String

passportCountryCheck

檢查OCR結果中的COUNTRY_CODE與系統檢測到的國家是否一致。

-

valueRange

List<String>

應與預設國家代碼一致

OCR結果中的COUNTRY_CODE應在valueRange範圍內。

當type設定為passportCountryCheck時，必須傳入valueRange欄位，各證件支援的valueRange，詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。

以下證件的valueRange為證件所屬國家或地區對應的預設國家或地區代碼所組成的列表。

• 中國大陸護照 / 00860000888 / COUNTRY_CODE / CHN

• 中國台灣護照 / 08860000002 / COUNTRY_CODE / TWN

• 中國澳門護照 / 08530000002 / COUNTRY_CODE / CHN

• 菲律賓舊版護照 / 00630000031 / COUNTRY_CODE / PHL

• 菲律賓新版護照 / 00630000032 / COUNTRY_CODE / PHL

每一項都應符合ISO_3166-1_alpha-3標準

以下證件的valueRange為列表，且每一項都應符合ISO_3166-1_alpha-3標準。

• 國際護照（僅含機讀區） / 00000001003 / COUNTRY_CODE

• 國際護照（含機讀區和視讀區）/ 00000001006 / COUNTRY_CODE

欄位名稱

資料類型

必須返回

描述

樣本值

certType

String

否

證件類型，當證件驗證完成時才返回certType欄位。

"00600000001"

docCategory

String

否

證件類別。

• PASSPORT：護照

• DRIVING_LICENSE：駕照

• ID_CARD：身份證

• RESIDENCE_PERMIT：居住證

• VISA：簽證

• OTHERS：其他

"PASSPORT"

docEdition

Integer

否

身份證件的版本。

• 1~3：身份證件的版本，詳見Real ID和ID Recognition支援的證件類型和返回的OCR結果。

• 0：無法對身份證件進行分類或證件類型錯誤。

• -1：未知錯誤。

1

result

Result

是

API請求結果，包含結果狀態、結果碼和結果訊息。

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

transactionId

String

否

事務ID。

說明：僅當交易進入處理階段後系統才會返回transactionId。如果在開始處理交易之前發生錯誤，系統不會返回transactionId。包括但不限於以下情況：

• 請求參數非法，例如入參格式錯誤或缺失必傳參數。

• 請求未能成功到達伺服器，例如網路問題或網關故障。

• 系統限流導致請求被拒絕。

"G000000005FID20200304000000000001570702"

recognitionResult

String

否

證件識別總結果。

• Y：證件識別成功。

• N：證件識別失敗。

"N"

recognitionErrorCode

String

否

證件識別不通過明細。

• NO_REQUIRED_ID：證件圖片不符合指定的證件類型。

• BLUR：證件圖片模糊。

• NO_FACE_DETECTED：未檢測到證件上的人臉。

• NOT_REAL_DOC：證件防偽檢測不通過。

• EXPOSURE：證件圖片過度曝光。

• UNKNOWN：其他錯誤。

"NO_REQUIRED_ID"

recognitionErrorDescription

String

否

證件識別失敗的原因。

"Passport country code check failed."

ocrResult

Map

否

OCR識別結果。詳細資料，請參見Real ID和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" }

deeperResult

String

否

返回的Deeper證件檢測結果，僅當deeperMode不為CLOSED時返回。傳回值如下：

• Y：未檢測到AIGC攻擊風險。

• N：檢測到AIGC攻擊風險。

"N"

deeperResultDescription

String

否

Deeper證件檢測結果的詳細描述，僅當deeperMode不為CLOSED且deeperResult為N時返回。

"deepfake risk, AIGC feature blacklib"

extraImages

Map<String,String>

否

在extraImageControlList中指定的額外需要返回的圖片。

• Key是在extraImageControlList中指定的值。

• Value是以Base64編碼的圖片內容。如果未找到請求的圖片，則該值為“”。

{

"CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA="

}

欄位名稱

資料類型

必須返回

描述

樣本值

resultCode

String

是

結果碼。

• SUCCESS：成功。

• SYSTEM_ERROR：其他內部錯誤。

• INVALID_ARGUMENT：輸入參數無效。

"SUCCESS"

resultStatus

String

是

結果狀態。

• S：成功

• F：失敗

"S"

resultMessage

String

是

結果描述。

"success"

欄位名稱

資料類型

必須返回

描述

樣本值

TAMPER_CHECK

String

是

身份證件是否通過了篡改檢測。

• Y：通過，即檢測結果為未被篡改。

• N：不通過，即檢測結果為被篡改。

"Y"

MATERIAL_CHECK

String

是

身份證件是否通過了材質檢測。

• Y：通過。

• N：不通過，例如檢測結果為黑白材質。

"Y"

SCREEN_RECAPTURE_CHECK

String

是

身份證件是否通過了螢幕翻拍檢測。

• Y：通過。

• N：不通過，即上傳的證件被檢測為從螢幕上翻拍的證件。

"Y"