ZOLOZZOLOZDOCS

verify

概览

  • API URL：/api/v1/zoloz/cnauthority/verify
  • API 描述：该接口用于将采集的人脸信息与中国大陆权威数据库中存储的信息进行比对，以验证用户身份的真实性，并为验证过程生成一个唯一的事务ID。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

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

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

"2017839040588699"

userId

String

64

否

null

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

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

"123456abcd"

sourceTransactionId

String

64

否

null

一个外部的引用ID，用于记录人脸图片的真实来源。

如果该人脸图片是从ZOLOZ的eKYC历史记录中选取，则建议使用eKYC的transactionId。

"G1647337311928"

base64ImageContent

String

1MB

是

-

采用Base64编码的人脸图片。

说明：

  • 人脸图片应为JPEG格式。
  • 人脸图片要求质量佳，且面部特征可见。

"/9j/4Axxxxxxxx"

idNo

String

32

是

-

用户的身份证号码。

"420502198012345000"

idName

String

16

是

-

用户身份证上的姓名。

"李四"

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{

   "resultCode": "AUTHORITY_INVALID_CERT_NO",  

   "resultMessage": "authority invalid cert no.",  

   "resultStatus": "F"

}

transactionId

String

否

ZOLOZ服务器为身份验证进程生成的唯一事务ID。

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

  • 请求参数非法，例如入参格式错误或缺失必传参数。
  • 请求未能成功到达服务器，例如网络问题或网关故障。
  • 系统限流导致请求被拒绝。

"G1334455667788XXX"

处理结果

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

  • 当result.resultStatus的值为S时，表示调用ZOLOZ CN Authority verify API成功，并返回唯一的事务ID。
  • 当result.resultStatus的值为F时，表示调用ZOLOZ CN Authority verify API失败。请检查错误码获取有关该错误的更多信息，并分析导致该错误的原因。

API通用结果码

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

API特有结果码

CN Authority verify API的结果码见下表。

结果码

结果状态

描述

SUCCESS

S

API调用成功且用户身份信息验证通过。

AUTHORITY_INACTIVE

F

商户未开通产品

AUTHORITY_INVALID_CERT_NAME

F

证件上的姓名无效

AUTHORITY_INVALID_CERT_AGE

F

无效的证件（未满14周岁的中国大陆用户无法使用本产品）

AUTHORITY_INVALID_CERT_NO

F

证件号码无效

AUTHORITY_INVALID_FACE_IMG

F

人脸图片无效

AUTHORITY_PROCESSING

F

仍在处理中

AUTHORITY_EXTRACT_FACE_FAIL

F

提取人脸失败

AUTHORITY_UNABLE_GET_IMAGE

F

无法获取图片

AUTHORITY_NOT_SAME_PERSON

F

不是同一个人

SYSTEM_ERROR

F

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

代码示例

请求示例

copy
{
    "bizId": "2017839040588699", 
    "userId": "123456abcd", 
    "idNo": "420502198012345000", 
    "idName": "李四", 
    "base64ImageContent": "/9j/4Axxxxxxxx", 
    "sourceTransactionId": "G1647337311928"
}

返回示例

当证件号码无效时将返回以下响应代码示例。

copy
{
    "result": {
        "resultCode": "AUTHORITY_INVALID_CERT_NO", 
        "resultMessage": "authority invalid cert no.", 
        "resultStatus": "F"
    }, 
    "transactionId": "G1334455667788XXX"
}