Blacklist Scan

2026-06-25 06:12

重要说明：

所有请求及返回参数均严格以官网API文档为准。
API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。

概览

API URL：/api/v1a/zoloz/blacklist/scan
API 描述：该接口用于扫描指定用户是否命中黑名单。支持同时扫描人脸（FACE）、证件（CERT）、设备（DEVICE）三种类型，并支持通过eKYC历史记录的transactionId自动反查扫描数据。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ不校验该字段的唯一性。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。	"2017839040588699"
userId	String	64	否	null	商户的用户ID或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。建议对`userId`字段的值进行预脱敏，例如进行哈希处理。	"user123456"
itemTypes	List<String>	-	否	["FACE","CERT","DEVICE"]	要扫描的黑名单类型列表，支持传入一种或多种类型。取值： `FACE`：人脸黑名单。 `CERT`：证件黑名单。 `DEVICE`：设备黑名单。说明：不传或传空数组时，默认扫描所有类型。	["FACE", "CERT"]
sourceTransactionId	String	64	否	null	指定扫描数据的来源。可传入当前调用商户的ZOLOZ eKYC历史记录ID（即`transactionId`），传入后系统自动从产品记录中反查人脸图片、证件信息、设备ID。 `sourceTransactionId`与直传参数（`base64ImageContent`、`docType`/`docNumber`、`deviceId`）可二选一或同时使用，详见数据来源与传参规则。	"G1647337311928"
base64ImageContent	String	5MB	否	null	当`itemTypes`包含`FACE`时，指定要扫描的人脸图片。图片需满足以下要求：编码格式：Base64编码字符串文件格式：JPEG格式图片质量：质量佳且面部特征可见说明：当同时传入`sourceTransactionId`且反查到人脸图片时，以反查结果为准。	"/9j/4Axxxxxxxx"
deviceId	String	128	否	null	当`itemTypes`包含`DEVICE`时，指定要扫描的设备ID。说明：设备ID必须通过ZOLOZ SDK采集，否则可能导致查询失败。当同时传入`sourceTransactionId`且反查到`deviceId`时，以反查结果为准。	"device_abc123"
docType	String	16	否	null	当`itemTypes`包含`CERT`时，指定要扫描的证件类型。支持的证件类型，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。说明：当同时传入`sourceTransactionId`且反查到`docType`时，以反查结果为准。	"NATIONAL_ID"
docNumber	String	32	否	null	当`itemTypes`包含`CERT`时，指定要扫描的证件号码。说明：当同时传入`sourceTransactionId`且反查到`docNumber`时，以反查结果为准。	"330100xxxx1234"

数据来源与传参规则

数据来源说明

每种扫描类型均有两种数据来源，反查与直传。两者可二选一或同时使用，反查结果优先级高于直传参数。

扫描类型	反查方式（优先级高）	直传方式（优先级低）
FACE	传入`sourceTransactionId`，自动反查人脸图片	传入`base64ImageContent`
CERT	传入`sourceTransactionId`，自动反查证件信息（`docType`+`docNumber`）	传入`docType`+`docNumber`
DEVICE	传入`sourceTransactionId`，自动反查设备ID	传入`deviceId`

传参方式与校验规则

根据传参方式的不同，处理逻辑和校验规则有所差异。

传参方式	传参要求	处理逻辑	校验规则	反查业务要求
反查+直传	同时传入`sourceTransactionId`和直传参数	优先使用反查结果；反查失败，自动使用直传参数扫描。	不校验	业务数据所属商户必须与当前调用商户一致
仅使用反查	仅传`sourceTransactionId`，不传直传参数	仅依赖反查数据	严格校验业务数据状态，需同时满足以下条件，否则返回`INVALID_ARGUMENT`。数据未被隐私政策删除业务状态为`Success`、`Failure`或`Pending`	业务数据所属商户必须与当前调用商户一致
仅使用直传	仅传直传参数，不传`sourceTransactionId`	直接使用直传参数扫描	不校验	无

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }
transactionId	String	否	本次扫描生成的唯一交易ID，可用于后续查询Case数据。仅当API调用成功时返回。	"G1647337312000"
isScan	String	否	是否执行了扫描。仅当API调用成功时返回。 `Y`：已执行扫描，至少完成了一种类型的黑名单扫描。 `N`：未执行扫描，当前商户无黑名单数据。	"Y"
blacklistResult	String	否	黑名单扫描结果。仅当`isScan`为`Y`时返回。 `Success`：未命中黑名单 `Failure`：命中黑名单	"Failure"
blacklistDetails	Map<String, List<ScanItemResult>>	否	命中详情，按扫描类型分组，结构定义见下方BlacklistDetails。仅当`blacklistResult`为`Failure`时返回。说明：当命中任意一种扫描类型时，所有请求的扫描类型都会作为Key在结果中返回。命中的类型：返回详情列表。未命中或跳过的类型：返回空数组。	参考返回示例
scannedItemTypes	List<String>	否	实际执行扫描的类型列表。仅当`isScan`为`Y`时返回。	["FACE", "CERT"]

BlacklistDetails结构

字段名称	数据类型	必须返回	描述	示例值
listId	String	是	命中的黑名单ID。	"default_list"
relatedTransactionId	String	否	录入黑名单时的源`transactionId`。	"G1647337311928"
itemId	String	是	命中的黑名单条目ID。	"86451b883c80372a1ccc85dc2fdae2cd"
similarityScore	Double	否	人脸相似度分数，分值越高越相似。仅当扫描类型为`FACE`且命中时返回。	95.6

处理结果

API通用结果码

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

API特有结果码

Blacklist Scan API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API调用成功。
INVALID_ARGUMENT	F	请求参数无效，请根据返回的`resultMessage`定位具体问题。常见原因包括：通用参数错误： `bizId`为空或类型不是String `itemTypes`类型不是Array，或包含不支持的黑名单类型所有扫描类型均缺少必要参数反查参数错误： `sourceTransactionId`对应的业务数据因隐私政策已被删除（仅当使用`sourceTransactionId`且未传直传参数时校验） `sourceTransactionId`对应的业务状态不合法，仅允许`Success`、`Failure`、`Pending`（仅当使用`sourceTransactionId`且未传直传参数时校验） `sourceTransactionId`对应的业务数据所属商户与当前调用商户不一致
BLACKLIST_LIST_NOT_FOUND	F	目标黑名单不存在。
BLACKLIST_IMAGE_DENIED	F	仅当`itemTypes`包含`FACE`时适用。当传入的图片格式不合法、图片质量不满足要求或图片大小超限时会返回该错误。有关错误详情，请查看返回的`resultMessage`。
SYSTEM_ERROR	F	系统内部错误。有关错误详情，请查看返回的`resultMessage`。

代码示例

请求示例

示例1：仅使用反查（sourceTransactionId）扫描所有类型

该示例通过eKYC的transactionId自动反查人脸、证件及设备信息，扫描所有类型的黑名单。

copy
{
    "bizId": "2017839040588699", 
    "sourceTransactionId": "G1647337311928"
}

示例2：仅使用直传扫描指定类型

该示例直接传入人脸图片和证件信息，仅扫描FACE和CERT类型的黑名单。

copy
{
    "bizId": "2017839040588699", 
    "userId": "user123456", 
    "itemTypes": [
        "FACE", 
        "CERT"
    ], 
    "base64ImageContent": "/9j/4Axxxxxxxx", 
    "docType": "NATIONAL_ID", 
    "docNumber": "330100xxxx1234"
}

示例3：混合模式（反查+直传）

该示例通过sourceTransactionId反查人脸、证件及设备信息，同时传入deviceId作为设备ID的备用。扫描时优先使用反查得到的数据，若设备ID反查失败，则自动使用直传参数deviceId扫描。

copy
{
    "bizId": "2017839040588699", 
    "sourceTransactionId": "G1647337311928", 
    "itemTypes": [
        "FACE", 
        "CERT", 
        "DEVICE"
    ], 
    "deviceId": "device_abc123"
}

返回示例

示例1：命中黑名单

命中FACE类型的黑名单，CERT和DEVICE类型均未命中。

copy
{
    "result": {
        "resultCode": "SUCCESS", 
        "resultMessage": "Success", 
        "resultStatus": "S"
    }, 
    "transactionId": "G1647337312000", 
    "isScan": "Y", 
    "blacklistResult": "Failure", 
    "scannedItemTypes": [
        "FACE", 
        "CERT", 
        "DEVICE"
    ], 
    "blacklistDetails": {
        "FACE": [
            {
                "listId": "default_list", 
                "relatedTransactionId": "G1647337311928", 
                "itemId": "86451b883c80372a1ccc85dc2fdae2cd", 
                "similarityScore": 95.6
            }
        ], 
        "CERT": [ ], 
        "DEVICE": [ ]
    }
}

示例2：未命中黑名单

copy
{
    "result": {
        "resultCode": "SUCCESS", 
        "resultMessage": "Success", 
        "resultStatus": "S"
    }, 
    "transactionId": "G1647337312001", 
    "isScan": "Y", 
    "blacklistResult": "Success", 
    "scannedItemTypes": [
        "FACE", 
        "CERT"
    ]
}

示例3：未执行扫描（商户无黑名单数据）

copy
{
    "result": {
        "resultCode": "SUCCESS", 
        "resultMessage": "Success", 
        "resultStatus": "S"
    }, 
    "transactionId": "G1647337312002", 
    "isScan": "N"
}

示例4：数据因隐私政策被删除导致反查失败

当仅通过sourceTransactionId反查数据，但该历史记录因隐私政策已被删除时，系统返回INVALID_ARGUMENT错误。

copy
{
    "result": {
        "resultCode": "INVALID_ARGUMENT", 
        "resultMessage": "The case has been deleted for privacy reasons", 
        "resultStatus": "F"
    }
}

示例5：bizId缺失

copy
{
    "result": {
        "resultCode": "INVALID_ARGUMENT", 
        "resultMessage": "bizId is mandatory", 
        "resultStatus": "F"
    }
}