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

# 供应商数据关联：将 ID 绑定到实体

> vendor_data 标识符可将您的系统与 Didit 关联，把会话、交易及用户/企业实体绑定为同一份档案。按次计费。

vendor\_data 关联提示词
将提示词复制到剪贴板

<pre>
  \`\`\`\`# Goal — link every session, transaction, and entity together using `vendor_data`

  `vendor_data` is the string identifier you choose and pass on every API call to bind it to a persistent [User](https://docs.didit.me/entities/users/overview.md) or [Business](https://docs.didit.me/entities/businesses/overview.md) entity. Get this right once and you never have to re-key history afterwards.

  ## Rules

  * `vendor_data` is **opaque** to Didit. Use your stable internal customer id.
  * Choose one canonical id per entity and never change it. Changing it orphans history under a new entity.
  * Prefix by entity type when convenient (`user_...`, `biz_...`) to avoid collisions in your own code.
  * Keep it under 128 chars, case-sensitive stable. Hard limit is 2000 bytes (UTF-8 encoded) - anything over that is rejected with a 400 rather than accepted.
  * **Never put raw PII in it** — it surfaces in webhooks, logs, and API responses.
  * Uniqueness is per application × entity type. User `user-42` and Business `user-42` are different entities (but don't do this).

  ## Where it goes

  | API | Field |
  | - | - |
  | `POST /v3/session/` | top-level `vendor_data` (KYC and KYB) |
  | `POST /v3/transactions/` | top-level `vendor_data` and `applicant.vendor_data` / `counterparty.vendor_data` |
  | `POST /v3/users/create/` / `POST /v3/businesses/create/` | `vendor_data` |
  | `GET /v3/sessions?vendor_data=...` | query param to retrieve history |
  | `GET /v3/users/{vendor_data}/` / `GET /v3/businesses/{vendor_data}/` | path param |

  ## Pattern — pre-create the entity, then run a session

  ```bash
  # 1) Seed the entity with metadata before any session
  curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "vendor_data": "user-42",
  "display_name": "Jane Doe",
  "metadata": {"tier": "premium", "signup_date": "2026-04-01"}
  }'

  # 2) Run a KYC session linked to the same entity
  curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "workflow_id": "$WORKFLOW_ID",
  "vendor_data": "user-42",
  "callback": "https://myapp.com/return"
  }'

  # 3) Later, retrieve every session for the entity
  curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  --data-urlencode "vendor_data=user-42"
  ```

  ## Auto-create semantics

  If you create a session with a new `vendor_data` and no entity exists, Didit creates the entity automatically with `status: ACTIVE` and links the session.

  ## Failure modes

  * Missing `vendor_data` on session create → session is orphaned, won't appear in any entity profile, cannot be filtered by `vendor_data` later (only by `session_id`).
  * Different case (`User-42` vs `user-42`) → two separate entities. Pick a casing convention and stick to it.
  * Same `vendor_data` across staging and prod apps → no collision; `vendor_data` is scoped per application.

  ## Sources of truth

  * /entities/users/operations — full User CRUD
  * /entities/businesses/operations — full Business CRUD
  * /sessions-api/create-session — session body shape
  * /integration/integration-prompt — canonical end-to-end prompt\`\`\`\`
</pre>

粘贴到

`vendor_data` 是您在每个会话和交易中提供的标识符，用于将其关联到[用户](https://docs.didit.me/zh/entities/users/overview.md)或[企业](https://docs.didit.me/zh/entities/businesses/overview.md)实体。它是实体聚合中最重要的字段。只要它设置正确，后续的所有功能（档案历史、交易监控、黑名单拦截、持续 AML 监控）都能顺畅运作。

## 是什么

`vendor_data` 是由您自行选择的**字符串**。Didit 将其视为不透明的标识符，不会解析其内容。常见的取值如下：

| 您的系统 | 适用的 `vendor_data` 取值 |
| - | - |
| 内部用户数据库 | `user_1234`，用户的 `uuid-v4` |
| 面向客户的 ID | `CUST-2026-00042`，哈希后的邮箱 |
| 多租户 SaaS | `tenant_acme:user_1234` |
| B2B 平台 | `company-hq-global`，`tax-id-US-123456789` |

> [!WARNING]
>
> 请**不要**直接在 `vendor_data` 中填入 PII（如邮箱、电话号码、原始税号）。请先对其进行哈希处理或添加前缀。`vendor_data` 会出现在 Webhook payload 中，只要实体存在，就会被无限期保存。

## 关联机制

```mermaid theme={null}
flowchart TD
    subgraph YourSystem["Your system"]
      Customer["Customer record: user-42"]
    end
    subgraph Didit["Didit platform"]
      Entity["User entity (vendor_data = user-42)"]
      S1[Session #1]
      S2[Session #2]
      T1[Transaction #1]
      T2[Transaction #2]
      F[Face biometric]
    end
    Customer -.vendor_data.-> Entity
    S1 --> Entity
    S2 --> Entity
    T1 --> Entity
    T2 --> Entity
    F --> Entity
```

当您提交带有 `vendor_data` 值的会话或交易时：

1. Didit 会在您的应用中查找具有该 `vendor_data` 的实体。
2. 如果实体已存在，则将新对象关联到该实体。
3. 如果实体不存在，Didit 会创建该实体（状态为 `status: ACTIVE`），并将新对象关联到它。

以下场景均适用此机制：

* `POST /v3/session/`：KYC 与企业验证（KYB）会话
* `POST /v3/transactions/`：交易（适用于申请人和交易对手双方）
* 交易负载中的 `applicant.vendor_data` / `counterparty.vendor_data` 字段

## 唯一性与适用范围

`vendor_data` 在**每个应用内唯一**，而不是在整个 Didit 范围内全局唯一：

| 范围 | 唯一性保证 |
| - | - |
| 单个应用内 | `vendor_data` 在每种实体类型内唯一（用户与企业是两个独立的命名空间） |
| 您组织内的不同应用之间 | `vendor_data` **不会**共享：两个应用中的相同取值指向两个不同的实体 |
| 不同组织之间 | 不会共享：每个组织都有自己的实体表 |

这意味着您可以在预发布（staging）应用和生产应用中使用相同的 `vendor_data`，而不会发生冲突。您也可以同时拥有用户 `user-42` 和企业 `user-42`，两者不会冲突（不过为了清晰起见，不建议这样做）。

## 省略 `vendor_data` 会怎样

您可以在不提供 `vendor_data` 的情况下创建会话。此时：

* 不会为该会话创建实体。
* 该会话成为孤立会话，不会出现在任何用户或企业档案中。
* 之后您无法通过 `vendor_data` 查询该会话，只能通过 `session_id` 查询。

此模式仅适用于匿名或一次性验证，即不需要实体聚合的场景。对于涉及重新验证、交易或持续监控的所有集成，请务必提供 `vendor_data`。

## 预创建实体并运行会话的示例

```bash theme={null}
# 1. Pre-create the User with initial metadata
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_date": "2026-04-01" }
  }'

# 2. Create a User Verification (KYC) session for the same user
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyc_standard",
    "vendor_data": "user-42"
  }'

# 3. Later, submit a transaction tied to the same user
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "tx-0001",
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Acme Corp" }
  }'
```

这三次调用都关联到同一个用户实体。之后调用 `GET /v3/users/user-42/` 时，您将看到会话数量、已通过和已拒绝的计数、关联的交易以及最新的档案数据。

## 迁移外部 ID

如果您是在使用现有 KYC 供应商后采用 Didit，请从第一天起就将现有的稳定用户 ID 作为 `vendor_data` 传入。这样可以更轻松地：

* 将 Didit 数据与您的内部数据库进行对账。
* 在运行任何会话之前，通过控制台 CSV 导入批量加载历史用户。
* 当您之后迁移到 Didit 进行交易监控时，保留既有关系。

## 规则、约定和最佳实践

| 规则 | 原因 |
| - | - |
| 为每个实体选择一个标准标识符，且永不更改 | 更改会创建新实体，并使历史记录成为孤立数据 |
| 按实体类型为 `vendor_data` 值添加前缀（`user_...`、`biz_...`） | 防止您自己的代码中不同命名空间之间发生意外冲突 |
| 保持 `vendor_data` 区分大小写且稳定 | Didit 不会对大小写进行规范化 |
| 保持 `vendor_data` 长度少于 128 个字符 | 便于数据库索引的高效存储 |
| 切勿暴露原始 PII | `vendor_data` 会出现在 Webhook、审计日志和 API 响应中 |

## 后续步骤

> [card] [用户概览](https://docs.didit.me/zh/entities/users/overview.md)
>
> 深入了解用户实体及其操作。

> [card] [企业概览](https://docs.didit.me/zh/entities/businesses/overview.md)
>
> 深入了解企业实体及其操作。

> [card] [创建会话](https://docs.didit.me/zh/sessions-api/create-session.md)
>
> 为某个 vendor\_data 发起验证。

> [card] [创建交易](https://docs.didit.me/zh/management-api/transactions/create.md)
>
> 提交与实体关联的交易。


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