initialize

2022-05-09 03:03

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

ZOLOZ Real ID 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`。
flowType	String	32	必填项。身份验证流的类型。支持以下值： `REALIDLITE_KYC`：使用 App SDK 接入模式。 `H5_REALIDLITE_KYC`：使用 H5 接入模式。
docType	String	16	必填项。证件类型，例如要上传的文件是护照，则将该属性的值设置为`00000001003`。Real ID支持的证件类型，请参见支持的证件类型和返回的OCR。
userId	String	64	必填项。商家用户 ID，或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。建议对 userId 字段的值进行预脱敏，如进行哈希处理。
sceneCode	String	64	可选项。场景码，用来为数据分析指定不同的业务场景。当数据分析需要区分业务场景时，。当需要区分不同业务场景中的数据表现时，建议根据业务用途将 sceneCode 字段设置为不同的值，例如 login、riskVerify、payment、changePassword。
serviceLevel	String	32	可选项。服务级别，即为欺诈检查和活体检测配置服务等级。不同的服务等级其享受到的服务不同，如下： `REALID0001`：该值表示在身份验证进程中，需要用户手动拍摄身份证件照片。ZOLOZ 服务器进行基本的欺诈检查，以及使用眨眼检测方法进行基本的活体检查。 `REALID0002`：该值表示在身份验证进程中，ZOLOZ SDK 自动扫描身份证件。 ZOLOZ 服务器进行高级欺诈检查，以及使用眨眼检测方法进行基本的活体检查。
operationMode	String	32	可选项。操作模式，即为身份验证配置操作模式。如下： `CLOSED`：所有算法和风险控制规则均未应用。总体通过率为100%。您可以在测试阶段使用这种操作模式，使算法和风控规则不影响测试进程。 `STANDARD`：应用标准推荐水平。整体通过率为90%，攻击者拦截率为95%。 `LOOSE`：应用相对宽松的级别。整体通过率99%，风控拦截率1%，攻击者拦截率80%。您可以在低风险场景中使用此操作模式。 `STRICT`：应用更严格的级别。整体通过率为80%，攻击者拦截率为99%。您可以在高风险场景中使用此操作模式。
pageConfig	Object		可选项。指定嵌入式 H5 页面的配置设置。有关详细信息，请参阅 pageConfig。
h5ModeConfig	Object		可选项。H5 Real ID 流的配置信息。当 H5 模式中的 flowType 字段为`H5_REALIDLITE_KYC`时，需设置 h5ModeConfig。更多信息请参见 h5ModeConfig。

响应参数

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

结果

结果处理逻辑

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

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

通用错误码

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

API 结果码

Connect 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 模式下初始化身份验证时，还必须为其指定一个名为 h5ModeConfig 的对象。有关详细信息，请参阅以下两个请求示例。

原生 RealId 请求示例

以下是在 App SDK 模式下初始化身份验证的请求代码示例。

copy
{
    "bizId": "2017839040588699",
    "flowType": "REALIDLITE_KYC",   
    "userId": "123456abcd",
    "docType": "08520000001",
    "pageConfig":{
      "urlFaceGuide":"http://url-to-face-guide-page.htm"
    },
    "serviceLevel": "REALID0001",
    "operationMode": "STANDARD",
    "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 模式下初始化身份验证的请求代码示例。

copy
{
    "bizId": "2017839040588699",
    "flowType": "H5_REALIDLITE_KYC",   
    "userId": "123456abcd",
    "docType": "08520000001",
    "pageConfig":{
      "urlFaceGuide":"http://url-to-face-guide-page.htm"
    },
    "serviceLevel": "REALID0001",
    "operationMode": "STANDARD",
    "metaInfo": "MOB_H5",
    "h5ModeConfig":{
      "completeCallbackUrl":"http://xxx.html",
      "interruptCallbackUrl":"http://xxx.html"
    }
}

响应示例

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

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

字段名称	数据类型	最大长度	描述
state	String	128	可选项。用于恢复客户上下文的标识符。您可以为该字段设置任何值，然后在 ZOLOZ SDK 回调商户应用时将该值作为参数被传递。如果未设置该值，则使用 transactionId 字段的值。
completeCallbackUrl	String	128	必选项。在整个身份验证完成时，为浏览器指定即将重定向的回调 URL。
interruptCallbackUrl	String	128	必选项。指定进程中断时重定向浏览器的回调 URL。
locale	String	16	可选项。网页语言，目前仅支持：en/zh-CN/zh-HK/jp/th。
isIframe	String	1	可选项。是否需要在 iframe 中打开网页，如果需要，则设置为 Y，否则设置为 N。取值范围： Y / N
uiCfg	String	256	可选项。自定义的 UI 配置，JSON 字符串格式。目前仅支持`titlebarbgcolor`、`titlebartextcolor`和`buttoncolor`。例如：`"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\"}"`.

日期	日志变更
2020.9.8	支持另外两种身份证件：马来西亚大马卡和澳门身份证。在请求参数中新增一个 h5ModeConfig 参数。
2020.6.9	在请求参数中新增一个 pageConfig 参数。
2019.12.27	将 productLevel 参数重命名为 serviceLevel，并更新相关描述。
2019.12.20	新增以下两个请求参数： productLevel operationMode
2019.12.6	首次发布