字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32B

是

-

业务ID，业务的唯一标识，用于追踪业务。

"trans-test-1234"

docType

String

32B

否

null

证件类型。

• 支持的C类证件，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。
• 支持的B类证件，详见ID Recognition支持的企业类证件和返回的OCR结果。

说明：docType用于指定具体的证件类型，而autoDocTypes和autoDocCategory用于证件自动分类，三个参数互斥，仅支持传入其中一个。

"00000001003"

autoDocTypes

List<String>

200

否

null

证件类型列表。docType、autoDocTypes和autoDocCategory三个参数互斥，仅支持传入其中一个。

• 如果传入autoDocTypes，ZOLOZ将自动对上传的证件进行分类。该功能支持护照自动分类，但仅在Native SDK中可用。
• 如果ZOLOZ无法对上传的证件进行分类或分类的证件类型不在autoDocTypes中，此时将返回NO_REQUIRED_ID。

支持的证件类型，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。

[

"08520000001",

"08520000002"

]

autoDocCategory

List<String>

-

否

null

证件类别列表。docType、autoDocTypes和autoDocCategory三个参数互斥，仅支持传入其中一个。

• 如果传入autoDocCategory，ZOLOZ将自动对上传的证件进行分类。支持的证件类别如下：

• PASSPORT：护照
• DRIVING_LICENSE：驾照
• ID_CARD：身份证
• RESIDENCE_PERMIT：居住证
• VISA：签证
• ALL：所有证件

• 如果ZOLOZ无法对上传的证件进行分类或分类的证件类型不在autoDocCategory中，则将返回NO_REQUIRED_ID。

注意：当传入autoDocCategory时，ZOLOZ可能会识别出新的证件类型，同时在checkresult API中，certType和docCategory会被归类为新的证件类别，这是因为ZOLOZ正在不断扩展其全球范围内的证件支持范围，以覆盖更多类型的证件。

以下示例仅供参考：

当autoDocCategory设置为ALL时，ZOLOZ会根据用户上传的证件进行自动分类，分类完成后，certType可能返回一种新的证件类型，例如00000001001，并归类为NEW_CATEGORY。

为确保系统平稳适配新的证件类型，建议您采取必要的兼容性集成措施，例如避免对返回的certType和docCategory进行强校验。

"ID_CARD"

frontPageImage

String

5MB

是

-

证件的正面照，支持Base64编码的JPG、JPEG、PNG、BMP格式。

注意：frontPageImage和backPageImage两张图片的总大小不能超过5MB，如果图片过大，建议压缩后再上传，以免造成系统错误。

"/9j/4AA..[omitted]..PxA="

backPageImage

String

5MB

否

null

证件的背面照，支持Base64编码的JPG、JPEG、PNG、BMP格式。

注意：frontPageImage和backPageImage两张图片的总大小不能超过5MB，如果图片过大，建议压缩后再上传，以免造成系统错误。

"/9j/4AA..[omitted]..PxA="

operationMode

String

32

否

STANDARD

为身份验证配置操作模式。取值如下：

• CLOSED：所有的算法和风控规则都未开启。该操作模式可用于测试场景，测试进程不受算法和风控规则的影响。
• STANDARD：推荐的标准模式。
• LOOSE：相对宽松的模式，可用于低风险场景。
• STRICT：相对严格的模式，可用于高风险场景。

"STANDARD"

sceneCode

String

64

否

null

场景码，用于为数据分析指定不同的业务场景。

当需要区分不同业务场景中的数据表现时，建议根据业务用途为sceneCode字段设置不同的值，例如login、riskVerify、payment、changePassword。该设置不会影响业务的正常运行。

"changePassword"

userId

String

64

否

null

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

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

"trans-abc-1234"

productConfig

ProductConfig

-

否

null

为IDR产品提供更精细化的控制，详见ProductConfig。

参考请求示例

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

pageInfoCheck

Array

-

否

null

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

说明：页面信息检查仅适用于中国香港身份证和大马卡。

[

{"name":"id"},

{"name":"symbol"},

{"name":"name"}

]

consistencyCheck

List<ConsistencyCheckItem>

-

否

null

是否进行一致性检查。一致性检查仅适用于部分证件的特定字段，详见ConsistencyCheckItem。

[

{

"type": "commonConsistencyCheck"

},

{

"details": [

"NAME",

"SEX"

],

"type": "mrzVisualConsistencyCheck"

},

{

"valueRange": [

"CHN",

"PHL"

],

"type": "passportCountryCheck"

}

]

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：不开启

"Y"

spoofMode

String

10

否

CLOSED

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

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

"STANDARD"

字段名称

数据类型

取值范围

描述

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

OCR一致性检查支持字段

type

String

commonConsistencyCheck

对证件防伪检测中的OCR字段进行一致性检查。

大马卡 / 马来西亚 / 00600000001

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

字段名称

数据类型

取值范围

描述

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

OCR一致性检查支持字段

type

String

mrzVisualConsistencyCheck

对证件防伪检测中机读区和视读区的OCR字段进行一致性检查。

-

-

details

List<String>

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

在details中指定OCR字段进行一致性检查。

• 当type设置为mrzVisualConsistencyCheck时，必须传入details字段。
• 仅允许传入证件类型所支持的OCR字段。

MyVisa / 马来西亚 / 00600000011

• NAME
• SEX

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

• ID_NUMBER
• COUNTRY_CODE
• EXPIRY_DATE
• DATE_OF_BIRTH

往来港澳通行证 / 中国大陆 / 00860000011

• ID_NUMBER
• DATE_OF_EXPIRY

字段名称

数据类型

取值范围

描述

支持的证件 / 国家或地区 / 证件类型 / 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

每一项都应符合ISO_3166-1_alpha-3标准

以下证件的valueRange为列表，且每一项都应符合ISO_3166-1_alpha-3标准。

• 国际护照（仅含机读区） / 00000001003 / COUNTRY_CODE
• 国际护照（含机读区和视读区）/ 00000001006 / COUNTRY_CODE

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{

"resultCode": "PROCESSING",

"resultStatus": "S",

"resultMessage": "It is still under processing"

}

transactionId

String

是

事务ID。

"G000000005FID2020030400000000000157****"

字段名称

数据类型

必须返回

描述

示例值

resultCode

String

是

结果码。

• INVALID_ARGUMENT：输入参数无效。

• bizId为null或空字符串。
• docType为null或无效。
• frontPageImage或backPageImage为空，或编码格式不正确。

• PROCESSING：正在处理中。
• SYSTEM_ERROR：其他内部错误。

"PROCESSING"

resultStatus

String

是

结果状态。

"S"

resultMessage

String

是

结果信息。

"It is still under processing"