Add Item

2026-05-28 01:46

重要说明：

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

概览

API URL：/api/v1/zoloz/blacklist/additem
API 描述：该接口用于向黑名单中添加一条记录。每个商户最多可存储10000条人脸黑名单记录。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。	"2017839040588699"
listId	String	32	否	默认黑名单	目标黑名单的名单ID。说明：如果`listId`为空，ZOLOZ会将该记录添加到默认黑名单中。
itemType	String	8	是	-	要添加的记录的类型。取值： `FACE`：人脸黑名单。当itemType为`FACE`时，可通过sourceTransactionId或base64ImageContent添加记录。 `DEVICE`：设备黑名单。当itemType为`DEVICE`时，可通过sourceTransactionId或deviceId添加记录。 `CERT`：证件黑名单。当itemType为`CERT`时，可通过sourceTransactionId或docType+docNumber添加记录。	"FACE"
base64ImageContent	String	5MB	否	null	当itemType为`FACE`时，指定要添加的人脸图片。说明：人脸图片应为JPEG格式。人脸图片要求质量佳，且面部特征可见。	"/9j/4Axxxxxxxx"
deviceId	String	128	否	null	当itemType为`DEVICE`时，指定要添加的设备ID。设备ID必须通过ZOLOZ SDK采集，否则可能会导致查询失败。
docType	String	16	否	null	当itemType为`CERT`时，指定要添加的证件的类型。查看支持的证件类型，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。
docNumber	String	32	否	null	当itemType为`CERT`时，指定要添加的证件的号码。
sourceTransactionId	String	64	否	null	指定该记录的来源。如果该记录是从ZOLOZ的eKYC历史记录中选取，则建议使用eKYC的transactionId。	"G1647337311928"
description	String	64	否	null	描述信息。

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode": "BLACKLIST_IMAGE_DENIED", "resultMessage": "Similar image(s) found in existing blacklist.", "resultStatus": "F" }
itemId	String	否	黑名单记录ID。当记录添加成功时，才返回该字段。	\"86451b883c80372a1ccc85dc2fdae2cd\",\"itemType\":\"FACE\"
relatedItems	List<String>	否	如果因为记录重复导致黑名单添加失败，则返回重复的黑名单记录。	[ "{\"itemId\":\"86451b883c80372a1ccc85dc2fdae2cd\",\"itemType\":\"FACE\"}" ]

处理结果

API通用结果码

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

API特有结果码

Blacklists additem API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API调用成功。
INVALID_ARGUMENT	F	输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。
BLACKLIST_LIST_NOT_FOUND	F	目标黑名单不存在。
BLACKLIST_IMAGE_DENIED	F	仅当itemType为`FACE`时适用。当传入的图片被拒绝时会返回该错误信息。有关错误详情，请查看返回的resultMessage。
SYSTEM_ERROR	F	其他内部错误。有关错误详情，请查看返回的resultMessage。

代码示例

请求示例

该示例将一张人脸图片添加到默认的人脸黑名单中。

copy
{
  "bizId":"2017839040588699",
  "itemType":"FACE",
  "base64ImageContent":"/9j/4Axxxxxxxx",
  "sourceTransactionId":"G1647337311928"
}

返回示例

当eKYC流程中采集到的人脸已被列入黑名单时，eKYC将返回以下响应示例。

copy
{
  "result":{
    "resultCode":"BLACKLIST_IMAGE_DENIED",
    "resultMessage":"Similar image(s) found in existing blacklist.",
    "resultStatus":"F"
  },
  "relatedItems":[
    "{\"itemId\":\"86451b883c80372a1ccc85dc2fdae2cd\",\"itemType\":\"FACE\"}"
  ]  
}