產生分享連結

從你的平台產生託管虛擬卡連結（「開放式」Send Cards）。你呼叫一個 API 來建立一或多個連結，然後透過電子郵件、簡訊，或你自有的發放流程將這些連結傳送給收件者。當收件者開啟連結時，會進入由 Fluz 託管的啟用頁面，完成驗證，並領取由你的帳戶資助的一次性加值虛擬卡。

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

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

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

運作方式

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

驗證

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

POST https://<your-fluz-api-host>/api/v1/graphql
Authorization: Bearer <access_token>
Content-Type: application/json

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

{
  "scopes": ["CREATE_SHARE_LINK"]
}

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

操作項目

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

generateVCShareLinks

建立 quantity 個託管分享連結。

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 供你自行分發

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 3,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

範例：以電子郵件傳送連結給收件者

{
  "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"
  }
}

範例：以簡訊傳送連結給收件者

{
  "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"
  }
}

回應

{
  "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。

https://fluz.app/virtual-prepaid-card/{share_request_id}

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

getVCShareLinks

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

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，你可用於後續查詢或停用作業。

範例

{
  "input": {
    "shareObjectStatuses": ["PENDING", "ISSUED"]
  }
}

{
  "input": {
    "shareRequestBatchIds": ["ABC123", "XYZ789"]
  }
}

{
  "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 讓已產生的連結提前失效，例如當某個批次誤發，或需要撤銷未被領取的連結時。

mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}

輸入欄位

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

範例

{
  "input": {
    "shareRequestBatchIds": ["ABC123"]
  }
}

回應

回傳確認字串，例如：

3 share requests successfully deactivated!

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

收件者啟用體驗

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

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

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

到期與卡片凍結

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。

狀態參考

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

常見錯誤

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

注意事項與限制

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

發送前請注意：

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

後續步驟

Send Cards 概觀

完整的功能敘事——收件者流程、方案規則，以及完整的錯誤參照。

建立大量訂單

一次核發多張卡，便於程式化分發。

​運作方式

​驗證

​操作項目

​generateVCShareLinks

​輸入欄位

​傳遞方式

​驗證規則

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

​範例：以電子郵件傳送連結給收件者

​範例：以簡訊傳送連結給收件者

​回應

​getVCShareLinks

​輸入欄位

​範例

​回應欄位

​deactivateVCShareLinks

​輸入欄位

​範例

​回應

​收件者啟用體驗

​到期與卡片凍結

​方案規則

​狀態參考

​常見錯誤

​注意事項與限制

​後續步驟

Send Cards 概觀

建立大量訂單

運作方式

驗證

操作項目

generateVCShareLinks

輸入欄位

傳遞方式

驗證規則

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

範例：以電子郵件傳送連結給收件者

範例：以簡訊傳送連結給收件者

回應

getVCShareLinks

輸入欄位

範例

回應欄位

deactivateVCShareLinks

輸入欄位

範例

回應

收件者啟用體驗

到期與卡片凍結

方案規則

狀態參考

常見錯誤

注意事項與限制

後續步驟