> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 用户黑名单：屏蔽人脸、证件与邮箱

> Didit 如何对 User 实体执行黑名单拦截：标识符类型、拦截检查方式，以及如何添加或移除条目。

黑名单可阻止未通过合规检查的用户创建新会话或发起新交易。Didit 支持按**标识符类型**设置黑名单，因此您可以在多个数据点（人脸、证件、邮箱、电话、用户 vendor\_data）上拦截同一名恶意行为者。

## 用户支持的标识符类型

| 类型 | Key | 匹配条件 |
| - | - | - |
| 人脸 | `FACE` | 新会话的活体自拍与黑名单中的人脸匹配 |
| 证件号码 | `DOCUMENT` | 新的证件提交与黑名单中的证件号码匹配 |
| 邮箱 | `EMAIL` | 新会话或交易使用了黑名单中的邮箱 |
| 电话 | `PHONE` | 新会话或交易使用了黑名单中的电话 |
| IP 地址 | `IP_ADDRESS` | 提交者的 IP 匹配，支持单个 IP（`1.2.3.4`）和 CIDR 范围（`10.0.0.0/8`） |
| 设备指纹 | `DEVICE_FINGERPRINT` | 提交者的设备指纹匹配 |
| 用户 | `USER` | 会话或交易使用了黑名单中的 `vendor_data` |

每种标识符类型都在其自然的触发点执行：

* 人脸和证件：在新会话期间执行。
* 邮箱和电话：在收集这些信息的会话步骤中执行，或在交易 payload 中执行。
* IP 和设备：在会话中的设备与 IP 分析期间执行。
* 用户 vendor\_data：在创建会话或交易时执行。

## 黑名单是如何产生的

> [!NOTE]
>
> 被拒绝的会话不会将任何人加入黑名单。会话以 `Declined` 结束，用户状态保持 `ACTIVE`，也不会写入任何名单条目，因此同一人仍可再次发起会话。加入黑名单是一个手动步骤：可以通过 [黑名单页面](https://docs.didit.me/zh/console/blocklist-users.md) 或 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 添加条目。其中，`USER` 条目（即用户的 `vendor_data`）还会将用户状态设为 `BLOCKED`。

**1. 自动：命中黑名单时**

当传入的会话匹配现有黑名单条目时，会话会被自动拒绝，并附带原因代码，例如 `blocked_face`、`blocked_document`、`blocked_email` 等。

**2. 手动：从控制台操作**

分析师可在 *Users → \[user] → Actions → Add to blocklist* 中将用户加入黑名单，并选择一个或多个要记录的标识符。

**3. 程序化：通过 Lists API**

使用 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 以编程方式添加条目。控制台底层使用的也是同一个 API。

## 系统名单与自定义名单

每个应用都有**系统黑名单**，每种标识符类型对应一个，由 Didit 自动管理。您无法重命名或删除它们。自定义名单则由您创建、命名并设定适用范围。

| 名单 | 创建者 | 说明 |
| - | - | - |
| System Face Blocklist | Didit | 该应用的标准人脸黑名单 |
| System Document Blocklist | Didit | 标准证件号码黑名单 |
| System Email Blocklist | Didit | 标准邮箱黑名单 |
| System Phone Blocklist | Didit | 标准电话黑名单 |
| System User Blocklist | Didit | 被拦截的 `vendor_data` 标识符 |
| 自定义黑名单 | 您 | 按范围划分的名单，例如按地区、按合作伙伴、按风险等级 |

## 通过 API 将用户加入黑名单

使用 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 添加黑名单条目。要按 `vendor_data` 拦截用户，请在对应的黑名单中添加 USER 类型的条目：

1. 使用 `entry_type=user` 和 `is_system=true` 过滤，[列出所有名单](https://docs.didit.me/zh/management-api/lists/list.md)，找到系统用户黑名单。
2. 在该名单上[创建条目](https://docs.didit.me/zh/management-api/lists/create-entry.md)，并将 `value` 设为用户的 `vendor_data`。

要按人脸拦截用户，请参阅 [人脸与生物识别](https://docs.didit.me/zh/entities/users/faces-and-biometrics.md#将人脸上传到黑名单)。要按邮箱、电话、证件或 IP 拦截，请使用对应的系统黑名单，并在 `value` 中填写相应标识符。

## 执行流程

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Didit
    participant Lists as Blocklist check
    participant Workflow
    Client->>Didit: POST /v3/session/ (vendor_data=user-42)
    Didit->>Lists: Does user-42 match a USER blocklist?
    Lists-->>Didit: Match found
    Didit-->>Client: Session auto-declined (reason: blocked_user)
```

对于人脸和证件黑名单，检查发生在验证步骤中：

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Didit
    participant Lists as Face Blocklist
    User->>Didit: Liveness capture
    Didit->>Lists: Embedding search
    Lists-->>Didit: Match similarity > threshold
    Didit-->>User: Session declined (reason: blocked_face)
```

## 从黑名单中移除

* **控制台**：*Blocklist → \[type] → row actions → Remove*。
* **API**：使用 [删除条目](https://docs.didit.me/zh/management-api/lists/delete-entry.md) 端点，并提供名单 UUID 和条目 UUID。

移除条目不会自动将用户恢复为 `ACTIVE`。如果您希望允许其发起新会话，请使用 `PATCH /v3/users/{vendor_data}/update-status/` 更改状态。

## 黑名单审计记录

黑名单中的每次添加或移除都会记录到[审计日志](https://docs.didit.me/zh/console/audit-logs.md)中：

* 添加者（用户邮箱，或 `'system'`、`'api'`）。
* 操作时间。
* 可选的 `comment`，用于说明原因。
* 若条目是自动生成的，则关联的会话或交易。

## 后续步骤

> [card] [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md)
>
> 完整的黑名单/白名单 API 参考文档。

> [card] [控制台黑名单](https://docs.didit.me/zh/console/blocklist-users.md)
>
> 在界面中管理黑名单。

> [card] [人脸与生物识别](https://docs.didit.me/zh/entities/users/faces-and-biometrics.md)
>
> 人脸黑名单的工作原理。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.