initialize

2022-06-24 08:25

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

ZOLOZ Face Capture initialize API 用于初始化 ZOLOZ 中的人脸采集进程，并为其生成一个唯一的事务 ID。后续在与 ZOLOZ 交互的所有过程中均使用该事务 ID。此 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\"}"`. 说明：不要修改返回值，直接传递即可。如果是 H5 接入模式，则设置为`MOB_H5`。
userId	String	32	必填项。商家用户 ID，或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。建议对 userId 字段的值进行预脱敏，如进行哈希处理。
serviceLevel	String	32	可选项。服务等级，合法值包括： FACECAPTURE002: 单眨眼活体 FACECAPTURE003: 随机多动作活体默认值为FACECAPTURE002。
h5ModeConfig	Object		可选项。为 H5 接入模式设置相关的配置项。更多信息请参见 h5ModeConfig。

响应参数

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

结果

结果处理逻辑

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

当 result.resultStatus 的值为 S时，表示调用 ZOLOZ Face Capture initialize API 成功，并返回唯一的事务 ID。
当 result.resultStatus 的值为 F时，表示调用 ZOLOZ Face Capture initialize API 失败。请检查错误码以获取有关该错误的更多信息，并分析可能导致该错误的原因。

通用错误码

有关常见错误码的完整列表，请参见错误处理中常见错误码部分。

API 结果码

Connect initialize API 的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API 调用成功。
HIGH_RISK	F	检测到高风险。用户账号被风险引擎冻结。
DEVICE_NOT_SUPPORT	F	不支持当前的设备类型。
OS_NOT_SUPPORT	F	不支持当前设备的操作系统。
SDKVERSION_NOT_SUPPORT	F	不支持 ZOLOZ SDK 当前的版本。
INVALID_ARGUMENT	F	输入参数无效。关于无效参数的详细信息，请查看结果消息或相关日志。
SYSTEM_ERROR	F	其他内部错误。关于错误详情，请查看返回的结果消息和相关日志。

代码示例

请求示例

不同的集成模式其请求结构略有不同。在 H5 模式下初始化人脸采集进程时，还必须为其指定一个名为 h5ModeConfig 的对象。有关详细信息，请参阅以下两个请求示例。

原生 FaceCapture 请求示例

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

copy
{
    "bizId":"test-bizId",
    "metaInfo": "{\"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": "not mandatory"
}

H5 FaceCapture 请求示例

以下是在 H5 模式下初始化人脸采集的请求代码示例。

copy
{
    "bizId":"dummy_bizid_1626180988600",
    "metaInfo":"MOB_H5",
    "userId":"dummy_userid_1626180988600",
    "h5ModeConfig":{
        "completeCallbackUrl":"http://xxx/result.html",
        "interruptCallbackUrl":"http://xxx/result.html"
    }
}

响应示例

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

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

字段名称	数据类型	最大长度	描述
state	String	128	可选项。用于恢复客户上下文的标识符。您可以为该字段设置任何值，然后在 ZOLOZ SDK 回调商户应用时将该值作为参数被传递。如果未设置该值，则使用 transactionId 字段的值。
completeCallbackUrl	String	128	必选项。在整个身份验证完成时，为浏览器指定即将重定向的回调 URL。
interruptCallbackUrl	String	128	必选项。指定进程中断时重定向浏览器的回调 URL。
isIframe	String	1	可选项。网页是否需要在 iframe 中打开，如果需要，则设置为 Y，否则设置为 N。取值范围： Y / N
locale	String	16	可选项。网页语言，目前仅支持：en/id。