名单 API：黑名单与白名单管理

Lists API 可让您管理应用中不同类型的名单。系统黑名单会在验证和交易筛查期间自动创建并进行检查。您还可以创建白名单和自定义名单，用于工作流条件。

概念

类型	描述
黑名单	由系统创建，每种条目类型一个。黑名单中的项目会在验证或交易筛查期间自动导致拒绝。
白名单	由用户创建。用于工作流条件，并可抑制可信匹配项的重复/复用操作。
自定义	由用户创建。灵活的名单，可用于工作流分支、监控规则或人工审核。

条目类型

条目类型	检查时机	命中后
`face`	活体检测	会话已拒绝
`document`	身份证件验证（OCR）	会话已拒绝
`phone`	电话验证	会话已拒绝
`email`	邮箱验证	会话已拒绝
`ip_address`	设备与 IP 分析（支持 CIDR 范围）	会话已拒绝
`device_fingerprint`	设备与 IP 分析	会话已拒绝
`wallet_address`	交易筛查	交易已拒绝
`bank_account`	交易筛查	交易已拒绝
`user`	交易筛查	用户已被拦截
`business`	交易筛查	企业已被拦截
`country`	工作流条件	可配置
`key`	自定义用途	可配置

白名单

白名单不会覆盖黑名单或真实性检查。白名单只会抑制同一条目类型的重复/复用操作。例如，人脸白名单中的人脸可以跳过 DUPLICATED_FACE 操作，IP 白名单中的 IP 可以跳过 DUPLICATED_IP_ADDRESS 操作，设备指纹白名单中的设备指纹可以跳过 DUPLICATED_DEVICE_FINGERPRINT 操作。Didit 仍会记录一条提示性的白名单警告，方便您审计重复操作未执行的原因。

系统黑名单

每个应用都会自动获得 10 个系统黑名单（每种受支持的条目类型一个）以及一个系统 高风险国家/地区 名单。这些名单不能删除或重命名。您可以通过 API 或控制台向其中添加条目。

可追溯性

每个黑名单条目都可以链接回其来源实体，以便您从名单跳转到原始记录：

从会话：创建条目时传入 reference_session_id（参见创建条目）。Didit 会自动提取该值（人脸、证件、电话、邮箱、IP 或设备），将底层模型标记为已加入黑名单，并将条目链接回该会话。Didit 会读取该会话中该类型的最新记录；若要添加较早记录中的值，请仅通过 value 添加，不传入 reference_session_id。
从交易、用户或企业：传入实体的 UUID 作为 reference_object_uuid，并包含 metadata.reference_type（"transaction"、"vendor_user" 或 "vendor_business"），以便控制台链接回原始记录。

Endpoints

列出所有名单

获取应用的所有名单。

名单条目

获取名单中的条目。

创建条目

向黑名单添加一个值，可通过值、会话引用或交易引用添加。

删除条目

删除条目并解除对底层实体的拦截。

上传人脸

直接将人脸图像上传到人脸黑名单。

​概念

​条目类型

​白名单

​系统黑名单

​可追溯性

​Endpoints