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

# 導入並連結客戶

> 端到端執行平台的快樂路徑 — 註冊客戶、使用 OAuth 連結其帳戶、驗證其身分，並代表他們進行操作。

這份快速上手是「建置平台」情境的可執行版本。你將以程式方式註冊一位客戶，走完 OAuth 授權以取得作用於「該客戶」帳戶範圍的權杖，使用沙盒 KYC 流程驗證其身分，並透過代表他們簽發一張虛擬卡來驗證連線 — 使用的 API 與你在自己帳戶上用的完全相同。

<Info>
  **先決條件**

  * 一個**包含測試環境應用程式的 Fluz 帳戶** — 任何快速上手的步驟 1–2，或參見[準備你的帳戶](/get-started/prepare-accounts)與[API 憑證](/get-started/api-credentials)。
  * 一個**已設定 OAuth 的應用程式**：`client_id`、`client_secret`，以及已註冊的 `redirect_uri` — 參見[建立 OAuth App](/create-an-o-auth-app)與[設定 OAuth App](/configure-o-auth-app)。
  * 請將請求送至**沙盒** — 沒有真實金錢、也沒有真實個資。參見[測試與正式環境](/concepts/environments)。
</Info>

<Warning>
  **註冊使用者需要特別許可。** `registerUser` 變更依應用程式控管（若未啟用會回傳 `AUTH-0022`）— 請聯繫你的客戶經理以啟用。尚未取得註冊權限嗎？跳過步驟 1，改用任何現有的測試環境使用者來執行流程。
</Warning>

## 完整流程

<Steps>
  <Step title="註冊客戶" icon="user-plus">
    使用 `registerUser` 佈建完整使用者 — 帳戶、餘額與推薦功能 — 並以**你的應用程式**權杖進行驗證。

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation RegisterUser(
            $firstName: String!
            $lastName: String!
            $phoneNumber: String!
            $regionCode: String!
            $emailAddress: String!
            $dateOfBirth: String!
          ) {
            registerUser(
              firstName: $firstName
              lastName: $lastName
              phoneNumber: $phoneNumber
              regionCode: $regionCode
              emailAddress: $emailAddress
              dateOfBirth: $dateOfBirth
            ) {
              success
              error { code message }
            }
          }
      ```

      ```json Variables theme={null}
          {
            "firstName": "Jane",
            "lastName": "Doe",
            "phoneNumber": "5551234567",
            "regionCode": "US",
            "emailAddress": "jane.doe@example.com",
            "dateOfBirth": "1990-05-15"
          }
      ```
    </CodeGroup>

    <Warning>
      此變更會將錯誤**放在回應資料內**，而非作為 GraphQL 錯誤 — 請務必檢查 `success` 並處理 `error` 物件。常見失敗：`AUTH-0026` / `AUTH-0027`（電話或 Email 已被使用）、`AUTH-0004`（無效電話）。完整清單：參見[使用者註冊](/user-registration)。
    </Warning>
  </Step>

  <Step title="讓客戶完成 OAuth 授權" icon="plug">
    客戶透過前往代管的授權頁來授權你的應用程式。使用你的 OAuth 設定與整合所需的範圍來建立 URL：

    ```text Authorization URL theme={null}
        https://uni.staging.fluzapp.com/authorize
          ?response_type=code
          &client_id=<YOUR_OAUTH_CLIENT_ID>
          &redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>
          &scopes=CREATE_VIRTUALCARD%20REVEAL_VIRTUALCARD
          &state=<OPTIONAL_OPAQUE_VALUE>
    ```

    * `scopes` 以**空白分隔**（URL 需編碼為 `%20`），且必須是你應用程式已啟用範圍的子集合 — 未知的範圍會被靜默忽略。
    * `state` 會原封不動回傳 — 用來將重導與你的工作階段對應。

    客戶會看到 Fluz 權限畫面，核准後被重導至你的 `redirect_uri`，並附帶 `?code=...&state=...`。該 `code` 僅能使用一次 — 請於伺服端擷取。

    完整參數參考：參見[面向客戶的 OAuth 授權流程](/client-facing-o-auth-grant-flow)。
  </Step>

  <Step title="以授權碼兌換客戶權杖" icon="key">
    以授權碼兌換作用於客戶範圍的 `accessToken`（以及 `refreshToken`）。此呼叫使用**基本驗證**：`client_id:client_secret` 的 base64。

    <CodeGroup>
      ```bash Exchange (cURL) theme={null}
          curl -X GET "https://uni.staging.fluzapp.com/token/exchange?code=<AUTH_CODE>&redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>" \
            -H "Authorization: Basic <base64 of CLIENT_ID:CLIENT_SECRET>"
      ```

      ```json Response (truncated) theme={null}
          {
            "accessToken": "eyJhbGciOi...",
            "accessTokenExpiresAt": "2026-07-13T21:05:30.673Z",
            "refreshToken": "8ec16c25951616150b0332a4a6d66547",
            "refreshTokenExpiresAt": "2026-08-13T20:55:30.738Z",
            "scope": ["CREATE_VIRTUALCARD", "REVEAL_VIRTUALCARD"],
            "user": { "id": "5070d5a1-d71a-4190-91b0-f116eec51771" }
          }
      ```
    </CodeGroup>

    `redirect_uri` 必須與授權步驟**完全**相同。請儲存 `refreshToken` 並在 `accessTokenExpiresAt` 之前輪替 — 參見[刷新 OAuth 存取權杖](/refresh-o-auth-access-token)。

    <Tip>
      要導入大量客戶嗎？在 authorize URL 後加上你的識別碼作為 `external_id`，以將 Fluz 帳戶連結到你系統的紀錄 — 參見[管理外部參考 ID](/managing-external-reference-ids)。
    </Tip>
  </Step>

  <Step title="驗證客戶身分（KYC）" icon="id-card">
    欲進行金流操作，需要完成身分驗證。請以**客戶的權杖**呼叫 `verifyUserInformation` — 權杖決定要驗證的是誰。在測試環境中，以下測試身分會一律回傳 `APPROVED`：

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation VerifyUserInformation($input: VerifyUserInformationInput!) {
            verifyUserInformation(input: $input) {
              status
              message
            }
          }
      ```

      ```json Variables (approved test identity) theme={null}
          {
            "input": {
              "firstName": "John",
              "lastName": "Smith",
              "streetLine1": "222333 Peachtree Place",
              "streetLine2": "",
              "city": "Atlanta",
              "state": "GA",
              "postalCode": "30318",
              "country": "United States",
              "dateOfBirth": "02/28/1975",
              "ssnLast4": "3333"
            }
          }
      ```
    </CodeGroup>

    <Warning>
      **三次嘗試上限：** 單一使用者最多可提交 3 次，再次提交將回傳 `ERROR` — 請勿在你真正需要的使用者上耗盡嘗試次數。完整沙盒結果：參見[測試 KYC 流程](/test-kyc-flows)。
    </Warning>
  </Step>

  <Step title="在其帳戶上操作 — 證明連線成功" icon="credit-card">
    重點來了：以**客戶的權杖**執行任何 Fluz 操作，將會在**該客戶**帳戶上執行。`createVirtualCard` 就是 `createVirtualCard` — 並無獨立的平台 API。

    ```graphql theme={null}
        mutation {
          createVirtualCard(
            input: {
              idempotencyKey: "1b7de2f8-c0a9-4532-9881-3ab5857bbe15"
              offerId: "ed669305-5e43-40a0-9a25-7a15ed174628"
              spendLimit: 50.00
              lockCardNextUse: true
              cardNickname: "First card on a connected account"
            }
          ) {
            virtualCardId
            virtualCardLast4
            status
          }
        }
    ```

    收到 `ACTIVE` 卡片代表閉環完成：已註冊 → 已連結 → 已驗證 → 可操作。客戶會透過權杖在你的系統中可見；他們不會獲得對「你的」帳戶的任何存取，而你只持有他們所授予的範圍。
  </Step>
</Steps>

## 大功告成 🎉

你已端到端導入並連結了一位客戶。接下來：

<CardGroup cols={2}>
  <Card title="建置平台" icon="layout-grid" href="/build-a-platform">
    完整的平台架構 — 權杖路徑、能力與模式。
  </Card>

  <Card title="核准與請求" icon="check-check" href="/features/approvals-and-requests">
    讓已連結使用者提出請求，由擁有者核准。
  </Card>

  <Card title="外部參考 ID" icon="link" href="/managing-external-reference-ids">
    以你的自有 ID 而非 Fluz 帳戶 ID 來識別客戶。
  </Card>

  <Card title="企業註冊與 KYB" icon="building-2" href="/business-registration">
    不只導入個人，也能導入企業。
  </Card>
</CardGroup>

<Note>
  **想了解更多嗎？** 與我們聯繫：[support@fluz.app](mailto:support@fluz.app) 以與專家對談或預約示範。
</Note>