initialize

2024-01-17 01:01

概览

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"
nfcConfig	NFCConfig	-	否	针对NFC产品的配置。	{ "dateOfBirth": "900115", "dateOfExpiry": "281015", "documentNumber": "E40431234", "needClientOCR": "N" }

NFCConfig字段说明

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
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请求的入参。说明：当身份识别出现错误时，例如参数无效，则不返回事务ID。	"G000000005FID20200304000000000001570702"
clientCfg	String	否	客户端配置信息，包括SDK连接和行为参数。说明：当result.resultStatus的值为S时，才返回该字段。	"……"

处理结果

根据请求结果执行下一步的响应动作，具体如下：

当result.resultStatus的值为S时，表示调用ZOLOZ NFC Reader initialize API成功，并返回唯一的事务ID。
当result.resultStatus的值为F时，表示调用ZOLOZ NFC Reader initialize 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。

代码示例

请求示例

商户服务端发送的请求代码示例。

copy
{
  "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"
  },
  "nfcConfig": {
    "dateOfBirth": "900115",
    "dateOfExpiry": "281015",
    "documentNumber": "E40431234",
    "needClientOCR": "N"
  },
  "userId": "123456abcd"
}

返回示例

ZOLOZ服务器返回的响应代码示例。

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