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 字符串格式返回,例如:

"{\"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 字段的值进行预脱敏,如进行哈希处理。

docType

String

16

必填项。证件类型,例如待上传的证件是护照,则应将该字段的值设置为 00000001003。该字段的值不能为 null 或空字符串。关于支持的证件类型的更多信息,请参见 支持的文档类型和返回的 OCR 结果

pages

String

32

可选项。待进行 ID 识别的证件页面,有多个页面时使用逗号分隔。有关证件页面的范围,请参见 支持的文档类型和返回的 OCR 结果

serviceLevel

String

32

可选项。支持以下三个级别的服务:

  • IDRECOGNITION0002(默认):基本的反欺诈,仅采集证件的普通照片。
  • IDRECOGNITION0003:手电筒式的反欺诈。该级别仅支持在原生 SDK 中使用,因为 Web SDK 在操作手电筒方面存在技术限制。如果在 web SDK 中使用,行为将不可预测。
  • IDRECOGNITION0005:多维度的防欺诈。该级别只支持在 web SDK 中使用,在原生 SDK 中使用时行为不可预测。目前,此级别仅支持香港身份证,未来可能会支持其他证件类型。

h5ModeConfig

Object

可选项。H5 ID Recognition 流程的配置集。更多信息参见 h5ModeConfig

响应参数

字段名称

数据类型

描述

result

Result

必填项,API 请求结果,包含 API 请求结果的详细信息,例如状态和错误码。

transactionId

String

可选项, ZOLOZ 服务器为 ID 识别进程生成的唯一事务 ID。此 ID 将用作 ID recognition checkresult API 请求的输入参数。

说明:当 ID 识别进程中出现错误时,例如参数无效,则不返回事务 ID。

clientCfg

String

可选项,客户端配置信息,包括 SDK 连接和行为参数。仅当 result.resultStatus 字段为S时,才需要指定该字段的值。

结果

结果处理逻辑

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

  • 当 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 模式中启动身份验证进程的请求示例。

copy
{
    "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 识别进程的请求示例。

copy
{
    "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 服务器返回的响应代码示例。

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

更多信息

h5ModeConfig

h5ModeConfig 对象中字段的说明见下表。

字段名称

数据类型

最大长度

描述

state

String

128

completeCallbackUrl

String

128

必填项。整个身份验证完成时浏览器被重定向的回调 URL。

interruptCallbackUrl

String

128

必填项。进程中断时重定向浏览器的回调 URL。

isIframe

String

1

可选项。当需要在 iframe 中打开网页时,该字段应该设置为 Y。

取值范围:Y / N

uiCfg

String

256

可选项。 JSON 字符串格式的自定义 UI 配置。目前仅支持titlebarbgcolortitlebartextcolorbuttoncolorcaptureMode

例如:"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\", \"captureMode\":\"landscape\"}"

如果将captureMode参数设置为 landscape,SDK 将切换到横向采集模式。