initialize

2022-05-09 03:03

入口：/api/v1/zoloz/connect/initialize

ZOLOZ Connect initialize API 用于初始化 ZOLOZ 中的人脸验证进程。为该进程生成唯一的事务 ID，并在与 ZOLOZ 服务器的所有后续交互中使用。此 API 不符合幂等性。

结构

请求参数

字段名称	数据类型	最大长度	描述
bizId	String	32	必填项。出于追踪目的的业务 ID，用来唯一标识某一业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ 服务器不检查该字段的值是否唯一。因此为了更便捷地追踪业务，建议开启商户服务器，并确保业务 ID 的唯一性。
metaInfo	String	512	必填项。SDK 和用户设备的元信息。该字段的值由 ZOLOZ SDK 以 JSON 字符串格式返回，例如： `"{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}"`. 说明：不要修改返回值，直接传递即可。
userId	String	64	必填项。商家用户 ID，或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。建议对 userId 字段的值进行预脱敏，如进行哈希处理。
sceneCode	String	64	可选项。场景码，用来为数据分析指定不同的业务场景。当数据分析需要区分业务场景时，。当需要区分不同业务场景中的数据表现时，建议根据业务用途将 sceneCode 字段设置为不同的值，例如 login、riskVerify、payment、changePassword。
serviceLevel	String	32	可选项。为人脸活体检测指定服务等级。 serviceLevel 的枚举值如下： CONNECT0001 ：该等级具有基本的活体检测能力。检测过程中用户无需跳转到新页面，从而减少了用户流失。该登录通常适用于对通过率要求较高的场景。 CONNECT0002：默认值。该等级具有基本的反欺骗能力。 ZOLOZ SDK 使用眨眼检测方法执行反欺骗检查。 CONNECT0003 ：该等级具有高等级的反欺骗能力。 ZOLOZ SDK 使用多动作检测方法执行反欺骗检查。

响应参数

字段名称	数据类型	描述
result	Result	必填项，API 请求结果，包含 API 请求结果的详细信息，例如状态和错误码。
transactionId	String	可选项， ZOLOZ 服务器为人脸验证进程生成的唯一事务 ID。此 ID 将用作 Connect checkresult API 请求的输入参数。说明：当人脸验证过程中出现错误时，例如参数无效，则不返回事务 ID。
clientCfg	String	可选项，客户端配置信息，包括 SDK 连接和行为参数。仅当 result.resultStatus 字段为`S`时，才需要指定该字段的值。

结果

结果处理逻辑

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

当 result.resultStatus 的值为 S时，表示调用 ZOLOZ Connect initialize API 成功，并返回唯一的事务 ID。
当 result.resultStatus 的值为 F时，表示调用 ZOLOZ Connect initialize 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	输入参数无效。关于无效参数的详细信息，请查看结果消息或相关日志。
SYSTEM_ERROR	F	其他内部错误。关于错误详情，请查看返回的结果消息和相关日志。

代码示例

请求示例

以下为商家服务器发送的请求代码示例。

copy
{
    "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\"
      }"
}

响应示例

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

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