概覽

API URL：/api/v1/zoloz/nfc/initialize
API 描述：該介面用於初始化ZOLOZ中的NFC身份識別服務，並為其產生一個唯一的事務ID。後續在與ZOLOZ互動的所有過程中均使用該事務ID。

說明

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

請求參數

欄位名稱	資料類型	最大長度	是否必填	描述	樣本值
bizId	String	32	是	業務ID，業務的唯一標識，用於追蹤業務。例如，商戶業務相關資料庫中的序號。說明：ZOLOZ伺服器不檢查該欄位的值是否唯一。為了更便捷地追蹤業務，建議開啟商戶伺服器，並確保業務ID的唯一性。	"781852350934518"
metaInfo	String	512	是	SDK和使用者裝置的元資訊。該欄位的值由ZOLOZ SDK以JSON字串格式返回。說明：不要修改傳回值，直接傳遞即可。	"{ \"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\" }"
docType	String	16	是	指定證件類型。NFC僅支援以下兩種證件類型： `00000001003`：護照。 `00860000011`：大陸居民往來港澳通行證。	"00860000011"
userId	String	64	是	商戶的使用者ID或其他可用於識別某一使用者的標識，例如手機號碼、電子郵件地址等。建議對userId欄位的值進行預脫敏，例如進行雜湊處理。	"123456abcd"
flowType	String	32	是	指定身分識別驗證流的接入類型，目前僅支援`NFCLITE`。 `NFCLITE`：使用App SDK接入模式。	"NFCLITE"
nfcConfig	NFCConfig	-	是	針對NFC產品的配置。	{ "docType": "00860000011", "dateOfBirth": "900115", "dateOfExpiry": "281015", "documentNumber": "E40431234", "needClientOCR": "N" }

NFCConfig欄位說明

欄位名稱	資料類型	最大長度	是否必填	預設值	描述	樣本值
docType	String	16	是	-	校正證件類型。目前僅支援以下兩種證件類型： `00000001003`：護照。 `00860000011`：大陸居民往來港澳通行證。	"00860000011"
needClientOCR	String	1	是	Y	是否通過用戶端進行OCR識別。 `Y`：是。當needClientOCR為Y時，用戶端OCR會識別出documentNumber、dateOfBirth和dateOfExpiry欄位，無需客戶單獨傳入。 `N`：否。當needClientOCR為N時，必須傳入documentNumber、dateOfBirth和dateOfExpiry欄位。	"Y"
documentNumber	String	9	否	null	證件號碼。	"E40431234"
dateOfBirth	String	6	否	null	出生日期，日期格式為yyMMdd。說明：該欄位為固定長度，長度必須為6位。	"900115"
dateOfExpiry	String	6	否	null	證件到期日，日期格式為yyMMdd。說明：該欄位為固定長度，長度必須為6位。	"281015"

返回參數

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

處理結果

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

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

API通用結果碼

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

API特有結果碼

NFC Reader initialize API的結果碼見下表。

結果碼	結果狀態	描述
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。

程式碼範例

請求樣本

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

{
  "bizId": "781852350934518",
  "docType": "00860000011",
  "metaInfo": {
    "apdidToken": "53237637-3082-4297-bf0f-e4fa2a4ef933",
    "appName": "com.zoloz.saas.demoapp",
    "appVersion": "1.3",
    "bioMetaInfo": "3.61.0:5570560,2;JIAJAAAAAAAAAAAJ",
    "deviceModel": "MI 6",
    "deviceType": "android",
    "jsonFormat": false,
    "osVersion": "9",
    "sdkVersion": "3.61.0",
    "zimVer": "1.0.0"
  },
  "flowType": "NFCLITE",
  "nfcConfig": {
    "docType": "00860000011",
    "dateOfBirth": "900115",
    "dateOfExpiry": "281015",
    "documentNumber": "E40431234",
    "needClientOCR": "N"
  },
  "userId": "123456abcd"
}

返回樣本

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

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