> ## 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 來建立一個或多個連結，然後用你喜歡的方式將這些連結交付給收件人——透過電子郵件、簡訊，或是回傳原始 URL 以便嵌入你自己的流程。當收件人開啟連結時，他們會進入由 Fluz 託管的頁面，完成身分驗證，並領取由你的帳戶資助的一次性加值虛擬卡。

<Info>
  **先決條件：** 需要具備 `CREATE_SHARE_LINK` 權限範圍的 Bearer 存取權杖，以及已啟用 Send Cards 的帳戶（`send_virtual_cards_enabled` 行銷活動旗標）。不接受基本驗證（Basic auth）。請聯絡你的業務代表以啟用存取權。請參閱 [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="你產生連結">
    以 offer、卡片額度、數量、資金來源與傳遞方式呼叫 `generateVCShareLinks`。每個連結代表一張擁有自己額度的卡片，資金來自你指定的消費帳戶。
  </Step>

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

  <Step title="連結被傳遞">
    使用 `GENERATE_URL` 時，你會拿回要自行分發的 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` 權限範圍，且你的帳戶須已啟用 Send Cards——否則每個作業都會回傳「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!`          | 是   | 該卡所綁定商家 offer 的 UUID v4。offer 必須為有效，且其商家必須可分享。                                                           |
| `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` 必須是 **有效** offer 的 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`              | 若以簡訊傳遞，則為收件人電話。                        |
| `linkExpirationDate`    | `DateTime`            | 連結到期 / 卡片鎖定時間。                         |
| `virtualCardId`         | `String`              | 一旦被領取後的虛擬卡 ID。                         |
| `linkUrl`               | `String`              | 該連結的託管 URL。                            |
| `shareRequestDetails`   | `ShareRequestDetails` | 原始設定（卡片額度、offer、數量、傳遞方式、資金）。           |

### 範例

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

## 到期與凍結

連結的到期日具備雙重意義：

* **連結到期**——在此日期之後，**未被領取**的連結將無法再被領取。
* **卡片凍結 / 鎖定日期**——對於已發行的卡片，此日期為鎖定日期（當天結束）。之後卡片將被凍結且無法消費。
* **卡片有效期限（expiry）** 將對齊至凍結日期所屬月份的月底（例如：凍結日為 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` 權限範圍   | 請求被拒（未授權）。        |
| 帳戶未啟用 Send Cards（`send_virtual_cards_enabled`） | 權限錯誤，並提示聯絡業務代表。   |
| 收件人清單長度 ≠ `quantity`                           | 清楚的驗證錯誤；不會建立任何紀錄。 |
| offer 無效、商家不可分享、或 `offerId` 無效                 | 驗證錯誤；不會建立任何紀錄。    |
| 缺少/無效的 `userCashBalanceId`，或提供多於一個資金來源         | 驗證錯誤；不會建立任何紀錄。    |

## 注意事項與限制

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

## 後續步驟

<CardGroup cols={2}>
  <Card title="產生分享連結" icon="link" href="/features/generate-share-links">
    `generateVCShareLinks` 的重點參考，若你只需要這部分即可。
  </Card>

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