說明：該介面不支援重複調用，即不符合等冪性。

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

bizId

String

32

是

-

業務ID，業務的唯一標識，用於追蹤業務。例如，商戶業務相關資料庫中的序號。

說明：ZOLOZ伺服器不檢查該欄位的值是否唯一。為了更便捷地追蹤業務，建議開啟商戶伺服器，並確保業務ID的唯一性。

"2017839040588699"

metaInfo

String

512

是

-

SDK和使用者裝置的元資訊。該欄位的值由ZOLOZ SDK以JSON字串格式返回。

說明：不要修改傳回值，直接傳遞即可。如果是H5接入模式，則設定為MOB_H5。

"{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }"

userId

String

64

是

-

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

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

"123456abcd"

docType

String

16

否

null

指定上傳證件的類型。例如上傳證件為護照，docType設定為00000001003。支援的證件類型，詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。

注意：

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

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

"08520000001"

autoDocTypes

List<String>

200

否

null

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

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

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

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

["00630000032","00630000004"]

autoDocCategory

List<String>

-

否

null

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

• 支援的證件類別如下：

• PASSPORT：護照

• DRIVING_LICENSE：駕照

• ID_CARD：身份證

• RESIDENCE_PERMIT：居住證

• VISA：簽證

• ALL：所有證件

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

注意：當傳入autoDocCategory時，系統可能識別出新的證件類型和類別，此時checkresult API返回的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中，checkresult API將返回NO_REQUIRED_ID。

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

[

"CHN",

"PHL"

]

autoDocPages

Map<String, String>

-

否

證件類型的預設頁數

指定需要掃描和上傳的證件頁數，僅支援與證件自動分類參數（autoDocTypes、autoDocCategory和autoDocCountrycode）組合使用。參數格式為索引值對（Key-Value）：

• Key：傳入的證件類型。

• Value：需要掃描的證件頁數。

• 1：表示僅掃描第1頁。

• 1,2：表示掃描第1頁和第2頁。

不同證件類型的最大支援頁數與預設頁數，詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。

注意：

• 如果不傳該參數，預設值為對應證件類型的預設頁數。

• 如果需要掃描兩頁，請傳1,2。

• 當和autoDocTypes組合使用時，在autoDocTypes中必須包含autoDocPages中的所有證件類型。

{

"00630000032": "1",

"00630000004": "1,2"

}

pages

String

32

否

證件類型的預設頁數

指定需要掃描和上傳的證件頁數，僅支援與docType參數組合使用。多個頁數間用英文逗號分隔，例如：

• 1：表示僅掃描第1頁。

• 1,2：表示掃描第1頁和第2頁。

不同證件類型的最大支援頁數與預設頁數，詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。

注意：

• 如果不傳該參數，預設值為對應證件類型的預設頁數。

• 如果需要掃描兩頁，請傳1,2。

• 當傳入autoDocTypes、autoDocCategory或autoDocCountrycode時，pages必須為空白，否則系統將返回INVALID_ARGUMENT。

"1"

serviceLevel

String

32

否

IDRECOGNITION0002

該參數已不再推薦使用，建議設定productConfig中的具體參數。

服務等級。取值如下：

• IDRECOGNITION0002：基礎防偽等級。

• IDRECOGNITION0003：使用閃光互動模式的高階防偽等級。如果設定了該值，ZOLOZ SDK會自動掃描身份證件。該等級僅支援在原生SDK模式下使用。

• IDRECOGNITION0005：使用多角度互動模式的高階防偽等級。該等級僅支援在Web SDK模式下使用，且目前該等級僅支援中國香港身份證。

"IDRECOGNITION0002"

operationMode

String

32

否

STANDARD

該參數已不再推薦使用，建議設定productConfig中的具體參數。

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

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

• STANDARD：推薦的標準模式。

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

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

"STANDARD"

h5ModeConfig

H5ModeConfig

-

否

null

H5 ID Recognition的配置資訊，詳見H5ModeConfig。

說明：當metaInfo的值為MOB_H5時必須傳入該欄位。

{ "completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html", "interruptCallbackUrl":"http://xxx.html" }

productConfig

ProductConfig

-

否

null

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

參考請求樣本

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

state

String

128

否

transactionId欄位的值

用於恢複客戶內容相關的標識符。您可以為該欄位設定任意值，當ZOLOZ SDK回調商戶的移動App時會將該值作為參數傳遞。

"G000000005FID20200304000000000001570702"

completeCallbackUrl

String

128

是

-

當整個身分識別驗證完成時，為瀏覽器指定即將重新導向的回調URL。

"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html"

interruptCallbackUrl

String

128

是

-

當進程中斷時，為瀏覽器指定重新導向到的回調URL。

"http://xxx.html"

locale

String

16

否

en

網頁語言，目前支援以下語言：

• en：英語

• zh-CN：簡體中文

• zh-HK：繁體中文

• jp：日語

• th：泰語

• es：西班牙語

• pt：葡萄牙語

• fr：法語

• id：印尼語

• de：德語

• kr：韓語

• vi：越南語

"zh-CN"

isIframe

String

1

否

N

是否需要在iframe中開啟網頁，如果需要設定為Y，否則設定為N。

"Y"

uiCfg

String

256

否

null

自訂UI配置，採用JSON字串格式。目前支援以下欄位：

• titlebarbgcolor

• titlebartextcolor

• buttoncolor

• captureMode：如果希望將SDK切換到橫向採集模式，captureMode需設定為landscape。

• isDesktop：是否從PC端初始化證件採集模式。

• Y：從PC端初始化。當isDesktop為Y時，serviceLevel僅支援IDRECOGNITION0002，否則系統將返回INVALID_ARGUMENT。

• N：從移動端初始化，使用移動Web SDK採集流程。預設值為N。

"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\", \"captureMode\":\"landscape\",\"isDesktop\":\"Y\"}"

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

cropDocImage

String

1

否

N

是否額外返回一張裁剪掉證件背景的證件圖片。取值：

• Y：是，如果同時採集了證件的正面和背面圖片，則會額外返回兩張裁剪後的圖片。

• N：否

"Y"

landmarkCheck

Array

-

否

null

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

說明：landmark檢查僅適用於大馬卡（MyKad）。

[

{"name":"kadPengenalan"},

{"name":"mykadLogo"},

{"name":"flagLogo"},

{"name":"mscLogo"},

{"name":"ghostFace"},

{"name":"hibiscusLogo"},

{"name":"coatOfArm"},

{"name":"twinTower"}

]

hologramCheck

Array

-

否

null

在證件防偽檢測中進行全息圖檢查，詳細檢查項，請參見證件防偽檢測組件。

說明：全息圖檢查僅適用於大馬卡（MyKad）。

[

{

"name": "hologram"

}

]

pageInfoCheck

Array

-

否

null

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

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

[

{"name":"id"},

{"name":"symbol"},

{"name":"name"}

]

consistencyCheck

List<ConsistencyCheckItem>

-

否

null

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

[

{

"type": "commonConsistencyCheck"

},

{

"details": [

"NAME",

"SEX"

],

"type": "mrzVisualConsistencyCheck"

}

]

riskMode

String

10

否

STANDARD

ID Recognition中的多維度風控冷卻規則校正，用於攔截可疑交易。取值：

• CLOSED：關閉風控冷卻規則。該等級適用於測試情境，測試進程不受風控規則的影響。

• STANDARD：推薦的標準等級。

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

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

"STANDARD"

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：不開啟

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

"Y"

docUiType

String

20

否

• Native SDK：2

• Web SDK：3

證件照片的採集方式。取值如下：

• 1：手拍版（Self-capture），使用者需要手動拍攝證件照片，僅具備基礎防偽能力。

• 2：Native防偽版（Deep-scan），僅適用於Native SDK。ZOLOZ SDK將自動對齊並拍攝證件照片，具備攔截彩打等進階防偽能力。

• 3：H5掃描版（Auto-scan），僅適用於Web SDK。ZOLOZ SDK將自動對齊並拍攝證件照片，僅具備基礎防偽能力。
  建議Web SDK使用自動掃描的採集方式，因為與手拍版相比，自動掃描的使用者體驗更好且證件圖片品質更高。
  

• 4：甩證版（Trace-scan），僅適用於Native SDK。當ZOLOZ SDK在網路攝影機範圍內檢測到證件時將自動拍攝。該版式可用於提升使用者體驗，但防偽能力較弱，僅具備基礎防偽能力。
  說明：該採集方式已廢棄並停止維護。
  

• 5：多角度版（Multi-angle），僅適用於Web SDK中的中國香港證件。使用者需要分別拍攝正對證件的照片和證件傾斜30°的照片，具備攔截彩打等進階防偽能力。

說明：Deeper功能依賴Deep-scan和Auto-scan這兩種採集方式。當開啟Deeper功能時，為確保最佳檢測效果，請根據您的實際應用情境選擇對應的採集方式，Native端使用Deep-scan，H5端使用Auto-scan，否則會影響檢測效果。

"2"

spoofMode

String

10

否

CLOSED

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

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

• STANDARD：推薦的標準等級。

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

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

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

"STANDARD"

deeperMode

String

10

否

CLOSED

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

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

• STANDARD：推薦的標準等級。

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

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

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

"STANDARD"

enableUpload

String

1

否

N

是否允許上傳檔案擷取證件圖片。取值：

• Y：允許上傳檔案擷取證件圖片。啟用此功能需注意以下事項：

• 在此情境下，IDR會將證件識別總結果置為Failure。

• Web SDK特殊配置：

• enableUpload=Y且isDesktop=Y：表示啟用PC端圖片上傳功能。

  • enableUpload=Y且isDesktop=N：表示啟用移動端圖片上傳功能。

• N：不允許上傳檔案擷取證件圖片。

SDK版本要求：

• iOS SDK：需使用2.1.2.260114104408及以上版本。

• Android SDK：需使用2.1.2.260115144712及以上版本。

"Y"

欄位名稱

資料類型

取值範圍

描述

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

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

欄位名稱

資料類型

必須返回

描述

樣本值

result

Result

是

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

{

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

}

transactionId

String

否

ZOLOZ伺服器為證件識別進程產生的唯一事務ID。此ID將作為ID Recognition checkresult API請求的輸入參數。

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

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

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

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

"G000000005FID20200304000000000001570702"

clientCfg

String

否

用戶端配置資訊，包括SDK串連和行為參數。

說明：當result.resultStatus的值為S時，才返回該欄位。

"……"

結果碼

結果狀態

描述

SUCCESS

S

API調用成功。

HIGH_RISK

F

檢測到高風險。使用者帳號被風險引擎凍結。

ACCOUNT_SERVICE_SUSPEND

F

使用者帳號被風險引擎列入黑名單。

DEVICE_NOT_SUPPORT

F

不支援當前的裝置類型。

OS_NOT_SUPPORT

F

不支援當前裝置的作業系統。

SDKVERSION_NOT_SUPPORT

F

不支援ZOLOZ SDK當前的版本。

INVALID_ARGUMENT

F

輸入參數無效。關於無效參數的詳細資料，請查看返回的resultMessage。

SYSTEM_ERROR

F

其他內部錯誤。有關錯誤詳情，請查看返回的resultMessage。