欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

bizId

String

32B

是

-

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

"trans-abc-1234"

docType

String

32B

否

null

指定上傳證件的類型。

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

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

注意：

• docType與autoDocTypes、autoDocCategory、autoDocCountryCode互斥，不可同時使用。

• docType、autoDocTypes、autoDocCategory、autoDocCountryCode可以分別單獨使用。

"00000001003"

autoDocTypes

List<String>

200

否

null

指定證件類型列表，由系統對上傳證件進行自動分類。該參數可單獨使用或與autoDocCountrycode組合使用。

• 銀行卡和港澳入境小票不支援自動分類。

• 如果系統無法分類或分類結果不在傳入的autoDocTypes中，則將返回NO_REQUIRED_ID。

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

["08520000001","08520000002"]

autoDocCategory

List<String>

-

否

null

指定證件類別，由系統對上傳證件進行自動分類。該參數可單獨使用或與autoDocCountrycode組合使用。

• 支援的證件類別如下：

• PASSPORT：護照

• DRIVING_LICENSE：駕照

• ID_CARD：身份證

• RESIDENCE_PERMIT：居住證

• VISA：簽證

• ALL：所有證件

• 如果系統無法分類或分類結果不在傳入的autoDocCategory中，則將返回NO_REQUIRED_ID。

注意：當傳入autoDocCategory時，系統可能識別出新的證件類型和類別，此時返回的certType和docCategory可能歸入新的證件類別。這是由於ZOLOZ正在不斷擴充全球證件的覆蓋範圍，以支援更多證件類型。

舉例：當autoDocCategory設定為ALL時，系統會根據上傳證件自動分類，分類完成後，certType可能返回一種新的證件類型（例如00000001001），並歸類為NEW_CATEGORY。

為確保您的系統平穩適配新的證件類型，建議提前做好相容性整合措施，例如避免對返回的certType和docCategory進行強校正。

"ID_CARD"

autoDocCountrycode

List<String>

300

否

null

指定證件所屬國家或地區。支援傳ALL或符合ISO 3166-1 alpha-3標準的三位國家碼。

支援以下使用方式：

• autoDocCountrycode單獨使用：表示傳入的證件類型屬於某個國家。

• autoDocCountrycode+autoDocCategory：取兩個參數的交集，表示傳入的證件類型屬於某國家某類別的證件。
  舉例：autoDocCategory=ID_CARD和DRIVING_LICENSE，autoDocCountrycode=PHL，表示只允許菲律賓的身份證和駕照通過，否則提示證件類型錯誤。
  

• autoDocCountrycode+autoDocTypes：取兩個參數的交集，表示傳入的證件類型列表屬於某個國家。
  注意：
  

• autoDocTypes必須包含通用護照（00000001003或00000001006）才能組合使用，否則系統將攔截該請求。

• autoDocCountrycode必須涵蓋傳入的autoDocTypes列表中的國家範圍，否則系統將攔截該請求。

舉例：

• autoDocTypes=通用護照（00000001003或00000001006）和菲律賓駕照（00630000004），autoDocCountrycode=AUS，系統將攔截該請求。

  • autoDocTypes=通用護照（00000001003或00000001006）和澳大利亞永久居民身份證（00610000009），autoDocCountrycode=AUS，表示只允許澳大利亞的護照和永久居民身份證通過，否則系統將提示證件類型錯誤。

注意：

• 如果系統無法分類或分類的證件國家不在autoDocCountrycode中，則將返回NO_REQUIRED_ID。

• 當傳入autoDocCountrycode時，系統可能識別出新的證件國家，此時返回的certCountry和certCountryCode可能歸入新的證件國家。這是由於ZOLOZ正在不斷擴充全球證件的覆蓋範圍，以支援更多證件類型。
  為確保您的系統平穩適配新的證件國家，建議提前做好相容性整合措施，例如避免對返回的certType、docCategory、certCountry和certCountryCode進行強校正。
  

[

"CHN",

"PHL"

]

frontPageImage

String

5MB

是

-

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

注意：frontPageImage和backPageImage兩張圖片的總大小不能超過5MB，如果圖片過大，建議壓縮後再上傳，以免造成系統錯誤。

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

backPageImage

String

5MB

否

null

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

注意：frontPageImage和backPageImage兩張圖片的總大小不能超過5MB，如果圖片過大，建議壓縮後再上傳，以免造成系統錯誤。

"/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結果。

在details中指定OCR欄位進行一致性檢查。

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

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

MyVisa / 馬來西亞 / 00600000011

• NAME

• SEX

護照（含機讀區和視讀區）/ 所有國家或地區 / 00000001006

• ID_NUMBER

• COUNTRY_CODE

• EXPIRY_DATE

• DATE_OF_BIRTH

往來港澳通行證 / 中國大陸 / 00860000011

• ID_NUMBER

• DATE_OF_EXPIRY

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型 / 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：簽證

"PASSPORT"

docEdition

Integer

否

身份證件的版本。

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

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

• -1：未知錯誤。

1

certCountry

String

否

簽發國家。

"Singapore"

certCountryCode

String

否

簽發國家碼。

"SGP"

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

}

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"

INFORMATION_CHECK

String

否

身份證件是否通過了資訊校正檢測。

• Y：通過。

• N：不通過。

說明：目前僅支援中國香港身份證，根據政府規定驗證身份證上的資訊，例如社會安全號碼碼。

"Y"

SECURITY_FEATURE_CHECK

String

否

身份證件是否通過了防偽安全特徵檢測。

• Y：通過。

• N：不通過。

說明：目前僅支援中國香港身份證，用來驗證身份證上的一些安全特徵以識別假證。

"Y"