字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

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

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

"2017839040588699"

transactionId

String

64

是

-

事务ID，由ZOLOZ NFC initialize API的响应消息返回。

"G000000005FID20200304000000000001570702"

isReturnImage

String

1

否

N

是否在响应中返回图片数据。取值：

• Y：在响应中返回图片数据。
• N：不在响应中返回图片数据。

"Y"

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

nfcResult

String

否

标识整个身份识别服务进程的运行状态。

• Success：身份识别服务运行成功。
• Pending：NFC读取过程已完成，但一致性检查结果待定，需要人工审核。
• Failure：身份识别失败。
• InProcess：正在身份识别中。
• VoidCancelled：用户取消了身份识别。
• VoidTimeout：身份识别超时。

"Success"

extBasicInfo

ExtBasicInfo

否

基本实名信息。

{

"certNo": "E40431234",

"certType": "00000001003",

"certName": "SAN ZHANG"

}

extFaceInfo

ExtFaceInfo

否

NFC身份识别服务中人脸的详细信息。

{

"faceImg": "/9j/4AAQSkZJRgABAQAAA..."

}

extIdInfo

ExtIdInfo

否

NFC身份识别服务中证件的详细信息。

{

"frontPageImg": "/9j/4AAQSkZ...",

"personInfoResult": {

"ID_NUMBER": "E40431234",

"SEX": "M",

"LAST_NAME": "ZHANG",

"DATE_OF_BIRTH": "891028",

"FIRST_NAME": "SAN",

"EXPIRY_DATE": "330419",

"COUNTRY_CODE": "CHN"

},

"docEdition": 1

}

extRiskInfo

ExtRiskInfo

否

NFC身份识别服务中风险控制的详细信息。

说明：该字段为过期字段，即将删除，无数据返回，请忽略。

无

extCancelInfo

ExtCancelInfo

否

NFC身份识别服务中用户取消的详细信息。

说明：该字段为过期字段，即将删除，无数据返回，请忽略。

无

extVerificationInfo

ExtVerificationInfo

否

第三方实证服务返回的额外文件信息。

参考返回示例

consistencyCheckResults

List<ConsistencyCheckResult>

否

可选。初始化请求中指定的一致性检查的详细结果。

只有在初始化的 nfcConfig 中指定了 consistencyCheck 时才返回此字段。请参阅以下 ConsistencyCheckResult 表。

参考返回示例

字段名称

数据类型

必须返回

描述

示例值

certType

String

否

证件类型。

"00000001003"

certNo

String

否

证件号码，即从证件中识别到的证件号码。

"E40431234"

certName

String

否

姓名，即从证件中识别到的姓名。

"SAN ZHANG"

字段名称

数据类型

必须返回

描述

示例值

faceImg

String

否

从证件芯片里读取的人脸信息，返回的图片格式为JPG。

说明：仅当isReturnImage为Y，且证件识别成功时才返回该字段。

"/9j/4AAQSkZJRgABAQAAA..."

字段名称

数据类型

必须返回

描述

示例值

frontPageImg

String

否

采用Base64编码的证件正面照，返回的图片格式为JPG。

说明：仅当isReturnImage为Y，且证件识别成功时才返回该字段。

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

personInfoResult

Map

否

NFC存储的身份相关信息，不同证件返回的身份信息有所不同，详细请参见PersonInfoResult。

说明：当证件识别成功时，才返回该字段。

{

"ID_NUMBER": "E40431234",

"SEX": "M",

"LAST_NAME": "ZHANG",

"DATE_OF_BIRTH": "891028",

"FIRST_NAME": "SAN",

"EXPIRY_DATE": "330419",

"COUNTRY_CODE": "CHN"

}

docEdition

Integer

否

身份证件的版本，默认为1。

1

字段名称

数据类型

描述

示例值

FIRST_NAME

String

名

"SAN"

LAST_NAME

String

姓

"ZHANG"

SEX

String

性别

"M"

ID_NUMBER

String

证件号码

"E40431234"

DATE_OF_BIRTH

String

出生日期，日期格式为yyMMdd。

"891028"

EXPIRY_DATE

String

到期日期，日期格式为yyMMdd。

"330419"

COUNTRY_CODE

String

国家代码

"CHN"

字段名称

数据类型

描述

示例值

NAME

String

英文姓名

"ZHANG SAN"

NAME_CN

String

中文姓名

"张三"

SEX

String

性别

"M"

ID_NUMBER

String

证件号码

"E40431234"

DATE_OF_BIRTH

String

出生日期，日期格式为yyMMdd。

"891028"

DATE_OF_EXPIRY

String

到期日期，日期格式为yyMMdd。

"330419"

字段名称

数据类型

描述

示例值

FULL_NAME_N

String

全名（阿拉伯语）

"لؤي"

ID_NUMBER

String

证件号码

"AL85819**"

DATE_OF_BIRTH

String

出生日期，日期格式为yyMMdd。

"891028"

DATE_OF_EXPIRY

String

到期日期，日期格式为yyMMdd。

"330419"

字段名称

数据类型

描述

示例值

NAME_CN

String

中文姓名

"张三"

NAME

String

英文姓名

"ZHANG SAN"

ID_NUMBER

String

证件号码

"4****************2"

SEX

String

性别

"男"

RACE

String

民族

"汉"

PLACE_OF_PERMANENT

String

住址

"长沙市**********************"

DATE_OF_BIRTH

String

出生日期，日期格式为yyyyMMdd。

"19880302"

DATE_OF_ISSUE

String

签发日期，日期格式为yyyyMMdd。

"20170502"

DATE_OF_EXPIRY

String

到期日期，日期格式为yyyyMMdd。

"20370502"

OTHER_ID_NUMBER

String

其他证件号码

"C668668"

ISSUE_TIMES

String

签发次数

"01"

COUNTRY_CODE

String

国家或地区代码

"CHN"

ISSUE_ORG_CODE

String

当次申请受理机关代码

"1500"

ID_VERSION

String

证件版本号

"01"

ISSUE_ORGANIZATION

String

签发机关

"********分局"

字段名称

数据类型

描述

示例值

NAME_CN

String

中文姓名

"张三"

NAME

String

英文姓名

"ZHANG SAN"

RACE

String

民族

"汉"

ISSUE_ORGANIZATION

String

签发机关

"********分局"

DATE_OF_ISSUE

String

签发日期，日期格式为yyyyMMdd。

"20170502"

PLACE_OF_PERMANENT

String

住址

"长沙市**********************"

OTHER_ID_NUMBER

String

其他证件号码

"C668668"

ISSUE_TIMES

String

签发次数

"01"

COUNTRY_CODE

String

国家或地区代码

"CHN"

ISSUE_ORG_CODE

String

当次申请受理机关代码

"1500"

ID_VERSION

String

证件版本号

"01"

字段名称

数据类型

必须返回

描述

示例值

idVoucherCredential

String

否

第三方实证服务返回的电子证件安全凭证（Base64编码的PDF文件）。

说明：仅当needVoucherCredential为Y时才返回该字段。

"JVBERi0xLjQKJeLjz9MKMyAwIG..."

idSuperviseCredential

String

否

第三方实证服务返回的监督凭证（Base64编码的PDF文件）。

说明：仅当needSuperviseCredential为Y时才返回该字段。

"JVBERi0xLjcKJeLjz9MKMTEgMC..."

idCompositeFrontImg

String

否

第三方实证服务返回的证件正面合成图片（Base64编码图片）。

说明：仅当needCompositeIdImage为Y时才返回该字段。

"/9j/4AAQSkZJRgABAgAAAQABA..."

idCompositeBackImg

String

否

第三方实证服务返回的证件背面合成图片（Base64编码图片）。

说明：仅当needCompositeIdImage为Y时才返回该字段。

"/9j/4AAQSkZJRgABAgAAAQABAA..."

字段名称

数据类型

必须返回

取值范围

描述

type

String

否

commonConsistencyCheck / documentChipConsistencyCheck / faceChipConsistencyCheck

一致性检查的类型。

status

String

否

PASS / PENDING / FAIL

一致性检查结果。

details

Object

否

reason / matchedFields / mismatchedFields / score / samePerson / suggestion

一致性检查结果的详细信息。返回的字段因类型和状态而异。

类型

状态

原因

描述

commonConsistencyCheck

FAIL

COMMON_VERSION_UNSUPPORTED

客户端 NFC software 版本早于 6，因此不支持检查。

documentChipConsistencyCheck

PENDING

DOCUMENT_CHIP_MISMATCH

打印的文档信息与一个或多个比较字段的芯片信息不匹配。

documentChipConsistencyCheck

FAIL

DOCUMENT_CHIP_VERSION_UNSUPPORTED

客户端 NFC software 版本早于 6，因此不支持检查。

documentChipConsistencyCheck

FAIL

DOCUMENT_CHIP_PRINTED_MISSING

打印的文档信息缺失，因此无法进行检查。

documentChipConsistencyCheck

FAIL

DOCUMENT_CHIP_PERSON_INFO_MISSING

芯片个人信息缺失，因此无法进行检查。

faceChipConsistencyCheck

FAIL

FACE_CHIP_VERSION_UNSUPPORTED

客户端 NFC software 版本早于 6，因此不支持检查。

faceChipConsistencyCheck

PENDING

FACE_CHIP_REVIEW

人脸相似度评分处于不确定范围，需要人工审查。

faceChipConsistencyCheck

FAIL

FACE_CHIP_MISMATCH

比对的两张脸不属于同一个人。

faceChipConsistencyCheck

FAIL

FACE_IMAGE_MISSING

面部图像缺失，因此无法进行检查。

结果码

结果状态

描述

SUCCESS

S

API调用成功。

INVALID_ARGUMENT

F

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

SYSTEM_ERROR

F

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