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

# 負責人身分驗證連結

> 為必須透過文件驗證的企業負責人產生可分享的身分驗證連結。

## Overview

**requestOwnerDocumentVerificationLink** 這個 mutation 會產生一個可分享的 URL，企業負責人可以用它完成文件式的身分驗證。此連結可獨立運作——負責人不需要 Fluz 認證憑證。

將它用於 [getBusiness](/business-status) 回傳 `verificationType: DOCUMENTS` 且 `status: PENDING_CIP` 的負責人。這些是以 `isUsPerson: false` 送出的實益擁有人或控制人，因此走文件驗證路徑，而不是 SSN 路徑。

<Note>
  走 SSN 路徑（`verificationType: SSN`）的負責人不需要使用此 mutation；尚未接受邀請的負責人也不需要——Fluz 會直接寄 Email 給這些負責人，並由他們自行驗證。
</Note>

## Required scopes

| Property        | Value                               |
| --------------- | ----------------------------------- |
| Endpoint        | GraphQL API                         |
| Authentication  | OAuth Bearer Token，帳戶類型為 `BUSINESS` |
| Required Scopes | `REGISTER_BUSINESS`                 |

使用 `registerBusiness` 為該企業帳戶簽發的權杖。

## Prerequisites

以下條件必須全部成立，否則呼叫會失敗：

<Steps>
  <Step title="具備 REGISTER_BUSINESS 的企業帳戶權杖">
    權杖需限定在擁有該名冊的企業之下。
  </Step>

  <Step title="案件必須處於已提交待篩檢狀態">
    僅能在提交後的一個特定狀態期間產生連結。仍在建立中、已在等待篩檢結果、或進入人工審查的案件都會被拒絕——即使 [getBusiness](/business-status) 會將這些都回報為 `kybStatus: PENDING`。請見 [Timing](#timing)。
  </Step>

  <Step title="businessOwnerId 為負責人的 business-user ID">
    取自 [getBusiness](/business-status) 的 `owners[].id`，且屬於該企業。不可使用 Fluz 使用者 ID；尚未接受邀請的負責人其 `id: null`。
  </Step>

  <Step title="負責人走文件驗證路徑">
    `verificationType: DOCUMENTS` 且 `status: PENDING_CIP`。
  </Step>
</Steps>

## Basic mutation structure

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

## Parameters

| Parameter         | Type   | Required | Description                                                                             |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `businessOwnerId` | `UUID` | Yes      | 負責人的 business-user ID，來自 [getBusiness](/business-status) 的 `owners[].id`。不是 Fluz 使用者 ID |

## Response details

| Field              | Type      | Description                   |
| ------------------ | --------- | ----------------------------- |
| `success`          | `Boolean` | 產生連結時為 `true`                 |
| `id`               | `UUID`    | 產生連結所對應的 `businessOwnerId`    |
| `verificationLink` | `String`  | 可分享的 Plaid IDV URL。直接傳送給負責人使用 |

<Note>
  失敗會以「GraphQL 最上層錯誤」回傳，而不是 `success: false`。請檢查 `errors` 陣列，而非僅看資料載荷。這點與 [registerBusiness](/business-registration) 相反；後者會在其載荷內回報驗證失敗。
</Note>

## Timing

先決條件 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 Example

```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" }
  }'
```

## Example Response

### Success

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

### Error

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

## Error Codes

| Code        | Name               | Description                                                                           | How to resolve                                                      |
| ----------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `AUTH-0002` | InvalidCredentials | 使用了 Basic auth；權杖的帳戶類型不是 `BUSINESS`；權杖缺少 `userId` 或 `accountId`；或該 `accountId` 並不存在企業 | 使用為該企業 `accountId` 簽發的權杖                                            |
| `AUTH-0031` | InvalidScope       | 權杖缺少 `REGISTER_BUSINESS` 權限範圍                                                         | 新增該範圍並重新簽發權杖                                                        |
| `ARG-0002`  | MissingArguments   | 未提供 `businessOwnerId`                                                                 | 傳入負責人的 business-user ID                                             |
| `ARG-0001`  | InvalidArguments   | `businessOwnerId` 不屬於此企業的負責人，或案件未處於 submitted-for-approval 狀態                         | 重新讀取 [getBusiness](/business-status) 以取得最新 ID，並參閱 [Timing](#timing) |
| `G-0001`    | InternalError      | 驗證供應商未回傳連結，或向其發送的請求失敗                                                                 | 重試一次。若持續發生，請攜帶 `accountId` 聯絡客服                                     |

## Notes

* 產生的連結僅限單一用途。若負責人的連結過期或遺失，請再次呼叫此 mutation 以取得新的連結，而非重複使用舊連結。
* 產生連結不會改變負責人的 `status`。只有當負責人實際完成驗證後，狀態才會變為 `READY`——請持續讀取 [getBusiness](/business-status)。
* 無批次版本。每位需要連結的負責人都需各自呼叫一次。

## Related pages

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