> ## 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 來建立一或多個連結，然後透過電子郵件、簡訊，或你自有的發放流程將這些連結傳送給收件者。當收件者開啟連結時，會進入由 Fluz 託管的啟用頁面，完成驗證，並領取由你的帳戶資助的一次性加值虛擬卡。

<Info>
  **先決條件：** 具有 `CREATE_SHARE_LINK` 權限範圍的 Bearer 存取權杖，以及已啟用託管虛擬卡發送的帳戶。若你的帳戶未啟用，API 會回傳權限錯誤並指示你聯絡你的 Fluz 代表。
</Info>

<Note>
  **「託管」/「開放式」的意義。** 託管連結會導向由 Fluz 託管的啟用頁面。開放式表示收件者領取的是可於合格商家使用的網路虛擬卡，但需遵循你的方案規則。
</Note>

<Tip>
  在找完整功能說明——收件者體驗、方案規則，以及完整的狀態／錯誤參照？請參見[Send Cards 概觀](/features/send-cards)。本頁專注於三個分享連結操作的 API 參考。
</Tip>

## 運作方式

1. 你的平台以 offer、卡片限額、數量、資金來源與傳遞方式呼叫 `generateVCShareLinks`。
2. Fluz 會為每個請求的連結建立一個分享請求與一個託管 URL。
3. 傳遞方式取決於 `shareMethod`：
   * `GENERATE_URL`：Fluz 於 API 回應中回傳託管 URL，由你自行分發。
   * `EMAIL`：Fluz 會將連結寄送至每位收件者的電子郵件。
   * `PHONE_NUMBER`：Fluz 會將連結簡訊給每位收件者。
4. 收件者開啟託管連結、登入、完成驗證，並領取卡片。
5. Fluz 將從寄件者帳戶資助，向收件者核發一次性加值的虛擬卡。

## 驗證

所有 Send Cards 分享連結操作皆使用 Fluz GraphQL API。

```http theme={null}
POST https://<your-fluz-api-host>/api/v1/graphql
Authorization: Bearer <access_token>
Content-Type: application/json
```

你的存取權杖必須包含 `CREATE_SHARE_LINK` 權限範圍。

```json theme={null}
{
  "scopes": ["CREATE_SHARE_LINK"]
}
```

你的帳戶也必須啟用託管虛擬卡發送。若帳戶未啟用，API 會回傳權限錯誤，並指示你聯絡你的 Fluz 代表。

## 操作項目

| Operation                | Type     | Purpose        |
| ------------------------ | -------- | -------------- |
| `generateVCShareLinks`   | Mutation | 建立一或多個託管虛擬卡連結。 |
| `getVCShareLinks`        | Query    | 列出並檢視先前產生的連結。  |
| `deactivateVCShareLinks` | Mutation | 停用已產生的連結。      |

## generateVCShareLinks

建立 `quantity` 個託管分享連結。

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

### 輸入欄位

| Field                 | Type               | Required    | Description                                                             |
| :-------------------- | :----------------- | :---------- | :---------------------------------------------------------------------- |
| `cardLimit`           | `Int!`             | Yes         | 每張卡的消費上限與加值金額。必須為整數且符合方案最低限額。                                           |
| `offerId`             | `String!`          | Yes         | 虛擬卡 offer 的 UUID v4。該 offer 必須為啟用狀態且其商家必須可分享。                           |
| `quantity`            | `Int!`             | Yes         | 要產生的連結數量。Fluz 會為每個單位建立獨立的託管 URL。                                        |
| `shareMethod`         | `ShareMethodType!` | Yes         | 傳遞方式：`GENERATE_URL`、`EMAIL` 或 `PHONE_NUMBER`。                           |
| `userCashBalanceId`   | `UUID`             | Yes         | 用於為卡片提供資金的消費帳戶。即使 GraphQL 結構可能顯示為選填，實際上此欄位為必填。                          |
| `daysUntilExpiration` | `Int`              | No          | 連結有效天數。最少為 1。若省略，則使用方案預設值。產生的到期日也會在核發後成為卡片的鎖定／凍結日期。                     |
| `recipientListEmail`  | `[String]`         | Conditional | 當 `shareMethod` 為 `EMAIL` 時必填。長度必須等於 `quantity`。在其他傳遞方式下必須省略或留空。        |
| `recipientListPhone`  | `[String]`         | Conditional | 當 `shareMethod` 為 `PHONE_NUMBER` 時必填。長度必須等於 `quantity`。在其他傳遞方式下必須省略或留空。 |

### 傳遞方式

| `shareMethod`  | Behavior         | Recipient list rule                               |
| :------------- | :--------------- | :------------------------------------------------ |
| `GENERATE_URL` | 回傳託管 URL 供你自行分發。 | 請勿傳送 `recipientListEmail` 或 `recipientListPhone`。 |
| `EMAIL`        | 針對每位收件者寄送一封電子郵件。 | 傳送 `recipientListEmail`；長度必須等於 `quantity`。        |
| `PHONE_NUMBER` | 針對每位收件者發送一則簡訊。   | 傳送 `recipientListPhone`；長度必須等於 `quantity`。        |

### 驗證規則

* `cardLimit` 必須為整數且符合方案最低限額。
* `offerId` 必須是啟用且可分享之 offer 的有效 UUID v4。
* `quantity` 必須為整數。
* 使用 `EMAIL` 或 `PHONE_NUMBER` 時，收件者清單長度必須等於 `quantity`。
* `userCashBalanceId` 必須是寄件者帳戶所擁有的有效消費帳戶。
* 請勿包含多個資金來源。
* 無效或格式錯誤的請求將驗證失敗，且不會建立任何分享連結。

### 範例：產生 URL 供你自行分發

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

```json 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 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 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"
  }
}
```

### 回應

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

```text theme={null}
https://fluz.app/virtual-prepaid-card/{share_request_id}
```

API 會回傳託管目的地 URL。若 Fluz 同時在內部建立了短網址包裝，該短網址不會由此 API 回傳。

## getVCShareLinks

使用 `getVCShareLinks` 來列出已產生的連結、取得批次與顯示 ID、檢視傳遞目標，以及查詢狀態。

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

### 輸入欄位

| Field                    | Type                  | Description                                  |
| :----------------------- | :-------------------- | :------------------------------------------- |
| `shareObjectStatuses`    | `[ShareObjectStatus]` | 依狀態過濾：`PENDING`、`ISSUED`、`USED` 或 `EXPIRED`。 |
| `shareRequestBatchIds`   | `[String]`            | 只回傳這些批次中的連結。                                 |
| `shareRequestDisplayIds` | `[String]`            | 只回傳具有這些顯示 ID 的連結。                            |

第一次查詢時，請以 `shareObjectStatuses` 過濾。回應中會包含 `shareRequestBatchId` 與 `shareRequestDisplayId`，你可用於後續查詢或停用作業。

### 範例

```json theme={null}
{
  "input": {
    "shareObjectStatuses": ["PENDING", "ISSUED"]
  }
}
```

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

```json theme={null}
{
  "input": {
    "shareRequestDisplayIds": ["SR-000001", "SR-000002"]
  }
}
```

### 回應欄位

| Field                   | Type                  | Description           |
| :---------------------- | :-------------------- | :-------------------- |
| `senderAppId`           | `String`              | 產生該連結的應用程式。           |
| `shareRequestBatchId`   | `String`              | 同一生成請求所建立連結所共用的批次 ID。 |
| `shareRequestDisplayId` | `String`              | 個別分享請求的人性化顯示 ID。      |
| `shareObjectStatus`     | `ShareObjectStatus`   | 分享請求的目前狀態。            |
| `recipientEmail`        | `String`              | 以電子郵件傳遞時的收件者電子郵件。     |
| `recipientPhone`        | `String`              | 以簡訊傳遞時的收件者電話號碼。       |
| `linkExpirationDate`    | `DateTime`            | 連結到期日與卡片鎖定／凍結日期。      |
| `virtualCardId`         | `String`              | 連結被領取後所核發的虛擬卡 ID。     |
| `linkUrl`               | `String`              | 分享請求的託管 URL。          |
| `shareRequestDetails`   | `ShareRequestDetails` | 原始的生成設定。              |

## deactivateVCShareLinks

使用 `deactivateVCShareLinks` 讓已產生的連結提前失效，例如當某個批次誤發，或需要撤銷未被領取的連結時。

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

### 輸入欄位

| Field                    | Type       | Description       |
| :----------------------- | :--------- | :---------------- |
| `shareRequestBatchIds`   | `[String]` | 停用這些批次中的所有連結。     |
| `shareRequestDisplayIds` | `[String]` | 僅停用具有這些顯示 ID 的連結。 |

### 範例

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

### 回應

回傳確認字串，例如：

```text theme={null}
3 share requests successfully deactivated!
```

停用連結會防止未被領取的連結再被領取。若卡片已經核發，請使用適當的卡片生命週期控制來管理該卡。

## 收件者啟用體驗

當收件者開啟託管連結，他們會被帶到由 Fluz 託管的啟用頁面。

1. 收件者開啟託管虛擬卡連結。
2. 收件者透過 Fluz 的驗證流程登入或建立帳戶。
3. 既有使用者在查看或領取卡片前需完成 2FA。
4. 若收件者尚未提供帳單地址，系統會提示新增。線上消費需要帳單地址。
5. 若卡片尚未核發，收件者需設定 PIN 碼。
6. Fluz 將虛擬卡核發給收件者。
7. 核發後，收件者可查看卡片詳情與活動紀錄。

若同一位使用者開啟他們已領取的連結，仍可查看其卡片詳情。若不同使用者開啟已被他人領取的連結，在驗證後會顯示拒絕存取的狀態。

## 到期與卡片凍結

`daysUntilExpiration` 決定託管連結的有效期間。

產生的到期日用於以下兩種相關行為：

* 在領取前：到期日之後，連結將無法再被領取。
* 在領取後：到期日會成為卡片的鎖定／凍結日期。該日期之後，已核發的卡片會被凍結且無法再消費。

若省略 `daysUntilExpiration`，將使用方案預設值。

## 方案規則

方案規則可能依合作夥伴而異。請與你的 Fluz 代表確認你的方案最終設定。

| Rule                            | Default / behavior                                          |
| :------------------------------ | :---------------------------------------------------------- |
| Funding source                  | 寄件者的消費帳戶。                                                   |
| Daily account spend limit       | 每日 \$250,000，除非你的方案有自訂上限。                                   |
| Restaurant transaction buffer   | 餐廳交易會套用 25% 緩衝。                                             |
| Restricted merchants/categories | 可能適用特定於方案的限制。                                               |
| Recipient support               | 1-888-360-6660 或 [humans@fluz.app](mailto:humans@fluz.app)。 |

## 狀態參考

| Status    | Meaning          |
| :-------- | :--------------- |
| `PENDING` | 已產生連結且尚未被領取。     |
| `ISSUED`  | 收件者已領取連結並核發了虛擬卡。 |
| `USED`    | 已核發的卡片已有使用紀錄。    |
| `EXPIRED` | 連結已到期或已被停用。      |

## 常見錯誤

| Cause                       | Result         |
| :-------------------------- | :------------- |
| 缺少或無效的 Bearer 權杖            | 請求被拒絕。         |
| 缺少 `CREATE_SHARE_LINK` 權限範圍 | 請求被拒絕。         |
| 帳戶未啟用託管卡片發送                 | 權限錯誤。          |
| 收件者清單長度不等於 `quantity`       | 驗證錯誤；不會建立任何連結。 |
| offer 為停用或不可分享              | 驗證錯誤；不會建立任何連結。 |
| 缺少或無效的 `userCashBalanceId`  | 驗證錯誤；不會建立任何連結。 |
| 提供了多個資金來源                   | 驗證錯誤；不會建立任何連結。 |

## 注意事項與限制

* 此 API 僅適用於託管虛擬卡。不支援託管禮品卡連結。
* API 回傳的是託管目的地 URL，而非短網址。
* `userCashBalanceId` 在實務上為必填。
* 本階段物件類型與卡片類型為固定，且不應在公開 API 請求中提供。

<Warning>
  **發送前請注意：**

  * 若你的資金來源在收件者領取卡片時餘額不足，核發將失敗。請確保你的餘額充足。
  * `recipientListPhone` 中的電話號碼必須為不含空格的字串，且開頭必須包含國碼——例如 `+18883606660`，其中 `+1` 為國碼。
</Warning>

## 後續步驟

<CardGroup cols={2}>
  <Card title="Send Cards 概觀" icon="send" href="/features/send-cards">
    完整的功能敘事——收件者流程、方案規則，以及完整的錯誤參照。
  </Card>

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