> ## 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 用户与企业实体的状态及流转，涵盖创建、验证、ACTIVE/FLAGGED/BLOCKED 转换及删除。按次计费。

每个用户和企业实体在 Didit 中都会经历一个可预测的生命周期。理解这一生命周期，是设计入驻、持续监控和整改流程的关键。

## 生命周期图

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: Created (API, console, or auto from session)
    ACTIVE --> FLAGGED: Rule match / analyst review / suspicious pattern
    FLAGGED --> ACTIVE: Analyst clears / remediation completed
    ACTIVE --> BLOCKED: Manual block / blocklist match
    FLAGGED --> BLOCKED: Investigation concludes blocked
    BLOCKED --> ACTIVE: Manual unblock (analyst only)
```

## 状态详解

| 状态 | 含义 | 执行效果 |
| - | - | - |
| `ACTIVE` | 默认状态，实体状况良好 | 新会话和交易会按您配置的工作流和规则执行 |
| `FLAGGED` | 实体存在待处理问题，需要审核 | 新会话仍会执行，但默认进入 `IN_REVIEW`；交易可能根据规则自动升级 |
| `BLOCKED` | 实体已被禁止使用您的平台 | 新会话自动拒绝；新交易自动拒绝；无法为该 `vendor_data` 创建新的会话链接 |

> [!NOTE]
>
> 通过 `PATCH /v3/users/{vendor_data}/update-status/` 或 `PATCH /v3/businesses/{vendor_data}/update-status/` 更改状态时，会发出 Webhook（`user.status.updated` / `business.status.updated`），以便下游系统实时响应。

## 生命周期各阶段

**1. 创建**

实体可通过以下三种方式创建：

* **自动创建**：使用新的 `vendor_data` 启动会话时。实体以 `ACTIVE` 状态创建。
* **通过 API 预先创建**：使用 `POST /v3/users/create/` 或 `POST /v3/businesses/create/`。状态默认为 `ACTIVE`。
* **在控制台中创建**：由合规操作员创建。除非操作员另行指定，状态默认为 `ACTIVE`。

每个实体都会获得一个由 Didit 生成的 `uuid`，以及一个由客户拥有的 `vendor_data` 标识符。

**2. 验证**

会话通过 `vendor_data` 关联到实体。每个会话都会运行您配置的 [工作流](https://docs.didit.me/zh/console/workflows.md)，包括身份证件验证、活体检测、人脸比对、AML、证件、KYB 的注册信息查询等。

已完成的会话会更新实体的汇总计数器：

* `session_count`、`approved_count`、`declined_count`、`in_review_count`
* `features` 映射：每项功能在所有会话中的最新状态（例如 `{ "id_verification": "APPROVED", "aml": "IN_REVIEW" }`）
* 个人资料字段由最新的已通过会话同步更新（例如 `full_name`、`date_of_birth`、`portrait_image`）。

**3. 日常使用**

实体在拥有一个或多个已通过的会话后，您可以：

* **提交交易**：在交易请求体中通过 `vendor_data` 关联该实体
* **运行持续 AML 监控**：定期重新扫描制裁、PEP 和负面新闻名单
* **定期重新验证**：按固定间隔为同一 `vendor_data` 创建新会话
* **汇总风险信号**：跨会话和交易汇总风险信号

**4. 状态转换**

实体状态可自动或手动变更。

**自动转换**

* `ACTIVE → FLAGGED`：交易超过审核阈值，或规则将实体加入观察名单时。
* `ACTIVE → BLOCKED`：人脸生物特征与黑名单条目匹配时。

被拒绝的会话不会将实体列入黑名单，因此不会改变其状态。若要将被拒绝的当事人列入黑名单，需要手动操作：从[黑名单页面](https://docs.didit.me/zh/console/blocklist-users.md)或[列表 API](https://docs.didit.me/zh/management-api/lists/overview.md)添加条目。类型为 `USER`（即 `vendor_data`）的条目会将状态设为 `BLOCKED`。

**手动转换**发生在分析人员通过控制台更改状态，或您调用 `update-status` 端点时。

每次状态转换都会发出 `user.status.updated` 或 `business.status.updated` Webhook。

**5. 删除**

实体可通过 `POST /v3/users/delete/` 或 `POST /v3/businesses/delete/`（批量）删除。实体记录会被永久移除。删除用户时，还会在会话删除后清除为其保留的所有[生物特征模板](https://docs.didit.me/zh/management-api/biometric-templates/overview.md)，使该人员不再参与重复检测和人脸搜索的匹配。

这些端点不涵盖验证会话和交易。请使用[删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md)或[批量删除会话](https://docs.didit.me/zh/management-api/sessions/batch-delete.md)删除会话；交易需在控制台中删除。

## 活动时间戳

实体会记录活动情况，帮助您识别长期未活跃或仍在活跃的档案：

| 时间戳 | 更新时机 |
| - | - |
| `first_session_at` | 为该实体创建第一个会话时 |
| `last_session_at` | 最近一次创建或更新会话时 |
| `last_activity_at` | 发生任何变更时，包括会话、交易、状态变更或个人资料更新 |

您可以利用这些时间戳筛选长期不活跃的实体、安排重新验证，或触发持续监控。

## 生命周期中触发的事件

| 生命周期阶段 | 发出的 Webhook |
| - | - |
| 创建（由会话自动创建） | `status.updated`（会话）、`user.data.updated` 或 `business.data.updated` |
| 验证 | `status.updated`（会话）、`data.updated` |
| 状态变更 | `user.status.updated` 或 `business.status.updated` |
| 提交交易 | `transaction.created` |
| 交易状态变更 | `transaction.status.updated` |

有关负载结构和投递语义，请参阅[实体 Webhook](https://docs.didit.me/zh/entities/webhooks.md)。

## 后续步骤

> [card] [vendor\_data 关联](https://docs.didit.me/zh/entities/vendor-data-linking.md)
>
> `vendor_data` 如何将会话、交易和实体关联在一起。

> [card] [用户操作](https://docs.didit.me/zh/entities/users/operations.md)
>
> 创建、更新、更改状态和删除用户实体。

> [card] [企业操作](https://docs.didit.me/zh/entities/businesses/operations.md)
>
> 创建、更新、更改状态和删除企业实体。


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