ZOLOZZOLOZDOCS

checkresult

概览

  • API URL：/api/v1/zoloz/nfc/checkresult
  • API 描述：该接口用于获取NFC身份识别服务的运行状态和相关的识别结果，包括证件详细信息、人脸详细信息等。

说明：该接口支持重复调用，即符合幂等性。当获取到身份识别结果后，请勿过度重复调用该接口，以免导致流量激增触发限流影响其他调用的正常使用。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

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

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

"2017839040588699"

transactionId

String

64

是

-

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

"G000000005FID20200304000000000001570702"

isReturnImage

String

1

否

N

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

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

"Y"

返回参数

说明：当result.resultStatus的值为S时，才返回nfcResult、extBasicInfo、extFaceInfo和extIdInfo字段。

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{        

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

nfcResult

String

否

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

  • Success：身份识别服务运行成功。
  • 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身份识别服务中用户取消的详细信息。

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

无

ExtBasicInfo字段说明

说明：当证件识别成功时，才返回certType、certNo和certName字段。

字段名称

数据类型

必须返回

描述

示例值

certType

String

否

证件类型。

"00000001003"

certNo

String

否

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

"E40431234"

certName

String

否

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

"SAN ZHANG"

ExtFaceInfo字段说明

字段名称

数据类型

必须返回

描述

示例值

faceImg

String

否

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

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

"/9j/4AAQSkZJRgABAQAAA..."

ExtIdInfo字段说明

字段名称

数据类型

必须返回

描述

示例值

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

PersonInfoResult字段说明

00000001003（护照）

字段名称

数据类型

描述

示例值

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"

00860000011（大陆居民往来港澳通行证）

字段名称

数据类型

描述

示例值

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"

09640000001（伊拉克身份证）

字段名称

数据类型

描述

示例值

FULL_NAME_N

String

全名（阿拉伯语）

"لؤي"

ID_NUMBER

String

证件号码

"AL85819**"

DATE_OF_BIRTH

String

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

"891028"

DATE_OF_EXPIRY

String

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

"330419"

处理结果

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

  • 当result.resultCode的值为SUCCESS时，表示调用ZOLOZ NFC Reader checkresult API成功，并返回身份识别服务的处理结果。
  • 当result.resultCode的值非SUCCESS时，表示调用ZOLOZ NFC Reader checkresult API失败。请检查错误码获取有关该错误的更多信息，并分析导致该错误的原因。

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

NFC Reader checkresult API的结果码见下表。

结果码

结果状态

描述

SUCCESS

S

API调用成功。

INVALID_ARGUMENT

F

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

SYSTEM_ERROR

F

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

代码示例

请求示例

商户服务端发送的请求代码示例。

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G000000005FID20200304000000000001570702",
    "isReturnImage": "Y"
}

返回示例

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

copy
{
    "result":{
        "resultStatus":"S",
        "resultCode":"SUCCESS",
        "resultMessage":"Success"
    },
    "extRiskInfo":{

    },
    "nfcResult":"Success",
    "extFaceInfo":{
        "faceImg":"/9j/4AAQSkZJRgABAQAAA..."
    },
    "extBasicInfo":{
        "certNo":"E40431234",
        "certType":"00000001003",
        "certName":"SAN ZHANG"
    },
    "extCancelInfo":{

    },
    "extIdInfo":{
        "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
    }
}