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

# KYC 与 KYB 会话 API（Sessions API）

> Didit 的统一 Sessions API 在同一个端点上支持 KYC 与 KYB。按次付费，推理延迟低于 2 秒，覆盖 220+ 个国家和地区、14,000+ 种证件，每月赠送 $10 免费额度。

会话是 Didit 上的验证单元。开始一次验证时，系统会创建一个 **会话**；验证完成后，该会话会携带完整的决策 payload。同一套会话 API 同时处理两种类型：

| 类型 | 验证对象 | 决策 payload 包含 |
| - | - | - |
| **用户验证（KYC）会话** | 个人 | 身份证件验证、活体检测、人脸比对、地址证明（POA）、NFC、数据库核验、电话验证、邮箱验证、AML 筛查、问卷、设备与 IP 分析 |
| **企业验证（KYB）会话** | 公司或法律实体 | 公司登记核查、关键人员（高管/UBO）、证件验证、电话验证、邮箱验证、AML 筛查、问卷、设备与 IP 分析 |

在 Academy 的用户体验课程中，第 5:34 章节对比了托管流程与自建界面，这正是本 API 为您做出的取舍。

[托管流程与自建界面对比 | Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=334\&rel=0\&playsinline=1)

## 类型由工作流决定

当您[创建会话](https://docs.didit.me/zh/sessions-api/create-session.md)时，需要传入 `workflow_id`。工作流的类型决定该会话是用户验证还是企业验证，调用方无法单独选择。KYB 工作流会创建企业验证会话；KYC 工作流会创建用户验证会话。

## `session_kind` 判别字段

每个会话响应（包括创建、获取、列出、更新状态、分享和导入）都包含一个顶层字段：

```json theme={null}
{
  "session_id": "...",
  "session_kind": "user",
  ...
}
```

* `"user"`：该会话为 **用户验证（KYC）会话**。响应包含用户相关的功能数组。
* `"business"`：该会话为 **企业验证（KYB）会话**。响应包含企业相关的功能数组。

请据此字段在您的系统中区分处理不同的响应结构。

> [!NOTE]
>
> 枚举值是简短的标识符 `"user"` 和 `"business"`，为了便于 API 使用，我们保持其简短。完整名称 **用户验证（KYC）** 和 **企业验证（KYB）** 在整个文档中使用，以便理解。

## 按类型区分的功能数组

决策中出现的功能数组取决于类型。某一类型不适用的字段不会出现在该类型的响应中（不返回 null，也不返回占位符）：

| 功能数组 | 用户验证（KYC） | 企业验证（KYB） |
| - | :-: | :-: |
| `id_verifications` | ✅ | — |
| `liveness_checks` | ✅ | — |
| `face_matches` | ✅ | — |
| `nfc_verifications` | ✅ | — |
| `poa_verifications` | ✅ | — |
| `database_validations` | ✅ | — |
| `registry_checks` | — | ✅ |
| `document_verifications` | — | ✅ |
| `key_people_checks` | — | ✅ |
| `aml_screenings` | ✅ | ✅ |
| `phone_verifications` | ✅ | ✅ |
| `email_verifications` | ✅ | ✅ |
| `questionnaire_responses` | ✅ | ✅ |
| `ip_analyses` | ✅ | ✅ |
| `reviews` | ✅ | ✅ |
| `contact_details` | ✅ | ✅ |

## 顶层共享字段

每个会话（两种类型）都包含以下字段：

| 字段 | 说明 |
| - | - |
| `session_id` | 会话的 UUID |
| `session_kind` | `"user"`（用户验证 / KYC）或 `"business"`（企业验证 / KYB） |
| `session_number` | 在应用内的顺序编号 |
| `session_url` | 托管验证 URL |
| `status` | 会话的整体状态：`APPROVED`、`DECLINED`、`IN_REVIEW`、`IN_PROGRESS` 等 |
| `workflow_id` | 所用工作流的 UUID |
| `vendor_data` | 您为该实体设置的标识符。[了解更多](https://docs.didit.me/zh/entities/vendor-data-linking.md) |
| `metadata` | 创建时附加的自由格式 JSON |
| `callback` | 可选的回调 URL |
| `features` | 工作流运行的功能列表，以逗号分隔 |
| `expected_details` | 用于交叉校验的可选预期数据 payload |
| `created_at`、`expires_at` | 时间戳 |

## 涵盖的 endpoint

以下 endpoint 均支持两种类型。没有单独的 `/v3/business-session/*` 路径。

| endpoint | 适用于 |
| - | - |
| [`POST /v3/session/`](https://docs.didit.me/zh/sessions-api/create-session) | 根据工作流类型创建用户验证（KYC）或企业验证（KYB）会话 |
| [`GET /v3/session/{id}/decision/`](https://docs.didit.me/zh/sessions-api/retrieve-session) | 获取任一类型，根据 `session_id` 进行分发 |
| [`GET /v3/sessions/`](https://docs.didit.me/zh/sessions-api/list-sessions) | 列出任一类型。使用 `session_kind` 查询参数进行过滤 |
| [`PATCH /v3/session/{id}/update-status/`](https://docs.didit.me/zh/sessions-api/update-status) | 更新任一类型 |
| [`DELETE /v3/session/{id}/delete/`](https://docs.didit.me/zh/sessions-api/delete-session) | 删除任一类型 |
| [`GET /v3/session/{id}/generate-pdf/`](https://docs.didit.me/zh/sessions-api/generate-pdf) | 为任一类型生成 PDF，并路由到用户验证或企业验证模板 |
| [`POST /v3/session/{id}/share/`](https://docs.didit.me/zh/sessions-api/share-session/share) | 分享 token 包含 `session_kind` |
| [`POST /v3/session/import-shared/`](https://docs.didit.me/zh/sessions-api/share-session/import) | 导入任一类型，并保留 token 中的 `session_kind` |

## 查询的工作方式

用户验证会话和企业验证会话是两种不同的类型。ID 使用 UUID，因此不可能发生冲突。当您使用 `session_id` 调用 endpoint 时，Didit 会：

1. 先在用户验证表中查找该 ID（覆盖大部分流量）。
2. 若未找到，则回退到企业验证（KYB）表中查找。
3. 若两张表均无匹配，则返回 404。

您无需告诉 API 您要查找的是哪种类型。

## 两种类型的状态完全相同

两种类型的状态值相同，API 会按本页所写的原样返回：`"Not Started"`、`"In Progress"`、`"Approved"`、`"Declined"`、`"In Review"`、`"Abandoned"`、`"Expired"`、`"Kyc Expired"`、`"Resubmitted"`、`"Awaiting User"`。匹配为精确匹配，且区分大小写。完整说明请参见[验证状态](https://docs.didit.me/zh/integration/verification-statuses.md)。

## Webhooks

Webhook 事件已包含 `session_kind` 字段，便于您的 Webhook 处理程序按类型分发。

| 事件 | 类型 | 触发时机 |
| - | - | - |
| `status.updated` | 两者 | 会话状态发生变化。payload 中包含 `session_kind: "user"` 或 `"business"`。 |
| `data.updated` | 两者 | 会话数据发生变化（功能结果、公司登记信息刷新、持续 AML 监控）。payload 中包含 `session_kind`。 |
| `business.status.updated` / `business.data.updated` | 企业实体 | 关联的企业实体发生变化。 |
| `user.status.updated` / `user.data.updated` | 用户实体 | 关联的用户实体发生变化。 |

关于签名验证和重试语义，请参阅 [Webhook](https://docs.didit.me/zh/integration/webhooks.md)；关于企业验证的事件目录，请参阅 [KYB Webhook](https://docs.didit.me/zh/business-verification/webhooks.md)。

## 后续步骤

> [card] [创建会话](https://docs.didit.me/zh/sessions-api/create-session.md)
>
> 发起用户验证或企业验证。

> [card] [获取会话](https://docs.didit.me/zh/sessions-api/retrieve-session.md)
>
> 获取决策结果。两种类型均适用。

> [card] [列出会话](https://docs.didit.me/zh/sessions-api/list-sessions.md)
>
> 按 `session_kind` 过滤。

> [card] [更新状态](https://docs.didit.me/zh/sessions-api/update-status.md)
>
> 批准、拒绝、审核或重新提交。

> [card] [生成 PDF](https://docs.didit.me/zh/sessions-api/generate-pdf.md)
>
> 按类型生成 PDF 报告。

> [card] [分享与导入](https://docs.didit.me/zh/sessions-api/share-session/overview.md)
>
> 在应用之间迁移会话。


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