initialize

概览

  • API URL:/api/v1/zoloz/idrecognition/initialize
  • API 描述:该接口用于初始化ZOLOZ中的证件识别进程,并为其生成一个唯一的事务ID。后续在与ZOLOZ交互的所有过程中均使用该事务ID。

说明:该接口不支持重复调用,即不符合幂等性。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32


-

业务ID,业务的唯一标识,用于追踪业务。例如,商户业务相关数据库中的序列号。

说明:ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务,建议开启商户服务器,并确保业务ID的唯一性。

"2017839040588699"

metaInfo

String

512

-

SDK和用户设备的元信息。该字段的值由ZOLOZ SDK以JSON字符串格式返回。

说明:不要修改返回值,直接传递即可。如果是H5接入模式,则设置为MOB_H5

"{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }"

userId

String

64

-

商户的用户ID或其他可用于识别某一用户的标识,例如手机号码、电子邮件地址等。

建议对userId字段的值进行预脱敏,例如进行哈希处理。

"123456abcd"

docType

String

16

null

指定证件类型。例如要上传的证件是护照,该字段的值需要设置为00000001003

docTypeautoDocTypes不能同时传入,需选择其中一个传入。

ID Recognition支持的证件类型,请参见RealID和ID Recognition支持的证件类型和返回的OCR结果

"08520000001"

autoDocTypes

List<String>

200

null

证件类型列表。docTypeautoDocTypes不能同时传入,需选择其中一个传入。

  • 如果传入autoDocTypes,ZOLOZ将自动对上传的证件进行分类。
    说明
    • 目前护照不支持自动分类。
    • 新加坡证件0065000000100650000002将统一归类为00650000002
  • 如果ZOLOZ无法对上传的证件进行分类或分类的证件类型不在autoDocTypes中,checkresult API将返回NO_REQUIRED_ID

支持的证件类型,请参见RealID和ID Recognition支持的证件类型和返回的OCR结果

["08520000001","08520000002"]

pages

String

32

证件类型支持的所有页

待进行证件识别的证件页面,多个页面以英文逗号分隔。例如:

  • 1:表示识别第一页。
  • 1,2:表示识别第一页和第二页。

证件所支持的页面数,请参见RealID和ID Recognition支持的证件类型和返回的OCR结果

说明

  • 如果不传该字段,默认值为对应证件类型支持的所有页。
  • 当传入autoDocTypes时,pages应为空;如果pages不为空,会返回INVALID_ARGUMENT

"1"

serviceLevel

String

32

IDRECOGNITION0002

服务等级。取值如下:

  • IDRECOGNITION0002:基础防伪等级。
  • IDRECOGNITION0003:使用闪光交互模式的高阶防伪等级。如果设置了该值,ZOLOZ SDK会自动扫描身份证件。该等级仅支持在原生SDK模式下使用。
  • IDRECOGNITION0005:使用多角度交互模式的高阶防伪等级。该等级仅支持在Web SDK模式下使用,且目前该等级仅支持中国香港身份证。

"IDRECOGNITION0002"

h5ModeConfig

H5ModeConfig

-

null

H5 ID Recognition的配置信息。详细信息,请参见H5ModeConfig

说明:当metaInfo的值为MOB_H5时必须传入该字段。

{ "completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html", "interruptCallbackUrl":"http://xxx.html" }

productConfig

ProductConfig

-

null

为IDR产品提供更精细化的控制。详细信息,请参见ProductConfig

参考请求示例

H5ModeConfig字段说明

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

state

String

128

transactionId字段的值

用于恢复客户上下文的标识符。

您可以为该字段设置任何值,当ZOLOZ SDK回调商户的移动App时将该值作为参数进行传递。

"G000000005FID20200304000000000001570702"

completeCallbackUrl

String

128

-

当整个身份验证完成时,为浏览器指定即将重定向的回调URL。

"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html"

interruptCallbackUrl

String

128

-

当进程中断时,为浏览器指定重定向到的回调URL。

"http://xxx.html"

isIframe

String

1

N

是否需要在iframe中打开网页,如果需要设置为Y,否则设置为N。

"Y"

uiCfg

String

256

null

自定义UI配置,采用JSON字符串格式。目前仅支持titlebarbgcolortitlebartextcolorbuttoncolorcaptureMode

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

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

ProductConfig字段说明

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

pageInfoCheck

Array

-

null

在证件防伪检测中进行页面信息检查,详细检查项,请参见证件防伪检测组件

说明:页面信息检查仅适用于中国香港身份证。

[

     {"name":"id"},

     {"name":"symbol"},

     {"name":"name"}

   ]

consistencyCheck

List<ConsistencyCheckItem>

-

null

是否在证件防伪检测中进行一致性检查。一致性检查仅适用于部分证件的特定字段,详见ConsistencyCheckItem

[

     {

       "type": "commonConsistencyCheck"

     },

     {

       "details": [

         "NAME",

         "SEX"

       ],

       "type": "mrzVisualConsistencyCheck"

     }

   ]

allowExpiredDocument

String

-

不同的证件类型有不同的默认值:

  • Y:除护照(docType=00000001003)外的所有证件
  • N:护照(docType=00000001003)

已过期的证件是否可以通过验证。取值:

  • Y:已过期的证件可以通过验证。
  • N:已过期的证件不能通过验证。当检测到证件过期时,IDR流程会失败。

说明:如果传入的值为空或无效,此时将使用默认取值。

"N"

cropFaceImageFromDoc

String

1

N

是否从采集的证件图片中裁剪出人脸图片。取值如下:

  • Y:是
  • N:否

"Y"

enableOCR

String

-

N

是否开启OCR功能。取值如下:

  • Y:开启
  • N:不开启

注意:需要先购买OCR产品,才能使用该功能。

"Y"

spoofMode

String

10

CLOSED

证件防伪等级。取值如下:

  • CLOSED:所有的防伪算法都未开启。该等级可用于测试场景,测试进程不受算法和风控规则的影响。
  • STANDARD:推荐的标准等级。
  • LOOSE预留等级,暂不支持使用
  • STRICT:预留等级,暂不支持使用。

注意:需要先购买Spoof产品,才能使用该功能。

"STANDARD"

ConsistencyCheckItem类型说明

commonConsistencyCheck

字段名称

数据类型

取值范围

描述

支持的证件 / 国家或地区 / 证件类型

OCR一致性检查支持字段

type

String

commonConsistencyCheck

OCR字段一致性检查。

大马卡 / 马来西亚 / 00600000001

  • 证件正面:ID_NUMBER
  • 证件背面:ID_NUMBER_BACK前12位数字

mrzVisualConsistencyCheck

字段名称

数据类型

取值范围

描述

支持的证件 / 国家或地区 / 证件类型

OCR一致性检查支持字段

type

String

mrzVisualConsistencyCheck

机读区和视读区的OCR字段进行一致性检查。

-

-

details

List<String>

请参见RealID和ID Recognition支持的证件类型和返回的OCR结果

在详细信息中指定OCR字段进行一致性检查。

  • type设置为mrzVisualConsistencyCheck时,必须传入details字段,且details不能为空。
  • 仅允许传入证件类型所支持的OCR字段。

MyVisa / 马来西亚 / 00600000011

  • NAME
  • SEX

护照(含机读区和视读区)/ 中国大陆、中国香港、中国台湾、中国澳门、菲律宾、新加坡、马来西亚 / 00000001006

  • ID_NUMBER
  • COUNTRY_CODE
  • EXPIRY_DATE

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

API请求结果,包含结果状态、结果码和结果消息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

ZOLOZ服务器为证件识别进程生成的唯一事务ID。此ID将作为ID Recognition checkresult API请求的输入参数。

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

"G000000005FID20200304000000000001570702"

clientCfg

String

客户端配置信息,包括SDK连接和行为参数。

说明:当result.resultStatus的值为S时,才返回该字段。

"……"

处理结果

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

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

API通用结果码

有关通用结果码的完整列表,请参见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

输入参数无效。关于无效参数的详细信息,请查看返回的resultMessage。

SYSTEM_ERROR

F

其他内部错误。有关错误详情,请查看返回的resultMessage。

代码示例

请求示例

不同的接入模式请求结构略有不同。在H5模式下启动证件识别进程时,必须指定H5ModeConfig对象。

  • 原生请求示例
    在App SDK模式下启动证件识别进程的请求代码示例。
copy
{
  "bizId": "2017839040588699",
  "userId": "123456abcd",
  "autoDocTypes":["08520000001","08520000002"],
  "productConfig": {
    "consistencyCheck": [
      {
        "type": "commonConsistencyCheck"
      },
      {
        "details": [
          "NAME",
          "SEX"
        ],
        "type": "mrzVisualConsistencyCheck"
      }
    ],
    "pageInfoCheck": [
            {
                "name": "id"
            },
            {
                "name": "symbol"
            },
            {
                "name": "name"
            }
        ],
    "allowExpiredDocument": "Y",
    "cropFaceImageFromDoc": "Y",
    "enableOCR": "Y",
    "spoofMode": "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 ID Recognition请求示例
    在H5模式下启动证件识别进程的请求代码示例。
copy
{
  "bizId": "2017839040588699",
  "userId": "123456abcd",
  "autoDocTypes":["08520000001","08520000002"],
  "metaInfo": "MOB_H5",
  "h5ModeConfig":{
    "completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html",
    "interruptCallbackUrl":"http://xxx.html"
  },
  "productConfig": {
    "consistencyCheck": [
      {
        "type": "commonConsistencyCheck"
      },
      {
        "details": [
          "NAME",
          "SEX"
        ],
        "type": "mrzVisualConsistencyCheck"
      }
    ],
    "pageInfoCheck": [
            {
                "name": "id"
            },
            {
                "name": "symbol"
            },
            {
                "name": "name"
            }
        ],
    "allowExpiredDocument": "Y",
    "cropFaceImageFromDoc": "Y",
    "enableOCR": "Y",
    "spoofMode": "STANDARD"
  }
}

返回示例

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

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