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接入模式,则设置为 | "{ \"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 | 指定证件类型。例如要上传的证件是护照,该字段的值需要设置为 说明: ID Recognition支持的证件类型,请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。 | "08520000001" |
autoDocTypes | List<String> | 200 | 否 | null | 证件类型列表。
支持的证件类型,请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。 | ["08520000001","08520000002"] |
pages | String | 32 | 否 | 证件类型支持的所有页 | 待进行证件识别的证件页面,多个页面以英文逗号分隔。例如:
证件所支持的页面数,请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。 说明:
| "1" |
serviceLevel | String | 32 | 否 | IDRECOGNITION0002 | 服务等级。取值如下:
| "IDRECOGNITION0002" |
h5ModeConfig | H5ModeConfig | - | 否 | null | H5 ID Recognition的配置信息。详细信息,请参见H5ModeConfig。 说明:当metaInfo的值为 | { "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字符串格式。目前仅支持 说明:如果将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 | - | 否 | 不同的证件类型有不同的默认值:
| 已过期的证件是否可以通过验证。取值:
说明:如果传入的值为空或无效,此时将使用默认取值。 | "N" |
cropFaceImageFromDoc | String | 1 | 否 | N | 是否从采集的证件图片中裁剪出人脸图片。取值如下:
| "Y" |
enableOCR | String | - | 否 | N | 是否开启OCR功能。取值如下:
注意:需要先购买OCR产品,才能使用该功能。 | "Y" |
spoofMode | String | 10 | 否 | CLOSED | 证件防伪等级。取值如下:
注意:需要先购买Spoof产品,才能使用该功能。 | "STANDARD" |
ConsistencyCheckItem类型说明
commonConsistencyCheck
字段名称 | 数据类型 | 取值范围 | 描述 | 支持的证件 / 国家或地区 / 证件类型 | OCR一致性检查支持字段 |
type | String | commonConsistencyCheck | OCR字段一致性检查。 | 大马卡 / 马来西亚 / 00600000001 |
|
mrzVisualConsistencyCheck
字段名称 | 数据类型 | 取值范围 | 描述 | 支持的证件 / 国家或地区 / 证件类型 | OCR一致性检查支持字段 |
type | String | mrzVisualConsistencyCheck | 对机读区和视读区的OCR字段进行一致性检查。 | - | - |
details | List<String> | 在详细信息中指定OCR字段进行一致性检查。
| MyVisa / 马来西亚 / 00600000011 |
| |
护照(含机读区和视读区)/ 中国大陆、中国香港、中国台湾、中国澳门、菲律宾、新加坡、马来西亚 / 00000001006 |
|
返回参数
字段名称 | 数据类型 | 必须返回 | 描述 | 示例值 |
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模式下启动证件识别进程的请求代码示例。
{
"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模式下启动证件识别进程的请求代码示例。
{
"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服务器返回的响应代码示例。
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success"
},
"transactionId":"G000000005FID20200304000000000001570702",
"clientCfg": "……"
}