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

# 以文件驗證

> 請求託管驗證連結，將其交付給您的客戶，讓他們上傳政府核發的身分證件與自拍照。

請求 IDV URL 是較高保證的 API 方法，且當[傳遞 SSN 資訊給我們](/verify-customers-by-ssn)未獲核准時可作為後備方案。您不需要自行蒐集身分文件，而是向 Fluz 請求一個託管驗證連結，然後交給您的客戶。Fluz 會直接收集並審查這些文件。

<Info>
  **先決條件**

  * Fluz 為您的應用程式啟用 `VERIFY_KYC` 權限範圍。請參閱[必要的 scope](/user-kyc-verification#required-scope)。
  * 為要驗證的該名客戶產生的[使用者存取權杖](/recipes/generate-user-access-token)，其 scopes 中包含 `VERIFY_KYC`。
  * 已註冊的 webhook 端點。**文件驗證必須具備此項** — 結果不會出現在 API 回應中。請參閱[驗證客戶](/user-kyc-verification#set-up-a-webhook)。
</Info>

## 運作方式

<Steps>
  <Step title="您識別客戶並請求連結">
    使用為該名客戶產生的使用者存取權杖呼叫 `requestDocumentVerificationLink`。此權杖告訴 Fluz 該次驗證屬於哪位客戶。
  </Step>

  <Step title="Fluz 回傳一組驗證連結">
    回應中包含 `verificationUrl` 與 `verificationId`。請儲存 `verificationId` — 您將以此對應最終送達 webhook 的事件與此次請求。
  </Step>

  <Step title="您將連結交付給客戶">
    依產品合適的方式傳送：電子郵件、簡訊、推播通知，或在 App 內重新導向。客戶可隨時完成驗證。
  </Step>

  <Step title="您的客戶上傳他們的文件">
    在託管頁面上，客戶會拍攝政府核發之身分證件（駕照、護照、州 ID 或軍人證）的正反面，並自拍以進行生物特徵比對。
  </Step>

  <Step title="Fluz 通知您驗證結果">
    當客戶完成後，Fluz 會審查提交內容，並將 `APPROVED` 或 `DECLINED` 的結果傳送至您的 webhook 端點。
  </Step>
</Steps>

<Warning>
  驗證連結對應於單一客戶與單次驗證嘗試。切勿在不同客戶間重複使用連結、將其記錄在共用系統中，或暴露於非該名客戶唯一可讀的場所 — 此連結可授予存取身分提交工作階段的權限。
</Warning>

## 請求

| Field          | Type    | Required | Description                                      |
| :------------- | :------ | :------- | :----------------------------------------------- |
| `gaveConsent`  | Boolean | Yes      | 客戶是否同意進行身分驗證。必須為 `true`，否則請求會被拒絕。                |
| `prefillData`  | Boolean | Yes      | 是否以 Fluz 既有的身分資訊預先填入驗證表單。當為 `true` 時，您不需要傳送下方欄位。 |
| `firstName`    | String  | No       | 客戶的法定名字。                                         |
| `lastName`     | String  | No       | 客戶的法定姓氏。                                         |
| `streetLine1`  | String  | No       | 居住街道地址。                                          |
| `streetLine2`  | String  | No       | 公寓、套房或門牌單位。                                      |
| `city`         | String  | No       | 城市。                                              |
| `region`       | String  | No       | 州或地區。                                            |
| `postalCode`   | String  | No       | 郵遞區號。                                            |
| `country`      | String  | No       | 國家（ISO 3166-1 alpha-2 格式）。                       |
| `dateOfBirth`  | String  | No       | 出生日期，格式為 `YYYY-MM-DD`。                           |
| `emailAddress` | String  | No       | 客戶的電子郵件地址。                                       |
| `phoneNumber`  | String  | No       | 客戶的電話號碼，E.164 格式。                                |

<Note>
  在設定 `gaveConsent: true` 之前，您必須先取得並記錄客戶的同意。您所傳遞的任何資料都將用於預先填入表單 — 客戶可在提交前檢視並更正，因此請將這些欄位視為便利性資料，而非最終將被驗證的值。
</Note>

<Warning>
  請注意與[SSN 驗證](/verify-customers-by-ssn)的欄位命名差異：此 mutation 使用 `region`，而另一個使用 `state`，並且此處的 `dateOfBirth` 預期為 `YYYY-MM-DD`，而非 `MM/DD/YYYY`。
</Warning>

## 範例

```javascript theme={null}
import { GraphQLClient, gql } from 'graphql-request';

const API_URL = 'https://transactional-graph.fluzapp.com/api/v1/graphql';

const REQUEST_DOC_VERIFICATION = gql`
  mutation RequestDocumentVerificationLink($input: RequestDocumentVerificationLinkInput!) {
    requestDocumentVerificationLink(input: $input) {
      userId
      verificationType
      verificationId
      verificationUrl
      status
      message
    }
  }
`;

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

const response = await client.request(REQUEST_DOC_VERIFICATION, {
  input: {
    gaveConsent: true,
    prefillData: true,
  },
});

console.log(response);
```

```json Response theme={null}
{
  "data": {
    "requestDocumentVerificationLink": {
      "userId": "eb910e93-5e39-4f53-99b9-0b033dd8e54b",
      "verificationType": "DOCUMENT_VERIFICATION",
      "verificationId": "idv_9MpDJC8aotDaxw",
      "verificationUrl": "https://verify.fluz.app/idv/idv_9MpDJC8aotDaxw?key=27f09ec042881c2c56945680c53108a4",
      "status": "OK",
      "message": "Verification link request successful"
    }
  }
}
```

<Note>
  此回應中的 `status`（`OK`）僅確認**連結已發行** — 並非驗證決策。決策會稍後透過 webhook 傳達。
</Note>

<Card title="開啟示範配方" icon="code" horizontal href="/recipes/request-document-verification-link">
  一個可直接複製執行的版本，能快速調整以融入您的整合。
</Card>

## 回應欄位

| Field              | Type   | Description                  |
| :----------------- | :----- | :--------------------------- |
| `userId`           | UUID   | 驗證所屬的 Fluz 客戶。               |
| `verificationType` | String | 一律為 `DOCUMENT_VERIFICATION`。 |
| `verificationId`   | String | 此次驗證嘗試的識別碼。請將其儲存以對應 webhook。 |
| `verificationUrl`  | String | 要交付給您客戶的託管連結。                |
| `status`           | String | 連結成功發行時為 `OK`。               |
| `message`          | String | 人類可讀的詳細資訊。                   |

## 客戶所見

託管流程會預先填入已知資訊供客戶檢視，接著要求他們：

1. 拍攝支援的政府核發照片 ID 的正反面。
2. 進行自拍，並與 ID 照片進行生物特徵比對。

在回傳決策前，會對文件真偽、是否被竄改，以及生物特徵比對結果進行全面審查。

## 接收結果

由於客戶可能在您發送連結後很久才完成驗證，結果將送達您的 webhook 端點。請將收到的事件與您儲存的 `verificationId` 進行比對，接著依結果採取行動：

* **`APPROVED`** — 客戶已通過驗證。開放相應功能。
* **`DECLINED`** — 客戶未通過驗證。文件驗證是升級路徑中的最後一步；此處被拒通常需要人工審查，而非再進行另一個自動化嘗試。

每位客戶的文件驗證請求次數有限。一旦達到上限，後續請求將回傳 `ERROR`，並附帶 `Exceeded document verification limit`。

## 測試

在測試環境中，您可以使用示例駕照與測試身分完成整個文件流程。測試環境不會強制執行文件真偽與其他安全特徵，您也可以在背面擷取時重複使用正面的影像。請參閱[測試 KYC 流程](/test-kyc-flows)。