Get Item

2026-05-28 01:46

重要说明：

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

概览

API URL：/api/v1/zoloz/blacklist/getitem
API 描述：该接口用于获取已有黑名单记录的详细信息。

请求参数

字段名称	数据类型	最大长度	是否必填	描述	示例值
bizId	String	32	是	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。	"2017839040588699"
itemType	String	8	是	要查询的黑名单记录的类型。取值如下： `FACE`：人脸黑名单。 `DEVICE`：设备黑名单。 `CERT`：证件黑名单。	"FACE"
itemId	String	64	是	要查询的黑名单记录ID。	"86451b883c80372"

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode":"SUCCESS", "resultMessage":"Success", "resultStatus":"S" }
itemId	String	否	黑名单记录ID。当成功获取到黑名单记录时，才返回该字段。	"86451b883c80372"
itemType	String	否	黑名单记录的类型。当成功获取到黑名单记录时，才返回该字段。	"FACE"
itemStatus	String	否	黑名单记录的状态。当成功获取到黑名单记录时，才返回该字段。 `ACTIVE`：有效 `DELETED`：已删除	"ACTIVE"
listId	String	否	目标黑名单的名单ID。当成功获取到黑名单记录时，才返回该字段。	"1"
base64ImageContent	String	否	人脸图片。当成功获取到黑名单记录，且itemType为`FACE`时才返回该字段。	"/9j/4AAxxxxxxx"
deviceId	String	否	设备ID。当成功获取到黑名单记录，且itemType为`DEVICE`时才返回该字段。
docType	String	否	证件类型。当成功获取到黑名单记录，且itemType为`CERT`时才返回该字段。
docNumber	String	否	证件号码。当成功获取到黑名单记录，且itemType为`CERT`时才返回该字段。
sourceTransactionId	String	否	黑名单记录的来源。当成功获取到黑名单记录时，才返回该字段。	"1646971102303"
gmtCreated	Date	否	首次创建黑名单记录的时间。当成功获取到黑名单记录时，才返回该字段。	1646971104006
gmtModified	Date	否	最近修改黑名单记录的时间。当成功获取到黑名单记录时，才返回该字段。	1646971104006

处理结果

API通用结果码

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

API特有结果码

Blacklists getitem API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API调用成功。
INVALID_ARGUMENT	F	输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。
BLACKLIST_ITEM_NOT_FOUND	F	请求的黑名单记录不存在。
SYSTEM_ERROR	F	其他内部错误。有关错误详情，请查看返回的resultMessage。

代码示例

请求示例

copy
{
  "bizId": "2017839040588699",
  "itemId": "86451b883c80372",
  "itemType": "FACE"
}

返回示例

找到目标黑名单时的代码示例

copy
{
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"Success",
    "resultStatus":"S"
  },
  "itemId":"86451b883c80372",
  "itemStatus":"ACTIVE",
  "itemType":"FACE",
  "listId":"1",
  "base64ImageContent":"/9j/4AAxxxxxxx",
  "sourceTransactionId":"1646971102303",
  "gmtCreated":1646971104006,
  "gmtModified":1646971104006
}

找不到目标黑名单时的代码示例

copy
{
  "result":{
    "resultCode":"BLACKLIST_ITEM_NOT_FOUND",
    "resultMessage":"item 86451b883c80372 of type FACE is not found.",
    "resultStatus":"F"
  }
}