Add Item

概览

  • API URL:/api/v1/zoloz/blacklist/additem
  • API 描述:该接口用于向黑名单中添加一条记录。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

-

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

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

"2017839040588699"

listId

String

32

默认黑名单

标黑名单的名单ID。

说明:如果参数值为空,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\"}"
  ]  
}