> ## 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.

# 管理 API v3：工作流与计费

> 通过 API 密钥配置工作流、问卷、用户、计费和黑名单。Didit 管理 API 支持智能体原生调用、兼容 MCP，按量付费，无需签订合同。

## 认证

所有管理 API 端点都使用您的应用 API 密钥。URL 中无需包含组织或应用 UUID，系统会根据您的密钥识别应用。

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...
```

还没有 API 密钥？[通过 2 次 API 调用以编程方式注册](https://docs.didit.me/zh/integration/programmatic-registration.md)。

***

## 工作流

工作流定义了用户需要完成的验证步骤（证件扫描、活体检测、人脸比对、AML 筛查等）。每个工作流都是可复用的配置，您可以将其关联到会话。

**GET /v3/workflows/** `GET`

列出应用的所有工作流。返回每个工作流的功能、阈值以及是否为默认工作流。

**POST /v3/workflows/** `POST`

创建新的工作流。定义要启用的验证功能、设置阈值、配置可接受的证件类型等。

**GET /v3/workflows/\{uuid}/** `GET`

获取指定工作流的完整详情，包括所有功能配置和阈值。

**PATCH /v3/workflows/\{uuid}/** `PATCH`

更新工作流配置。您可以修改任意功能设置、阈值或可接受的证件。

**DELETE /v3/workflows/\{uuid}/** `DELETE`

删除工作流。已使用该工作流的会话不受影响。

> [!WARNING]
>
> 我们强烈建议您使用**业务控制台**创建和配置工作流。可视化工作流构建器提供模板、拖放式功能配置、证件设置、阈值调整和预览功能，无需编写代码即可完成。仅在需要自动化或以编程方式管理工作流时使用 API。

### 创建工作流示例

`workflow_type` 决定基础功能集。随后可通过 `is_*_enabled` 标志开启或关闭各项功能。

```bash theme={null}
curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'
```

可用的 `workflow_type` 值：`kyc`、`kyb`、`adaptive_age_verification`、`biometric_authentication`、`address_verification`、`questionnaire_verification`、`email_verification`、`phone_verification`。

对于 `kyc` 工作流，会自动包含证件验证，无需为其单独设置标志。使用 `is_*_enabled` 标志可添加或移除可选功能，例如人脸比对、活体检测、AML、NFC、电话、邮箱、地址证明、设备与 IP 分析等。

然后在创建会话时使用该工作流：

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'
```

***

## 问卷

您可以将自定义表单添加到验证工作流中，以收集用户的额外信息。

**GET /v3/questionnaires/** `GET`

列出所有问卷。

**POST /v3/questionnaires/** `POST`

创建新问卷，包含自定义问题、分支逻辑和翻译内容。

**GET /v3/questionnaires/\{uuid}/** `GET`

获取问卷详情，包括所有问题和表单结构。

**PATCH /v3/questionnaires/\{uuid}/** `PATCH`

更新问卷。

**DELETE /v3/questionnaires/\{uuid}/** `DELETE`

删除问卷。

***

## 用户

管理应用中的已验证个人（用户）。每个用户由您在创建会话时提供的 `vendor_data` 字符串标识。

**GET /v3/users/** `GET`

列出应用的所有用户，包括其验证状态和会话历史。

**GET /v3/users/\{vendor\_data}/** `GET`

通过您的 vendor\_data 标识符获取用户详情。

**PATCH /v3/users/\{vendor\_data}/** `PATCH`

更新用户元数据。

**POST /v3/users/delete/** `POST`

批量删除用户。请求体：`{"vendor_data_list": ["user-1", "user-2"]}` 或 `{"delete_all": true}`。同时会清除为这些用户保留的所有生物特征模板。

***

## 生物特征模板

已选择加入的应用在删除会话后保留的不含图像的人脸生物特征模板。参见[生物特征模板](https://docs.didit.me/zh/management-api/biometric-templates/overview.md)。

**GET /v3/biometric-templates/** `GET`

分页列表，支持过滤条件（`vendor_data`、`vendor_user_uuid`、`status`、`source_type`、`retained_from`、`retained_to`、`ordering`）。

**GET /v3/biometric-templates/count/** `GET`

使用相同过滤条件统计数量。

**GET /v3/biometric-templates/\{template\_uuid}/** `GET`

获取单个模板：所属用户、来源引用、到期时间、指令和状态。

**DELETE /v3/biometric-templates/\{template\_uuid}/** `DELETE`

清除单个模板。返回 `{"uuid": "...", "outcome": "purged" | "already_purged"}`。

**POST /v3/biometric-templates/delete/** `POST`

批量清除。请求体：`{"template_uuids": [...]}` 或 `{"delete_all": true}`，并可附加可选过滤条件。

***

## 会话操作

**POST /v3/sessions/delete/** `POST`

批量删除会话。需要 `delete:sessions` 权限。请求体：`{"session_numbers": ["1", "2", "3"]}` 或 `{"delete_all": true}`（可使用以 `filter_` 为前缀的会话列表过滤条件缩小 `delete_all` 的范围，例如 `filter_status`），并可附加可选参数 `retain_face_embeddings`、`face_retention_days`、`face_retention_deadline`、`deletion_instruction` 和 `instruction_id`。匹配的会话最多为 20 个时，返回 `200`，并附带每个会话的 `face_retention_outcome`；超过 20 个时，返回 `202` 和一个删除任务。

**GET /v3/sessions/delete/\{job\_id}/** `GET`

查看返回 `202` 的批量会话删除任务的进度和结果计数。

**GET /v3/sessions/\{uuid}/reviews/** `GET`

列出会话的审核记录和活动日志。

**POST /v3/sessions/\{uuid}/reviews/** `POST`

为会话添加审核备注或状态变更。

***

## 计费

**GET /v3/billing/balance/** `GET`

获取当前额度余额和自动充值设置。

```json theme={null}
{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}
```

**POST /v3/billing/top-up/** `POST`

创建 Stripe 结账会话以为额度充值。每次充值金额为 \$50 至 \$20,000，按面值计入。

```json theme={null}
{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}
```

***

## 黑名单、白名单与自定义列表

按类型管理用于黑名单、白名单和自定义工作流条件的列表。完整内容请参阅 [列表 API 文档](https://docs.didit.me/zh/management-api/lists/overview.md)。

**GET /v3/lists/** `GET`

列出应用的所有列表（黑名单、白名单、自定义）。

**POST /v3/lists/\{list\_uuid}/entries/** `POST`

向列表添加条目。支持使用 `reference_session_id` 从会话中自动提取数据，并支持使用 `reference_object_uuid` 追溯到交易、用户或企业。

**DELETE /v3/lists/\{list\_uuid}/entries/\{entry\_uuid}/** `DELETE`

从列表中移除条目。

**POST /v3/lists/\{list\_uuid}/entries/face-upload/** `POST`

向人脸黑名单上传人脸图片（base64）。

***

## Webhook 配置

**GET /v3/webhook/** `GET`

获取当前 Webhook 配置，包括 URL、版本、用于验证 Webhook 签名的密钥，以及应用的数据保留策略和生物特征模板保留策略。
响应中还包含 `allowed_domains`，说明见下文 `PATCH /v3/webhook/`。

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"],
  "allowed_domains": ["https://app.example.com"]
}
```

**PATCH /v3/webhook/** `PATCH`

更新 Webhook URL、版本或轮换密钥。设置 `rotate_secret_key: true` 可生成新的 Webhook 密钥，旧密钥会立即失效。同时设置应用的保留策略：`data_retention_months`，以及在启用保留时必须提供的 `face_retention_policy`（默认为 `delete_with_session`，或 `retain_until_user_deleted`）和有限值的 `face_retention_days`（1-3650）。详见[生物特征模板保留](https://docs.didit.me/zh/console/data-retention.md#生物特征模板保留)。此外，还可注册 `allowed_return_hosts`：最多 20 个裸主机名（例如 `app.example.com`，不含协议、端口、路径或通配符），[数字身份钱包 API](https://docs.didit.me/zh/standalone-apis/digital-id-wallets.md#注册返回目标) 验证可通过 HTTPS 将用户返回这些主机。新列表会替换已注册的列表，您应用的白标域名始终被允许。

此外，还可设置 `allowed_domains`：最多 50 个 Web 来源（例如 `https://app.example.com`），托管验证流程可嵌入这些来源，并可借助会话的 `callback` 将用户返回这些来源。
每个条目由协议、主机和可选端口组成，不得包含路径、查询参数或通配符。
请使用 `https`；仅 `localhost`、`127.0.0.1` 和 `::1` 可以使用 `http`。
Didit 会将每个来源以小写形式存储，且不保留默认端口，并在 `allowed_domains` 中返回该列表。
无效条目会在 `allowed_domains` 上返回 400 错误。
新列表会替换已注册的列表，空列表会移除该限制。
列表非空时，[`POST /v3/session/`](https://docs.didit.me/zh/sessions-api/create-session) 会拒绝列表之外的 Web `callback`，返回 400，托管流程也不会将用户重定向到列表之外的已存储或工作流默认回调地址。
自定义 URL scheme（应用深层链接）和服务器到服务器的 API 调用不受影响。

如果您发送 `endpoints`，列表中未包含的每个 Webhook 目标都会被永久删除，连同其签名密钥和完整投递日志一并删除，删除方式与 [`DELETE /v3/webhook/destinations/{destination_uuid}/`](https://docs.didit.me/zh/management-api/webhook/delete-destination) 完全相同。
此操作无法撤销。
如需逐个管理目标，请改用 [Webhook 目标 endpoint](https://docs.didit.me/zh/management-api/webhook/list-destinations.md)。

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}
```

***

## API endpoint 完整汇总

| 端点 | 方法 | 说明 |
| - | - | - |
| `/v3/session/` | POST | 创建验证会话 |
| `/v3/sessions/` | GET | 列出所有会话 |
| `/v3/session/{id}/decision/` | GET | 获取会话验证结果 |
| `/v3/session/{id}/update-status/` | PATCH | 批准或拒绝会话 |
| `/v3/session/{id}/delete/` | DELETE | 删除单个会话 |
| `/v3/sessions/delete/` | POST | 批量删除会话 |
| `/v3/sessions/delete/{job_id}/` | GET | 批量会话删除任务状态 |
| `/v3/sessions/{id}/reviews/` | GET, POST | 会话活动/审核记录 |
| `/v3/workflows/` | GET, POST | 列出/创建工作流 |
| `/v3/workflows/{id}/` | GET, PATCH, DELETE | 工作流详情/更新/删除 |
| `/v3/questionnaires/` | GET, POST | 列出/创建问卷 |
| `/v3/questionnaires/{id}/` | GET, PATCH, DELETE | 问卷详情 |
| `/v3/users/` | GET | 列出已验证用户 |
| `/v3/users/{vendor_data}/` | GET, PATCH | 用户详情/更新 |
| `/v3/users/delete/` | POST | 批量删除用户（同时清除其保留的生物特征模板） |
| `/v3/biometric-templates/` | GET | 列出已保留的生物特征模板 |
| `/v3/biometric-templates/count/` | GET | 统计已保留的生物特征模板数量 |
| `/v3/biometric-templates/{id}/` | GET, DELETE | 模板详情/清除 |
| `/v3/biometric-templates/delete/` | POST | 批量清除模板 |
| `/v3/lists/` | GET, POST | 列出所有列表/创建列表 |
| `/v3/lists/{id}/` | GET, PATCH, DELETE | 列表详情/更新/删除 |
| `/v3/lists/{id}/entries/` | GET, POST | 列出条目/添加条目 |
| `/v3/lists/{id}/entries/{eid}/` | DELETE | 移除条目 |
| `/v3/lists/{id}/entries/face-upload/` | POST | 向黑名单上传人脸 |
| `/v3/webhook/` | GET, PATCH | Webhook 配置（URL、密钥、版本）、保留策略和钱包返回主机 |
| `/v3/billing/balance/` | GET | 查询额度余额 |
| `/v3/billing/top-up/` | POST | 为额度充值 |


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