checkresult

2024-12-17 00:53

概览

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

否

从证件芯片里读取的人脸信息，通常为JPEG2000格式。

说明：当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"
EXPIRY_DATE	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
    }
}