initialize

2024-12-06 08:40

概览

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`。说明：`docType`和`autoDocTypes`不能同时传入，需选择其中一个传入。 ID Recognition支持的证件类型，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。	"08520000001"
autoDocTypes	List<String>	200	否	null	证件类型列表。`docType`和`autoDocTypes`不能同时传入，需选择其中一个传入。如果传入`autoDocTypes`，ZOLOZ将自动对上传的证件进行分类。说明：目前护照不支持自动分类。新加坡证件`00650000001`和`00650000002`将统一归类为`00650000001`。如果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"
operationMode	String	32	否	STANDARD	为身份验证配置操作模式。取值如下： `CLOSED`：所有的算法和风控规则都未开启。该操作模式可用于测试场景，测试进程不受算法和风控规则的影响。 `STANDARD`：推荐的标准模式。 `LOOSE`：相对宽松的模式，可用于低风险场景。 `STRICT`：相对严格的模式，可用于高风险场景。	"STANDARD"
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字符串格式。目前仅支持`titlebarbgcolor`、`titlebartextcolor`、`buttoncolor`和`captureMode`。说明：如果将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结果。	在`details`中指定OCR字段进行一致性检查。当`type`设置为`mrzVisualConsistencyCheck`时，必须传入`details`字段。仅允许传入证件类型所支持的OCR字段。	MyVisa / 马来西亚 / 00600000011	NAME SEX
details	List<String>	请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。		护照（含机读区和视读区）/ 中国大陆、中国香港、中国台湾、中国澳门、菲律宾、新加坡、马来西亚 / 00000001006	ID_NUMBER COUNTRY_CODE EXPIRY_DATE DATE_OF_BIRTH

passportCountryCheck

字段名称	数据类型	取值范围	描述	支持的证件 / 国家或地区 / 证件类型 / OCR一致性检查支持字段 / 默认国家代码
type	String	passportCountryCheck	检查OCR结果中的`COUNTRY_CODE`与系统检测到的国家是否一致。	-
valueRange	List<String>	应与默认国家代码一致	OCR结果中的`COUNTRY_CODE`应在`valueRange`范围内。当`type`设置为`passportCountryCheck`时，必须传入`valueRange`字段，各证件支持的`valueRange`，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。	以下证件的`valueRange`为证件所属国家或地区对应的默认国家或地区代码所组成的列表。中国大陆护照 / 00860000888 / COUNTRY_CODE / CHN 中国台湾护照 / 08860000002 / COUNTRY_CODE / TWN 中国澳门护照 / 08530000002 / COUNTRY_CODE / CHN 菲律宾旧版护照 / 00630000031 / COUNTRY_CODE / PHL 菲律宾新版护照 / 00630000032 / COUNTRY_CODE / PHL
valueRange	List<String>	每一项都应符合ISO_3166-1_alpha-3标准		以下证件的`valueRange`为列表，且每一项都应符合ISO_3166-1_alpha-3标准。国际护照（仅含机读区） / 00000001003 / COUNTRY_CODE 国际护照（含机读区和视读区）/ 00000001006 / COUNTRY_CODE

返回参数

字段名称	数据类型	必须返回	描述	示例值
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"
      },
      {
        "valueRange": [
          "CHN",
          "PHL"
        ],
        "type": "passportCountryCheck"
      }
    ],
    "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\"
    }",
   "serviceLevel": "IDRECOGNITION0002",
   "operationMode": "CLOSED"
}

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"
      },
      {
        "valueRange": [
          "CHN",
          "PHL"
        ],
        "type": "passportCountryCheck"
      }
    ],
    "pageInfoCheck": [
            {
                "name": "id"
            },
            {
                "name": "symbol"
            },
            {
                "name": "name"
            }
        ],
    "allowExpiredDocument": "Y",
    "cropFaceImageFromDoc": "Y",
    "enableOCR": "Y",
    "spoofMode": "STANDARD"
  },
  "serviceLevel": "IDRECOGNITION0002",
  "operationMode": "CLOSED"
}

返回示例

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

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