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

# 所有者验证链接

> 为必须通过证件完成验证的企业所有者生成可分享的身份验证链接。

## 概览

**requestOwnerDocumentVerificationLink** 变更会生成一个可分享的 URL，企业所有者可用其通过证件完成身份验证。该链接可独立使用——所有者不需要 Fluz 凭证。

将其用于那些 [getBusiness](/business-status) 返回 `verificationType: DOCUMENTS` 且 `status: PENDING_CIP` 的所有者。这些是以 `isUsPerson: false` 提交的实益所有人或控制人，因此走证件通道而不是 SSN 通道。

<Note>
  走 SSN 通道（`verificationType: SSN`）的所有者不需要使用此变更；尚未接受邀请的所有者也不需要——Fluz 会直接给这些所有者发送邮件，他们自行完成验证。
</Note>

## 必需的范围

| 属性   | 值                                   |
| ---- | ----------------------------------- |
| 端点   | GraphQL API                         |
| 认证   | OAuth Bearer Token，账户类型为 `BUSINESS` |
| 所需范围 | `REGISTER_BUSINESS`                 |

使用为 `registerBusiness` 返回的该企业账户铸造的令牌。

## 先决条件

以下条件全部满足，否则调用失败：

<Steps>
  <Step title="具有 REGISTER_BUSINESS 的企业账户令牌">
    作用域限定到拥有该花名册的企业。
  </Step>

  <Step title="案件处于已提交等待筛查状态">
    该链接只能在提交后的特定状态下生成。仍在创建中、已在等待筛查结果或处于人工审核的案件都会被拒绝——尽管 [getBusiness](/business-status) 会将这些都报告为 `kybStatus: PENDING`。参见[时机](#timing)。
  </Step>

  <Step title="businessOwnerId 是所有者的业务用户 ID">
    取自 [getBusiness](/business-status) 的 `owners[].id`，且属于此企业。不接受 Fluz 用户 ID，尚未接受邀请的所有者其 `id: null`。
  </Step>

  <Step title="该所有者走证件通道">
    `verificationType: DOCUMENTS` 且 `status: PENDING_CIP`。
  </Step>
</Steps>

## 基本变更结构

```graphql theme={null}
mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) {
  requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) {
    success
    id
    verificationLink
  }
}
```

## 参数

| 参数                | 类型     | 必填 | 描述                                                                           |
| ----------------- | ------ | -- | ---------------------------------------------------------------------------- |
| `businessOwnerId` | `UUID` | 是  | 所有者的业务用户 ID，来自 [getBusiness](/business-status) 的 `owners[].id`。不是 Fluz 用户 ID |

## 响应详情

| 字段                 | 类型        | 描述                          |
| ------------------ | --------- | --------------------------- |
| `success`          | `Boolean` | 当生成了链接时为 `true`             |
| `id`               | `UUID`    | 生成链接所针对的 `businessOwnerId`  |
| `verificationLink` | `String`  | 可分享的 Plaid IDV URL。直接发送给所有者 |

<Note>
  失败作为**GraphQL 顶层错误**返回，而不是 `success: false`。请检查 `errors` 数组，而不只是数据负载。与 [registerBusiness](/business-registration) 相反，后者会在其负载内报告校验失败。
</Note>

## 时机

先决条件 2 中的状态要求是此调用失败的最常见原因，并且它不会通过 `kybStatus` 直观显示。

<Warning>
  **要尽早调用。** 在 `registerBusiness` 返回后不久，只要 [getBusiness](/business-status) 显示该所有者为 `verificationType: DOCUMENTS` 且 `status: PENDING_CIP`，即可调用。

  如果你收到 `ARG-0001`，并提示 `business is not submitted for approval`，说明案件已越过——或尚未到达——该时间窗口。不要循环重试。持续读取 `getBusiness`，如果某位所有者一直停留在 `PENDING_CIP` 且无法向其发送链接，请携带 `accountId` 联系你的客户经理。
</Warning>

## cURL 示例

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <BUSINESS_ACCESS_TOKEN>" \
  -d '{
    "query": "mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) { requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) { success id verificationLink } }",
    "variables": { "businessOwnerId": "d4e5f6a7-b8c9-0123-def0-234567890123" }
  }'
```

## 示例响应

### 成功

```json theme={null}
{
  "data": {
    "requestOwnerDocumentVerificationLink": {
      "success": true,
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "verificationLink": "https://verify.docs../..."
    }
  }
}
```

### 错误

```json theme={null}
{
  "errors": [
    {
      "message": "Invalid arguments received - business owner not found.",
      "extensions": {
        "code": "ARG-0001",
        "statusCode": 422
      }
    }
  ],
  "data": null
}
```

## 错误代码

| 代码          | 名称                 | 描述                                                                            | 解决方法                                                           |
| ----------- | ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `AUTH-0002` | InvalidCredentials | 使用了基本认证；令牌的账户类型不是 `BUSINESS`；令牌缺少 `userId` 或 `accountId`；或该 `accountId` 不存在企业 | 使用为该企业 `accountId` 铸造的令牌                                       |
| `AUTH-0031` | InvalidScope       | 令牌缺少 `REGISTER_BUSINESS` 范围                                                   | 添加该范围并重新铸造令牌                                                   |
| `ARG-0002`  | MissingArguments   | 未提供 `businessOwnerId`                                                         | 传入所有者的业务用户 ID                                                  |
| `ARG-0001`  | InvalidArguments   | `businessOwnerId` 不匹配此企业上的某位所有者，或案件不处于已提交等待批准状态                               | 重新读取 [getBusiness](/business-status) 以获取最新 ID，并参见[时机](#timing) |
| `G-0001`    | InternalError      | 验证服务商未返回链接，或对其的请求失败                                                           | 重试一次。如仍持续，请携带 `accountId` 联系支持                                 |

## 备注

* 生成的链接仅用于单一目的。若所有者的链接过期或丢失，请再次调用该变更以获取新的链接，而不是重复使用旧的。
* 生成链接不会改变所有者的 `status`。只有当所有者实际完成验证后才会变为 `READY`——请持续读取 [getBusiness](/business-status)。
* 没有批量版本。每位需要链接的所有者都需单独调用。

## 相关页面

<CardGroup cols={2}>
  <Card title="企业 KYB 状态" href="/business-status">
    识别哪些所有者需要链接，并确认他们何时完成。
  </Card>

  <Card title="KYB 概览" href="/kyb-overview">
    了解此步骤在端到端流程中的位置。
  </Card>

  <Card title="注册企业" href="/business-registration">
    `isUsPerson` 如何使所有者走证件通道。
  </Card>
</CardGroup>