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

# 傳遞方式

> 將開放式卡片交到收件者手中的四種方式——以及為此你需要了解多少。

<Info>
  **重點摘要：你不需要知道任何關於收件者的資訊就能產生卡片。**

  只有當你希望由 *Fluz* 負責傳遞時，才需要收件者的聯絡資料。若由你自行傳遞連結，你只需提供卡片限額、優惠與資金帳戶——不需要其他資訊。收件者會在託管頁面上自行填寫資料。
</Info>

## 選擇你的方式

<Steps>
  <Step title="要由 Fluz 傳遞連結，還是由你來？">
    若你自行傳遞——透過你自己的 Email、你自己的簡訊、App 內、入口網站，或將 URL 交給下游客戶——使用 **`GENERATE_URL`**。不需提供收件者資料。
  </Step>

  <Step title="若由 Fluz 傳遞，要用哪種方式？">
    Email（`EMAIL`）或簡訊（`PHONE_NUMBER`）。你需為每張卡提供一個地址或號碼。
  </Step>

  <Step title="你是否已持有收件者的完整身分資訊？">
    若是——且你希望收件者完全略過資料輸入——請向你的 Fluz 窗口洽詢 **預先填入式註冊**。此為受控選項，不屬於標準的 `generateVCShareLinks` 流程。
  </Step>
</Steps>

## 四種選項一覽

| # | 選項                | `shareMethod`  | 你提供給 Fluz 的內容  | 誰負責傳遞連結 | 收件者需要輸入什麼  |
| - | ----------------- | -------------- | -------------- | ------- | ---------- |
| 1 | **產生連結**          | `GENERATE_URL` | 無需提供收件者資訊      | **你**   | 他們自行填寫     |
| 2 | **Fluz 寄送 Email** | `EMAIL`        | 每張卡一個 Email 地址 | Fluz    | 他們自行填寫     |
| 3 | **Fluz 傳送簡訊**     | `PHONE_NUMBER` | 每張卡一個電話號碼      | Fluz    | 他們自行填寫     |
| 4 | **預先填入式註冊**       | 受控——聯絡你的窗口     | 完整的收件者身分資訊     | 你或 Fluz | 無需輸入——僅需領取 |

<Note>
  選項 1–3 都是同一個 mutation 上 `shareMethod` 欄位的三個值。彼此切換只需改一行——你不是在整合三個不同的 API。
</Note>

## 選項 1 — 產生連結，由你傳遞

**大多數合作夥伴都選這個。** 你呼叫 API，取得一組 URL 陣列，接著可任意處理：用你自己的系統寄信、發簡訊、放進客戶入口網站，或交給下游客戶，再由他們分送給最終使用者。

Fluz 不會向任何人寄送任何東西。對於這些連結，我們沒有任何收件者聯絡資料，因為你從未提供給我們。

```json Generate URLs theme={null}
{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 1,
    "daysUntilExpiration": 30,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}
```

```json Response theme={null}
{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1"
      ]
    }
  }
}
```

<Warning>
  使用 `GENERATE_URL` 時，`recipientListEmail` 與 `recipientListPhone` 必須**留空或省略**。在 `GENERATE_URL` 下同時送出收件者清單會導致驗證錯誤，且不會建立任何紀錄。
</Warning>

<Tip>
  將 `quantity` 設為大於 1，可在一次呼叫中鑄造一批。你會得到每單位一個獨立 URL，而且每個 URL 僅能被認領一次。請依原樣分發這些 URL——不要重寫或再次縮網址。
</Tip>

## 選項 2 — 由 Fluz 寄送 Email 連結

你為每張卡提供一個 Email，Fluz 會寄出 Email。收件者點擊後會進入與選項 1 相同的託管頁面，並在該處自行輸入資料。

當你已持有收件者 Email，且不想自行建立傳遞流程時可使用此方法。

```json Email theme={null}
{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "EMAIL",
    "recipientListEmail": ["mike.bennett@example.com", "dana.ruiz@example.com"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}
```

<Warning>
  `recipientListEmail` 的長度**必須等於** `quantity`。不一致將回傳驗證錯誤，且不會建立任何紀錄——不會產生部分批次。
</Warning>

## 選項 3 — 由 Fluz 傳送簡訊連結

與選項 2 類似，但透過 SMS。你需以 E.164 格式提供每張卡一個電話號碼。Fluz 會發送簡訊；在此路徑上 Fluz **不會**另外寄送 Email。

```json SMS theme={null}
{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": ["+12125550101", "+12125550102"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}
```

<Warning>
  `recipientListPhone` 的長度必須等於 `quantity`，且兩個清單互斥——請送出與 `shareMethod` 相符的清單，並將另一個留空。
</Warning>

## 選項 4 — 預先填入式註冊

有些合作夥伴會希望提供更高端的體驗，讓收件者完全不必輸入任何資料。在此模式中，你會將卡片註冊所需的身分資訊傳給 Fluz，而收件者唯一要做的就是開啟連結並領取卡片。

這是**受控選項**，不屬於標準的 `generateVCShareLinks` 輸入內容。若你的專案需要此功能，請與 Fluz 客戶團隊洽談——因為你會代表尚未與 Fluz 互動的人提供個人資訊，這在你方會帶來額外的資料處理與合規義務。

<Note>
  僅在你確實持有經驗證的收件者身分資料時才選擇此法。若你只是為了避免向收件者索取資訊而傾向選項 4，幾乎可以確定選項 1 才是你真正需要的。
</Note>

## 收件者會做什麼

在選項 1–3 之間完全相同。無論由誰傳遞，連結都會前往相同的託管頁面：

<Steps>
  <Step title="開啟連結">
    無需下載 App、無需 Fluz 帳號、無需密碼。
  </Step>

  <Step title="以手機驗證">
    一次性驗證碼用來確認持有連結的人。
  </Step>

  <Step title="輸入卡片資料">
    收件者提供卡片所需的資料。此階段不會要求輸入 PIN。
  </Step>

  <Step title="領取、揭露、並消費">
    卡片資金會在收件者**領取時**自你的消費帳戶撥款，而非在產生連結時。收件者將成為該張卡片物件的授權使用者——不包含你帳戶上的其他任何東西。卡片在領取後不會自動揭露：揭露時會提示收件者輸入其 PIN，或若尚未設定則先建立 PIN。
  </Step>
</Steps>

完整流程與當連結過期、被撤銷或已被領取時的狀態，請參考[收件者體驗](/features/open-loop-cards/open-loop-cards-recipient-experience)。

## 常見疑惑

<AccordionGroup>
  <Accordion title="我們必須預先填入收件者資訊嗎？">
    不需要。那是對 API 參考文件的常見誤讀。收件者欄位是為了**讓 Fluz 能代你傳遞**——它們不是卡片發行的輸入項。使用 `GENERATE_URL` 時你完全不會送出任何收件者資料。
  </Accordion>

  <Accordion title="每個請求都必須包含 Email 地址嗎？">
    不必。只有在 `shareMethod = EMAIL` 時才**必須**提供 `recipientListEmail`。在 `GENERATE_URL` 與 `PHONE_NUMBER` 下，它必須為空。
  </Accordion>

  <Accordion title="我們把連結交給客戶，再由他們轉交給最終使用者。可行嗎？">
    可以——這正是 `GENERATE_URL` 的使用模式。此 URL 為持有人式：誰先開啟並完成驗證，誰就領取該卡。請將連結視為敏感資訊，透過你信任的通道傳遞。
  </Accordion>

  <Accordion title="我可以從入口網站產生測試連結嗎？">
    目前不行。連結產生僅支援 API。請使用具有 `CREATE_SHARE_LINK` 權限範圍的 Staging 權杖在測試環境進行測試——參見[Staging 與正式環境](/docs/staging-vs-live-environment)。
  </Accordion>

  <Accordion title="之後可以更換方式嗎？">
    可以。`shareMethod` 是針對每次呼叫設定，不是針對帳戶。你完全可以先產生一批 URL，再讓 Fluz 寄送下一批。
  </Accordion>
</AccordionGroup>

## 所有方式的共通需求

| 需求 | 詳細說明                                                       |
| -- | ---------------------------------------------------------- |
| 驗證 | 具備 `CREATE_SHARE_LINK` 權限範圍的 Bearer 存取權杖。Basic auth 會被拒絕。  |
| 撥款 | `userCashBalanceId`——你自己帳戶上的消費帳戶。雖於 schema 標示為選填，但實務上等同必填。 |
| 優惠 | `offerId` 必須為可分享商家的有效優惠。                                   |
| 到期 | `daysUntilExpiration` 預設為 30。此日期同時也是卡片的凍結日期。               |

## 下一步

<CardGroup cols={2}>
  <Card title="Open Loop Cards Overview" icon="credit-card" href="/features/open-loop-cards/send-open-loop-cards">
    產生、列出與停用連結的完整操作參考。
  </Card>

  <Card title="Recipient Experience" icon="user" href="/features/open-loop-cards/open-loop-cards-recipient-experience">
    收件者所見內容，以及其卡片所適用的規則。
  </Card>
</CardGroup>