checkresult
入口：/api/v1/zoloz/realid/checkresult
ZOLOZ Real ID checkresult API 用于请求身份验证进程运行状态和相关的验证结果，包括证件验证结果及详细信息、人脸验证结果、风险控制结果等。该 API 符合幂等性。
结构
请求参数
字段名称 | 数据类型 | 最大长度 | 描述 |
bizId | String | 32 | 必填项。出于追踪目的的业务 ID，用来唯一标识某一业务。例如，商户业务相关数据库中的序列 ID。 说明：ZOLOZ 服务器不检查该字段的值是否唯一。因此为了更便捷地追踪业务，建议开启商户服务器，并确保业务 ID 的唯一性。 |
transactionId | String | 64 | 必填项。事务 ID，由 initialize API 响应消息返回。 |
isReturnImage | String | 1 | 可选项。是否在响应中返回图像数据。枚举值如下：
默认情况下是 N。 |
响应参数
字段名称 | 数据类型 | 描述 |
result | 必填项。包含了 API 请求结果的信息，例如结果状态和错误码。 | |
ekycResult | String | 可选项。标识整个身份验证进程的运行状态。该字段仅在 result.resultSatus 字段的值为 S 时可用。枚举值及其含义如下：
|
extBasicInfo | ExtBasicInfo | 可选项。基本实名信息。该字段仅在 result.resultStatus 字段的值设置为 S 时可用。有关详细信息，请参见 ExtBasicInfo。 |
extFaceInfo | ExtFaceInfo | 详细的 eKYC 申请人脸信息。仅当 result.resultStatus 为 S 时可用。请参阅下表了解更多信息。 可选项。有关人脸验证的详细信息。该字段仅在 result.resultStatus 字段的值设置为 S 时可用。有关详细信息，请参见 ExtFaceInfo。 |
extIdInfo | ExtIdInfo | 可选项。有关证件验证的详细信息。此字段仅在 result.resultStatus 字段的值设置为 S 时可用。有关详细信息，请参见 ExtIdInfo。 |
extRiskInfo | ExtRiskInfo | 可选项。有关风险控制的详细信息。此字段仅在 result.resultStatus 字段的值设置为 S 时可用。有关详细信息，请参见 ExtRiskInfo。 |
结果
结果处理逻辑
根据请求结果，执行下一步操作。有关详细信息，请参见以下内容：
- 当 result.resultCode 的值为
SUCCESS时，表示调用 ZOLOZ Real ID checkresult API 成功，并返回了证件验证、人脸验证或以及风控处理结果。 - 当 result.resultCode 的值非
SUCCESS时，表示调用 ZOLOZ Real ID checkresult API 失败。请检查错误码以获取有关该错误的更多信息，并分析可能导致该错误的原因。
场景错误码
有关常见错误码的完整列表，请参见 错误处理 中常见错误码部分。
API 结果码
Connect checkresult API 的结果码见下表。
结果码 | 结果状态 | 描述 |
SUCCESS | S | API 调用成功。 |
INVALID_ARGUMENT | F | 输入参数无效。关于无效参数的详细信息，请查看结果消息或相关日志。 |
SYSTEM_ERROR | F | 其他内部错误。关于错误详情，请查看返回的结果消息和相关日志。 |
代码示例
请求示例
以下是商家服务器发送的请求代码示例。
{
"bizId": "2017839040588699",
"transactionId": "G000000005FID20200304000000000001570702",
"isReturnImage": "N"
}响应示例
以下是 ZOLOZ 服务器返回的响应代码示例。
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "Success",
"resultStatus": "S"
},
"ekycResult": "Pending",
"extBasicInfo": {
"certType": "08530000001",
"certNo": "A12345678",
"certName": "xxxxxx"
},
"extFaceInfo": {
"ekycResultFace": "Success",
"faceScore": 88.31415926535897,
"faceImg": "/9j/4AA..[omitted]..PxA=",
"faceQuality": 97.61517973846627,
"faceLivenessResult": "Success"
},
"extIdInfo": {
"ekycResultDoc": "Pending",
"docEdition": 1,
"frontPageImg": "/9j/4AA..[omitted]..PxA=",
"backPageImg": "/9j/4AA..[omitted]..PxA=",
"ocrResult": {
...
},
"spoofResult": {
"TAMPER_CHECK": "Y",
"MATERIAL_CHECK": "Y",
"SCREEN_RECAPTURE_CHECK": "Y",
"OTHER_CHECK":,"Y"
},
"securityFeaturesResult": {
"LASER_IMAGE_1_SCORE":95,
"LASER_IMAGE_1_THRESHOLD":90,
"LASER_IMAGE_1_PASSED":"True",
"HOLOGRAM_SCORE":95,
"HOLOGRAM_THRESHOLD":90,
"HOLOGRAM_PASSED":"True",
"STEREO_LASER_PORTRAIT_SCORE":95,
"STEREO_LASER_PORTRAIT_THRESHOLD":90,
"STEREO_LASER_PORTRAIT_PASSED":"True",
"LASER_IMAGE_2_SCORE":95,
"LASER_IMAGE_2_THRESHOLD":90,
"LASER_IMAGE_2_PASSED":"True",
"OVERALL_SCORE":95,
"OVERALL_THRESHOLD":90,
"OVERALL_PASSED":"True"
},
"docErrorDetails": "BLUR"
},
"extRiskInfo": {
"ekycResultRisk": "Pending",
"strategyPassResult": "ID_NETWORK_HIGH_RISK",
"idNetworkDetails": "..."
},
"extCustomInfo": {
...
}
}更多信息
ExtBasicInfo
ExtBasicInfo 数据模型中字段的说明见下表。
字段名称 | 数据类型 | 描述 |
certType | String | 身份证件类型。 身份证件的类型。如果证件验证进程成功运行，则为必填项。 |
certNo | String | 身份证件号码。 从身份证件中识别到的 ID 号码。如果证件验证进程成功运行，则为必填项。 |
certName | String | 身份证件名称。 从身份证件中识别到的名称。如果证件验证进程成功运行，则为必填项。 |
ExtFaceInfo
ExtFaceInfo 数据模型中字段的说明见下表。
字段名称 | 数据类型 | 描述 |
ekycResultFace | String | 人脸验证进程的运行状态。枚举值及其含义如下：
如果人脸验证进程成功运行，则该字段为必填项。 |
faceScore | Double | 人脸对比分数，取值范围 0-100。该分数表示将活体人脸（自拍）与从身份证件中识别到的人脸进行比较的结果。如果人脸验证进程成功运行，则该字段为必填项。 |
faceImg | String | 人脸自拍像，采用 base64 编码。仅当请求中的 isReturnImage 字段值为 |
faceQuality | Double | 人脸自拍像的质量分数，取值范围 0-100。如果人脸验证进程成功运行，该字段为必填项。 |
faceLivenessResult | String | 人脸活跃度检查结果。使用人脸活跃度检查算法检查人脸自拍照是否为假脸攻击。如果检查结果不是假脸攻击，则返回 |
ExtIdInfo
ExtIdInfo 数据模型中字段的说明见下表。
字段名称 | 数据类型 | 描述 |
ekycResultDoc | String | 证件验证进程的运行状态。枚举值及其含义如下：
如果证件验证进程成功运行，则该字段为必填项。 |
docEdition | Integer | 身份证件的版本。例如，对于当前的 HKID，该字段的返回值为 1，而对于新的 HKID，该字段的返回值为 2。 如果证件验证进程成功运行，则该字段为必填项。 |
frontPageImg | String | 身份证件的正面照，base64 编码的格式。当请求中 isReturnImage 字段值为 |
backPageImg | String | 身份证件的背面照（如果有），base64 编码的格式。当请求中 isReturnImage 字段值为 |
ocrResult | Map | OCR 结果，结果中包含身份相关的信息。 当证件验证进程成功运行时，则该字段为必填项。由于身份证件的类型不同，识别出的身份信息集不同。更多信息请参见 支持的证件类型和返回的 OCR 结果。 |
spoofResult | Map | 可选项。欺诈检查结果，其中包含有关篡改、证件材料真实性和屏幕重新捕获等检查结果的信息。更多详细信息请参见 spoofResult。 |
securityFeaturesResult | Map | 可选项。身份证件安全特性的检测结果，例如身份证件上的激光图像。根据身份证件类型，检查身份证件中不同的安全特性。更多信息请参见 securityFeaturesResult。 |
docErrorDetails | String | 可选项。证件验证进程错误的详细信息。枚举值及其含义如下：
|
ExtRiskInfo
ExtRiskInfo 数据模型中字段的说明见下表。
字段名称 | 数据类型 | 描述 |
ekycResultRisk | String | 风控进程运行状态。枚举值及其含义如下：
|
strategyPassResult | String | 风险检查结果。当风控进程成功运行时，该字段为必填项。枚举值及其含义如下：
|
idNetworkDetails | String | 可选项。ID 网络输出的详细信息。仅当 strategyPassResult 字段返回为 ID_NETWORK_HIGH_RISK 时，该字段为必填项。 |
spoofResult
spoofResult 详细说明见下表。
字段名称 | 数据类型 | 描述 |
TAMPER_CHECK | String | 必填项。输入的身份证件是否通过篡改检查。
|
MATERIAL_CHECK | String | 必填项。身份证件的材料是否通过真实性检查。
|
SCREEN_RECAPTURE_CHECK | String | 必填项。身份证件是否通过屏幕重新捕获检查。
|
OTHER_CHECK | String | 必填项。其他检查项的结果，包括身份证明文件本身的安全特性检查和信息有效性检查。枚举值及其含义如下：
|
securityFeaturesResult
下表显示了针对不同身份证件检测到的安全特性，以及在 securityFeaturesResult 数据模型中返回的字段。为每个安全特性，均返回一个检查结果，包括分数、阈值和标识相应检查是否通过的标志。此外，还会返回整体检查结果。
目前安全功能检测仅支持 HKID，即Hong Kong Identity Card。（包括 Current HKID 和 New HKID）。
身份证件 | 证件类型 | 安全功能示例 | 字段及字段值示例 |
现时香港身份证 | 08520000001 |
图 1. 现时香港居民身份证 的示例图像 说明：示例图片来自 https://www.smartid.gov.hk/en/Development-of-Hong-Kong-Identity-Cards/index.html. | 如图 1 所示，对于当前的 HKID，通过光学可变墨水、多激光图像和 Kineprint 来检测安全特性。 以下列表显示了每个安全特性和总体检查结果的字段和值示例。
|
新香港身份证 | 08520000002 |
图 2. 新香港居民身份证的示例图像 说明：示例图片来自 https://www.smartid.gov.hk/en/Security-Features-of-New-Smart-Identity-Card/index.html | 如图 2 所示，对于新的香港身份证，安全特性包括激光图像 1、全息图、立体激光 (SLI) 肖像和激光图像 2。 以下列表显示了每个安全特性和总体检查结果的字段和值示例。
综上：
|
Version
发布日期 | 变更记录 |
2021.11.11 | 支持中国身份证。 |
2021.11.11 | 首次发布 |