概覽

API URL：/api/v1/zoloz/connect/initialize
API 描述：該介面用於初始化ZOLOZ中的人臉驗證進程，並為其產生一個唯一的事務ID。後續在與ZOLOZ互動的所有過程中均使用該事務ID。

說明

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

請求參數

欄位名稱	資料類型	最大長度	是否必填	預設值	描述	樣本值
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"
sceneCode	String	64	否	null	情境碼，用來為資料分析指定不同的業務情境。當需要區分不同業務情境中的資料表現時，建議根據業務用途為sceneCode欄位設定不同的值，例如login、riskVerify、payment、changePassword。	"changePassword"
serviceLevel	String	32	否	CONNECT0002	人臉活體檢測服務等級。取值如下： `CONNECT0001`：該等級具有基本的活體檢測能力。檢測過程直接在原頁面完成，從而減少了使用者流失。該等級適用於對通過率要求較高的情境。 `CONNECT0002`：該等級具有基本的活體檢測能力。ZOLOZ SDK使用眨眼檢測方法進行活體檢測。 `CONNECT0003`：該等級具有高等級的活體檢測能力。ZOLOZ SDK使用多動作檢測方法進行活體檢測。說明：H5模式不支援傳入serviceLevel欄位。	"CONNECT0002"
operationMode	String	32	否	STANDARD	為身分識別驗證配置操作模式。取值如下： `CLOSED`：所有的演算法和風控規則都未開啟。該操作模式可用於測試情境，測試進程不受演算法和風控規則的影響。 `STANDARD`：推薦的標準模式。 `LOOSE`：相對寬鬆的模式，可用於低風險情境。 `STRICT`：相對嚴格的模式，可用於高風險情境。說明：H5模式不支援傳入operationMode欄位。	"STANDARD"
h5ModeConfig	H5ModeConfig	-	否	null	H5 Connect的配置資訊。詳細資料，請參見H5ModeConfig。說明：當metaInfo的值為`MOB_H5`時必須傳入該欄位。	{ "completeCallbackUrl":"http://xxx.html", "interruptCallbackUrl":"http://xxx.html" }
productConfig	ProductConfig	-	否	null	為Connect產品提供更精細化的控制。詳細資料，請參見ProductConfig。說明：如果同時設定了productConfig、serviceLevel和operationMode，則serviceLevel和operationMode均不生效，ZOLOZ將唯讀取productConfig的值。	{ "livenessMode":"STANDARD", "antiInjectionMode":"CLOSED", "actionCheckItems":["FACEBLINK","HEADLOWER"], "actionRandom":"Y" }

H5ModeConfig欄位說明

欄位名稱	資料類型	最大長度	是否必填	預設值	描述	樣本值
state	String	128	否	transactionId欄位的值	用於恢複客戶內容相關的標識符。您可以為該欄位設定任何值，當ZOLOZ SDK回調商戶的移動App時將該值作為參數進行傳遞。	"G006600016CN20190114000000009572520355"
completeCallbackUrl	String	128	是	-	當整個身分識別驗證完成時，為瀏覽器指定即將重新導向的回調URL。	"http://xxx.html"
interruptCallbackUrl	String	128	是	-	當進程中斷時，為瀏覽器指定重新導向到的回調URL。	"http://xxx.html"
locale	String	16	否	en	網頁語言，目前僅支援以下語言： en（英語） id（印尼語） zh-CN（簡體中文）	"en"
isIframe	String	1	否	N	是否需要在iframe中開啟網頁，如果需要設定為Y，否則設定為N。	"Y"
uiCfg	String	256	否	null	自訂UI配置，採用JSON字串格式。目前僅支援`titlebarbgcolor`、`titlebartextcolor`和`buttoncolor`。	"{\"titleBackgroudColor\": \"#0064FF\",\"titleTextColor\": \"#FFFFFF\",\"topTipColor\": \"#0064FF\"}"

ProductConfig欄位說明

欄位名稱	資料類型	最大長度	是否必填	預設值	描述	樣本值
livenessMode	String	10	否	STANDARD	人臉活體檢測等級。取值如下： `CLOSED`：所有的演算法和風控規則都未開啟。該等級可用於測試情境，測試進程不受演算法和風控規則的影響。 `STANDARD`：推薦的標準等級。 `LOOSE`：相對寬鬆的等級，可用於低風險情境。 `STRICT`：相對嚴格的等級，可用於高風險情境。	"STANDARD"
antiInjectionMode	String	10	否	CLOSED	該參數已廢棄，後續不再維護，為了保證API相容性，該參數會繼續保留。防注入檢測等級。防注入檢測能夠有效抵禦使用換臉圖片或視頻進行的注入攻擊。取值如下： `CLOSED`：所有的防注入演算法都不開啟。如果業務情境不需要注入攻擊檢測，則不需要開啟。 `STANDARD`：推薦的標準等級。 `LOOSE`：預留等級，暫不支援使用。 `STRICT`：預留等級，暫不支援使用。注意：開啟防注入檢測會略微增加誤判率和已耗用時間，開啟前請先聯絡ZOLOZ支援人員。	"CLOSED"
actionCheckItems	List<String>	-	否	FACEBLINK	用戶端和Web端的動作檢測列表。取值如下： `FACEBLINK`：眨眼 `MOUTHOPEN`：張嘴 `HEADSHAKE`：搖頭 `HEADLOWER`：低頭 `HEADRAISE`：抬頭說明：為了更好的使用者體驗，不建議使用兩種及以上的動作。	["FACEBLINK","HEADLOWER"]
actionRandom	String	1	否	N	用戶端和Web端的動作檢測順序是否隨機。取值如下： `Y`：隨機。 `N`：不隨機，則按照actionCheckItems中的順序進行檢測。	"Y"
deeperMode	String	10	否	CLOSED	AIGC攻擊檢測的Deeper等級，Deeper檢測功能的詳細介紹，請參見什麼是Deeper。該參數支援以下取值： `CLOSED`：Deeper的所有能力均不開啟，例如AIGC檢測演算法、終端風險檢測等。如果業務情境不需要AIGC攻擊檢測，則無需開啟。 `STANDARD`：推薦的標準等級。 `LOOSE`：相對寬鬆的等級，可用於低風險情境。 `STRICT`：相對嚴格的等級，可用於高風險情境。注意：需要先購買Deeper產品，才能使用該功能。	"STANDARD"

返回參數

欄位名稱	資料類型	必須返回	描述	樣本值
result	Result	是	API請求結果，包含結果狀態、結果碼和結果訊息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	否	ZOLOZ伺服器為人臉驗證進程產生的唯一事務ID。此ID將作為Connect checkresult API請求的輸入參數。說明：僅當交易進入處理階段後系統才會返回`transactionId`。如果在開始處理交易之前發生錯誤，系統不會返回`transactionId`。包括但不限於以下情況：請求參數非法，例如入參格式錯誤或缺失必傳參數。請求未能成功到達伺服器，例如網路問題或網關故障。系統限流導致請求被拒絕。	"G006600016CN20190114000000009572520355"
clientCfg	String	否	用戶端配置資訊，包括SDK串連和行為參數。說明：當result.resultStatus的值為S時，才返回該欄位。	"……"

處理結果

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

當result.resultStatus的值為S時，表示調用ZOLOZ Connect initialize API成功，並返回唯一的事務ID。
當result.resultStatus的值為F時，表示調用ZOLOZ Connect initialize API失敗。請檢查錯誤碼擷取有關該錯誤的更多資訊，並分析導致該錯誤的原因。

API通用結果碼

有關通用結果碼的完整列表，請參見API通用結果碼。

API特有結果碼

Connect initialize API的結果碼見下表。

結果碼	結果狀態	描述
SUCCESS	S	API調用成功。
UNABLE_GET_IMAGE	F	未找到參考源（因未註冊而驗證導致的錯誤）。
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。

程式碼範例

請求樣本

不同的接入模式請求結構略有不同。在H5模式下初始化身分識別驗證時，必須指定H5ModeConfig對象。

原生Connect請求樣本

{
 "bizId": "2017839040588699",
 "userId": "merchant side user id",
 "sceneCode": "changePassword",
 "serviceLevel": "CONNECT0002",
 "metaInfo": "{
 \"deviceType\": \"deviceType\",
 \"appVersion\": \"1.0\",
 \"osVersion\": \"7.1.1\",
 \"appName\": \"com.alipay.android.zoloz.company\",
 \"bioMetaInfo\": \"3.37.0:262144,0\",
 \"apdidToken\": \"mock-apdidToken\",
 \"deviceModel\": \"MI 6\",
 \"zimVer\": \"2.0.0\"
 }",
 "productConfig": {
 "livenessMode":"STANDARD",
 "antiInjectionMode":"CLOSED",
 "actionCheckItems":["FACEBLINK","HEADLOWER"],
 "actionRandom":"Y"
 }
}

H5 Connect請求樣本

{
 "bizId": "2017839040588699",
 "userId": "merchant side user id",
 "sceneCode": "changePassword",
 "metaInfo": "MOB_H5",
 "h5ModeConfig":{
 "completeCallbackUrl":"http://xxx.html",
 "interruptCallbackUrl":"http://xxx.html"
 },
 "productConfig": {
 "livenessMode":"STANDARD",
 "antiInjectionMode":"CLOSED",
 "actionCheckItems":["FACEBLINK","HEADLOWER"],
 "actionRandom":"Y"
 }
}

返回樣本

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

copy

{
 "result": {
 "resultStatus": "S",
 "resultCode": "SUCCESS",
 "resultMessage": "Success"
 },
 "transactionId":"G006600016CN20190114000000009572520355", 
 "clientCfg": "……" 
}