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

# 總覽

> 從你的平台產生託管的虛擬卡連結（「開放式迴路」Send Cards）。你只需呼叫一個 API 來鑄造一個或多個連結，然後以你喜歡的方式將這些連結交付給收件人——透過電子郵件、SMS，或回傳原始網址以嵌入你的自有流程。當收件人開啟連結時，他們會進入由 Fluz 託管的頁面、完成驗證，並領取由你的帳戶資助的一次性加值虛擬卡。

<Info>
  **先決條件：** 需要具備 `CREATE_SHARE_LINK` 權限範圍的 Bearer 存取權杖。基本驗證會被拒絕。請聯絡你的業務代表以啟用存取權。請參閱 [Authentication](/concepts/authentication)。
</Info>

<Note>
  **「託管」/「開放式迴路」的意義。** *託管* 連結會指向 Fluz 託管的啟用頁面。*開放式迴路* 表示產生的虛擬卡為網路卡（Visa/Mastercard 類型），可依你的方案規則在多家商家使用——而非單一品牌的封閉式禮品卡。
</Note>

![Hosted virtual card](https://test.fluz.app/wp-content/uploads/2026/04/ol-mock.png)

## 運作方式

<Steps>
  <Step title="你產生連結">
    以優惠、卡片限額、數量、資金來源與交付方式呼叫 `generateVCShareLinks`。每個連結代表一張擁有自己限額的卡片，並由你指定的消費帳戶資助。
  </Step>

  <Step title="Fluz 為每個連結建立一筆分享請求">
    每個連結對應到一筆分享請求（`PENDING`）和一個託管 URL。
  </Step>

  <Step title="連結被交付">
    使用 `GENERATE_URL` 時，你會拿回要自行分發的網址。使用 `EMAIL` 或 `PHONE_NUMBER` 時，Fluz 會代你將連結送達每位收件人。
  </Step>

  <Step title="收件人啟用並領取卡片">
    收件人開啟連結後，以一次性驗證碼驗證手機號碼並設定卡片 PIN——無需下載 App、無需密碼。卡片限額會在領取時自你的消費帳戶扣撥，而非在產生連結時。他們之後可檢視卡片資訊、線上消費，並一鍵把卡片加入 Apple Pay 或 Google Pay。
  </Step>
</Steps>

收件人只會成為該虛擬卡物件的授權使用者——他們不會取得你帳戶、餘額或其他卡片的存取權。

觀賞收件人實際體驗流程：[桌面版流程](https://test.fluz.app/wp-content/uploads/2026/04/Web-Share-V6.mp4) · [行動版流程](https://test.fluz.app/wp-content/uploads/2026/04/Mob-Share-F.mp4)。

![Send cards flow diagram](https://files.readme.io/c19029bfeaca196f7eadc2f020ab56f2aad893261f561307bec543e700f0d74b-diagram.svg)

## 可用性與範圍

| 功能            | 狀態             |
| ------------- | -------------- |
| 一次性加值虛擬卡      | ✅ 支援           |
| 單次使用 / 可重複加值卡 | ❌ 不支援          |
| 透過 API 產生連結   | ✅ 支援           |
| 透過 CSV 匯入產生連結 | ❌ 即將推出         |
| 託管型「禮品卡」連結    | ❌ 不在範圍內（僅限虛擬卡） |

卡片分享連結物件類型為 `VIRTUAL_CARD`，卡片類型為 `SINGLE_LOAD`。

<Warning>
  **禮品卡：** 儘管更廣泛的計畫以「虛擬卡與禮品卡」為主題，目前沒有託管的禮品卡領取流程。禮品卡餘額只會在此處以「潛在的資金來源」出現（規劃中，尚未啟用）。請僅以虛擬卡進行文件撰寫與開發。
</Warning>

## 作業參考

共有三個公開作業，全部受 `CREATE_SHARE_LINK` 權限範圍控管：

| 作業                       | 類型       | 目的            |
| ------------------------ | -------- | ------------- |
| `generateVCShareLinks`   | Mutation | 建立一或多個託管虛擬卡連結 |
| `getVCShareLinks`        | Query    | 列出/檢視先前產生的連結  |
| `deactivateVCShareLinks` | Mutation | 停用（使失效）你產生的連結 |

所有 Send Cards 作業皆在 Fluz GraphQL API 上，`POST https://<your-fluz-api-host>/api/v1/graphql`，並附上 `Authorization: Bearer <access_token>` 標頭。權杖必須包含 `CREATE_SHARE_LINK` 權限範圍——否則每個作業都會回傳「Missing permissions! Please contact your sales rep to get access to generate VC share links.」。

## generateVCShareLinks

建立 `quantity` 筆分享請求，並為每筆請求回傳一個託管連結。

```graphql theme={null}
mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}
```

### 輸入欄位

| 欄位                    | 類型                 | 必填  | 說明                                                                                                       |
| --------------------- | ------------------ | --- | -------------------------------------------------------------------------------------------------------- |
| `cardLimit`           | `Int!`             | 是   | 每張卡的消費上限（亦為加值金額），單位為整數貨幣單位。必須為整數且 ≥ 方案下限。                                                                |
| `offerId`             | `String!`          | 是   | 卡片綁定之商家優惠的 UUID v4。該優惠必須為啟用狀態，且其商家必須可分享。                                                                 |
| `quantity`            | `Int!`             | 是   | 要產生的連結數量。每個單位會建立一個不同的託管 URL。                                                                             |
| `shareMethod`         | `ShareMethodType!` | 是   | 連結的交付方式：`GENERATE_URL`、`EMAIL` 或 `PHONE_NUMBER`。                                                         |
| `userCashBalanceId`   | `UUID`             | 是\* | 用於資助卡片的消費帳戶。*雖然在綱要中標示為選填，但實務上為必填——省略會驗證失敗。*                                                              |
| `daysUntilExpiration` | `Int`              | 否   | 連結到期的天數。最少為 1。若省略，預設為方案預設值（30 天）。**此日期同時也會成為卡片的鎖定/凍結日期**——詳見 [Expiration & freeze](#expiration--freeze)。 |
| `recipientListEmail`  | `[String]`         | 條件式 | 當 `shareMethod = EMAIL` 時為必填且不可為空；長度必須等於 `quantity`。否則必須留空。                                              |
| `recipientListPhone`  | `[String]`         | 條件式 | 當 `shareMethod = PHONE_NUMBER` 時為必填且不可為空；長度必須等於 `quantity`。否則必須留空。                                       |

<Note>
  **資金來源。** 目前唯一支援的資金來源為**消費帳戶**（`userCashBalanceId`），且必須屬於你（寄件者）的帳戶。其他資金來源（銀行帳戶、銀行卡、預付款/獎勵餘額）尚未開放。
</Note>

### 交付方式（`shareMethod`）

| 值              | 行為                       | 收件人清單                                      |
| -------------- | ------------------------ | ------------------------------------------ |
| `GENERATE_URL` | Fluz 在回應中回傳託管 URL。你自行分發。 | 兩個清單都必須為空/省略。                              |
| `EMAIL`        | Fluz 代你以電子郵件將連結寄給每位收件人。  | 需要 `recipientListEmail`；長度必須等於 `quantity`。 |
| `PHONE_NUMBER` | Fluz 代你以簡訊將連結傳給每位收件人。    | 需要 `recipientListPhone`；長度必須等於 `quantity`。 |

### 驗證規則

* `cardLimit` 必須為整數且至少達到方案下限。
* `offerId` 必須為 **啟用** 中之優惠且其 **商家可分享** 的有效 UUID v4。
* `quantity` 必須為整數。
* 若以 `EMAIL` 或 `PHONE_NUMBER` 交付，對應之收件人清單長度**必須等於** `quantity`。若不相符會回傳明確錯誤，且**不會**建立任何紀錄。
* 只能提供一個資金來源。`userCashBalanceId` 必須為寄件者帳戶所擁有的有效 UUID v4。
* 無效的卡片類型或格式錯誤的輸入會回傳明確錯誤，且不會建立任何紀錄。

### 範例

<CodeGroup>
  ```json Generate URLs theme={null}
  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 3,
      "shareMethod": "GENERATE_URL",
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }
  ```

  ```json Email theme={null}
  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 2,
      "shareMethod": "EMAIL",
      "recipientListEmail": ["recipient1@example.com", "recipient2@example.com"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }
  ```

  ```json SMS theme={null}
  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 2,
      "shareMethod": "PHONE_NUMBER",
      "recipientListPhone": ["+12125550101", "+12125550102"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }
  ```
</CodeGroup>

### 回應

```json theme={null}
{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1",
        "https://fluz.app/virtual-prepaid-card/9b2d...77",
        "https://fluz.app/virtual-prepaid-card/0c41...e3"
      ]
    }
  }
}
```

`shareLinks` 是託管 URL 的陣列，數量等於 `quantity`，其格式為 `https://fluz.app/virtual-prepaid-card/{share_request_id}`。

<Tip>
  回應只會回傳 URL。若要擷取你剛建立的連結所需的**批次 ID** 與 **顯示 ID**（用於清單與停用），請使用 `getVCShareLinks` 並以狀態做篩選。
</Tip>

## getVCShareLinks

列出先前產生的分享連結，以便你檢視狀態、收件人、到期日與已發行卡片。

```graphql theme={null}
query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    senderAppId
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    recipientPhone
    recipientEmail
    linkExpirationDate
    virtualCardId
    linkUrl
    shareRequestDetails {
      cardLimit
      offerId
      daysUntilExpiration
      quantity
      shareMethod
      recipientListEmail
      recipientListPhone
      userCashBalanceId
    }
  }
}
```

### 輸入欄位

| 欄位                       | 類型                    | 說明                                         |
| ------------------------ | --------------------- | ------------------------------------------ |
| `shareObjectStatuses`    | `[ShareObjectStatus]` | 以狀態篩選：`PENDING`、`ISSUED`、`USED`、`EXPIRED`。 |
| `shareRequestBatchIds`   | `[String]`            | 僅回傳屬於這些批次的連結。                              |
| `shareRequestDisplayIds` | `[String]`            | 僅回傳具有這些顯示 ID 的連結。                          |

<Tip>
  **建議流程。** 第一次呼叫時，僅以 `shareObjectStatuses` 篩選。回應會提供 `shareRequestBatchId` 與 `shareRequestDisplayId`；在後續呼叫（以及停用時）使用這些值做更精準的篩選。
</Tip>

### 回應欄位（`GeneratedShareLink`）

| 欄位                      | 類型                    | 說明                                     |
| ----------------------- | --------------------- | -------------------------------------- |
| `senderAppId`           | `String`              | 產生該連結的應用程式/開發者應用。                      |
| `shareRequestBatchId`   | `String`              | 在一次呼叫中產生的所有連結共用的批次識別。                  |
| `shareRequestDisplayId` | `String`              | 針對每個連結的人類可讀識別。                         |
| `shareObjectStatus`     | `ShareObjectStatus`   | `PENDING`、`ISSUED`、`USED` 或 `EXPIRED`。 |
| `recipientEmail`        | `String`              | 若以電子郵件交付，則為收件人信箱。                      |
| `recipientPhone`        | `String`              | 若以 SMS 交付，則為收件人電話。                     |
| `linkExpirationDate`    | `DateTime`            | 連結到期 / 卡片凍結時間。                         |
| `virtualCardId`         | `String`              | 已領取後所發行的虛擬卡 ID。                        |
| `linkUrl`               | `String`              | 該連結的託管 URL。                            |
| `shareRequestDetails`   | `ShareRequestDetails` | 原始設定（卡片限額、優惠、數量、交付、資金）。                |

### 範例

<CodeGroup>
  ```json By status theme={null}
  { "input": { "shareObjectStatuses": ["PENDING", "ISSUED"] } }
  ```

  ```json By batch theme={null}
  { "input": { "shareRequestBatchIds": ["ABC123", "XYZ789"] } }
  ```

  ```json By display ID theme={null}
  { "input": { "shareRequestDisplayIds": ["SR-000001", "SR-000002"] } }
  ```
</CodeGroup>

## deactivateVCShareLinks

停用（使失效）你產生的連結——例如，若批次誤發，或你需要撤銷未被領取的連結。停用連結會將其狀態設為 `EXPIRED`；未領取的連結將無法再被領取。

```graphql theme={null}
mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}
```

### 輸入欄位

| 欄位                       | 類型         | 說明                |
| ------------------------ | ---------- | ----------------- |
| `shareRequestBatchIds`   | `[String]` | 停用這些批次中的所有連結。     |
| `shareRequestDisplayIds` | `[String]` | 僅停用具有這些顯示 ID 的連結。 |

從 `getVCShareLinks` 取得批次 ID。

```json theme={null}
{ "input": { "shareRequestBatchIds": ["ABC123"] } }
```

回傳人類可讀的確認字串，例如：`"3 share requests successfully deactivated!"`。

<Warning>
  若收件人已經**領取**連結（狀態為 `ISSUED`/`USED`），停用連結不會回收已發行的卡片。若要停止已發行卡片的消費，請使用相應的卡片生命週期/凍結控制。
</Warning>

## 收件人體驗

當收件人開啟託管連結（`https://fluz.app/virtual-prepaid-card/{share_request_id}`）時：

<Steps>
  <Step title="進入頁面與登入">
    收件人會看到帶有寄件商標示的啟用頁面。他們透過 Fluz 驗證入口登入（新收件人在此進行導入）。
  </Step>

  <Step title="雙重驗證">
    初次載入時，既有使用者會被導向 2FA 畫面。必須完成 2FA 才能檢視或領取卡片。
  </Step>

  <Step title="帳單地址（若需要）">
    若收件人尚未留存帳單地址，系統會提示新增。*線上交易需要帳單地址。*
  </Step>

  <Step title="PIN（若尚未發行）">
    在卡片發行前，收件人需設定 PIN。
  </Step>

  <Step title="卡片發行與領取">
    系統會建立一張一次性加值虛擬卡並指派給收件人，資金來自寄件者帳戶，鎖定日期等同於連結的到期日。
  </Step>

  <Step title="使用卡片">
    領取後，收件人可查看卡片資訊、交易紀錄，並（在支援的情況下）將卡片加入行動錢包。
  </Step>
</Steps>

<Note>
  **已被領取了嗎？** 若同一位使用者開啟他已領取的連結，會看到自己的卡片資訊。若\_不同\_使用者開啟已被他人領取的連結，通過 2FA 後會看到拒絕存取的狀態。
</Note>

## 到期與凍結

連結的到期日具備雙重用途：

* **連結到期**——在此日期之後，**未被領取**的連結將無法再被領取。
* **卡片凍結 / 鎖定日**——對於**已發行**的卡片，此日期為鎖定日（該日結束）。之後卡片會被凍結且無法消費。
* **卡片有效期限** 將對齊凍結日所在月份的月底（例如，凍結日為 2026/6/15，卡片到期為 2026/6/30）。

請在產生時以 `daysUntilExpiration` 設定期間。若省略，將使用方案預設（30 天）。此日期會顯示給收件人（通常以「有效至」日期呈現）。

## 應告知收件人的方案規則

以下為託管（開放式迴路）虛擬卡的方案層級規則。請與你的 Fluz 代表確認**你的**方案之確切數值——部分屬於合作方協議內容。

| 規則       | 預設              | 備註                           |
| -------- | --------------- | ---------------------------- |
| 每日帳戶消費上限 | **\$250,000/日** | 部分合作夥伴有自訂上限。                 |
| 餐廳交易緩衝   | **25%**         | 所有方案皆適用 25% 緩衝（以涵蓋餐廳小費/預授權）。 |
| 受限商家/類別  | 依方案而定           | 某些商家類別受限。                    |
| 資金來源     | 寄件者的消費帳戶        | 卡片在領取時自寄件者帳戶資助。              |

**收件人客服支援：** 1-888-360-6660 · [humans@fluz.app](mailto:humans@fluz.app)

<Note>
  完整的合作夥伴參考文件（術語、含截圖的收件人操作流程、資金補充指引、受限類別與支援）位於 **Partner Guide — Hosted URL Virtual Cards**。請向你的 Fluz 聯絡窗口索取你方案的最新版本。
</Note>

## 狀態與錯誤參考

### 分享物件狀態

| 狀態        | 意義               |
| --------- | ---------------- |
| `PENDING` | 已產生連結，尚未被領取。     |
| `ISSUED`  | 收件人已領取連結；虛擬卡已發行。 |
| `USED`    | 已發行的卡片已有使用紀錄。    |
| `EXPIRED` | 連結到期或被停用；不可再領取。  |

### 面向收件人的連結錯誤

| 條件               | 收件人所見                              |
| ---------------- | ---------------------------------- |
| 連結在被領取前已到期       | 「Expired before issued」——連結無法再被領取。 |
| 寄件者提前停用連結        | 「Frozen by sender」——連結在到期前被撤銷。     |
| 卡片已被領取，且鎖定日已過    | 「Expired after issued」——卡片已凍結。     |
| 不同使用者開啟已被他人領取的連結 | 「Access denied」。                   |

### 常見 API 錯誤

| 成因                                           | 結果                |
| -------------------------------------------- | ----------------- |
| 缺少/無效的 Bearer 權杖或缺少 `CREATE_SHARE_LINK` 權限範圍 | 請求被拒絕（未授權）。       |
| 收件人清單長度 ≠ `quantity`                         | 明確的驗證錯誤；不會建立任何紀錄。 |
| 優惠未啟用、商家不可分享、或無效的 `offerId`                  | 驗證錯誤；不會建立任何紀錄。    |
| 缺少/無效的 `userCashBalanceId`，或提供多於一種資金來源       | 驗證錯誤；不會建立任何紀錄。    |

## 備註與限制

* **回傳的 URL 為託管目的地，而非短連結。** 內部也會以短連結服務包裝，但 API 回傳的是標準託管 URL（`/virtual-prepaid-card/{share_request_id}`）。請原樣分發該 URL。
* 即使綱要標示為選填，`userCashBalanceId` 在實務上為必填。
* **隱藏/內部欄位不屬於此 API。** 物件類型與卡片類型是固定的（`VIRTUAL_CARD` / `SINGLE_LOAD`），其他資金來源欄位尚未啟用；請勿傳送。
* **不支援託管型禮品卡連結。** 此 API 僅適用於虛擬卡。

## 下一步

<CardGroup cols={2}>
  <Card title="建立大量訂單" icon="layers" href="/features/create-bulk-order">
    一次發行多張卡片以利程式化分發。
  </Card>
</CardGroup>