initialize
入口：/api/v1/zoloz/idrecognition/initialize
ZOLOZ initialize API 用于初始化 ZOLOZ 中的 ID 识别进程。为该进程生成一个唯一的事务 ID，并在与 ZOLOZ 服务器的所有交互中使用。此 API 不符合幂等性。
结构
请求参数
字段名称 | 数据类型 | 最大长度 | 描述 |
bizId | String | 32 | 必填项。出于追踪目的的业务 ID，用来唯一标识某一业务。例如，商户业务相关数据库中的序列号。 说明：ZOLOZ 服务器不检查该字段的值是否唯一。因此为了更便捷地追踪业务，建议开启商户服务器，并确保业务 ID 的唯一性。 |
metaInfo | String | 512 | 必填项。SDK 和用户设备的元信息。该字段的值由 ZOLOZ SDK 以 JSON 字符串格式返回，例如：
说明：不要修改返回值，直接传递即可。 |
userId | String | 64 | 必填项。商家用户 ID，或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。 建议对 userId 字段的值进行预脱敏，如进行哈希处理。 |
docType | String | 16 | 必填项。证件类型，例如待上传的证件是护照，则应将该字段的值设置为 00000001003。该字段的值不能为 null 或空字符串。关于支持的证件类型的更多信息，请参见 支持的文档类型和返回的 OCR 结果。 |
pages | String | 32 | 可选项。待进行 ID 识别的证件页面，有多个页面时使用逗号分隔。有关证件页面的范围，请参见 支持的文档类型和返回的 OCR 结果。 |
serviceLevel | String | 32 | 可选项。支持以下三个级别的服务：
|
h5ModeConfig | Object | 可选项。H5 ID Recognition 流程的配置集。更多信息参见 h5ModeConfig。 |
响应参数
字段名称 | 数据类型 | 描述 |
result | 必填项，API 请求结果，包含 API 请求结果的详细信息，例如状态和错误码。 | |
transactionId | String | 可选项， ZOLOZ 服务器为 ID 识别进程生成的唯一事务 ID。此 ID 将用作 ID recognition checkresult API 请求的输入参数。 说明：当 ID 识别进程中出现错误时，例如参数无效，则不返回事务 ID。 |
clientCfg | String | 可选项，客户端配置信息，包括 SDK 连接和行为参数。仅当 result.resultStatus 字段为 |
结果
结果处理逻辑
根据请求结果执行下一步的响应动作，如下：
- 当 result.resultStatus 的值为
S时 ，表示调用 ZOLOZ initialize API 成功，并返回唯一的事务 ID。 - 当 result.resultStatus 的值为
F时，表示调用 ZOLOZ initialize API 失败。请检查错误码以获取有关该错误的更多信息，并分析可能导致该错误的原因。
通用错误码
有关常见错误码的完整列表，请参见 错误处理 中常见错误码部分。
API 结果码
ID Recognition 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 | 输入参数无效。关于无效参数的详细信息，请查看结果消息或相关日志。 |
SYSTEM_ERROR | F | 其他内部错误。关于错误详情，请查看返回的结果消息和相关日志。 |
示例
请求示例
不同的接入模式，请求结构略有不同。在 H5 模式下启动 ID 识别进程时，必须指定 h5ModeConfig 对象。更多详细信息，请参见以下两个请求示例。
原生请求示例
以下是在 App SDK 模式中启动身份验证进程的请求示例。
{
"bizId": "2017839040588699",
"userId": "123456abcd",
"docType": "08520000001",
"pages": "1",
"metaInfo": "{
\"deviceType\": \"deviceType\",
\"appVersion\": \"1.0\",
\"osVersion\": \"7.1.1\",
\"appName\": \"com.company.wallet\",
\"bioMetaInfo\": \"3.37.0:262144,0\",
\"apdidToken\": \"mock-apdidToken\",
\"deviceModel\": \"MI 6\",
\"zimVer\": \"2.0.0\"
}"
}H5 RealId 请求示例
以下是在 H5 接入模式中启动 ID 识别进程的请求示例。
{
"bizId": "2017839040588699",
"userId": "123456abcd",
"docType": "08520000001",
"pages": "1",
"metaInfo": "MOB_H5",
"h5ModeConfig":{
"completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html",
"interruptCallbackUrl":"http://xxx.html"
}
}响应示例
以下是 ZOLOZ 服务器返回的响应代码示例。
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success"
},
"transactionId":"G000000005FID20200304000000000001570702",
"clientCfg": "……"
}更多信息
h5ModeConfig
h5ModeConfig 对象中字段的说明见下表。
字段名称 | 数据类型 | 最大长度 | 描述 |
state | String | 128 | 可选项。用于恢复客户上下文的标识符。您可以为该任何值，然后在 ZOLOZ SDK 回调商户应用程序时将该值作为参数进行传递。如果未设置该字段的值，则使用 transactionId 字段的值。 |
completeCallbackUrl | String | 128 | 必填项。整个身份验证完成时浏览器被重定向的回调 URL。 |
interruptCallbackUrl | String | 128 | 必填项。进程中断时重定向浏览器的回调 URL。 |
isIframe | String | 1 | 可选项。当需要在 iframe 中打开网页时，该字段应该设置为 Y。 取值范围：Y / N |
uiCfg | String | 256 | 可选项。 JSON 字符串格式的自定义 UI 配置。目前仅支持 例如： 如果将 |