開放式卡片總覽

先決條件： 具備 CREATE_SHARE_LINK 權限範圍的 Bearer 存取權杖。基本驗證會被拒絕。請聯絡你的業務代表以啟用存取。請參閱驗證。

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

運作方式

你產生連結

使用 generateVCShareLinks 指定優惠、卡片上限、數量、資金來源，以及傳遞方式。每個連結代表一張卡，皆有其個別上限，並由你指定的消費帳戶資助。

Fluz 為每個連結建立一筆分享請求

每個連結對應一筆分享請求（PENDING）與一個託管 URL。

連結被交付

使用 GENERATE_URL 時，你會取得可自行分發的 URL。使用 EMAIL 或 PHONE_NUMBER 時，Fluz 會為你將連結傳送給每位收件人。

收件人啟用並領取卡片

收件人開啟連結並以一次性驗證碼驗證手機號碼——無需下載 App、無需密碼。卡片上限會在領取時自你的消費帳戶扣除，而不是在產生連結時扣除。卡片不會在領取時自動顯示；顯示卡片時會提示收件人輸入其 PIN，若尚未設定 PIN，則需先建立。完整流程請見收件人體驗。

收件人僅成為該虛擬卡物件的授權使用者——他們不會取得你帳戶、餘額或任何其他卡片的存取權。傳送卡片流程圖

可用性與範圍

功能	狀態
單次加值虛擬卡	✅ 支援
單次使用虛擬卡	✅ 支援
可重複加值卡	❌ 不支援

e

透過 API 產生連結	✅ 支援	.
透過 CSV 匯入產生連結	❌ 即將推出
託管的「禮品卡」連結	❌ 不在範圍內（僅虛擬卡）
卡片分享連結物件類型為 `VIRTUAL_CARD`，卡片類型為 `SINGLE_LOAD`。

禮品卡： 儘管更廣泛的計畫以「虛擬卡與禮品卡」為架構，目前沒有託管的禮品卡領取流程。禮品卡餘額在此僅作為託管虛擬卡的_潛在資金來源_（規劃中，尚未啟用）。文件與開發請僅針對虛擬卡。

作業參考

ce

共有三個公開作業，皆受 CREATE_SHARE_LINK 權限範圍管制

作業	類型	目的
`generateVCShareLinks`	Mutation	建立一或多個託管虛擬卡連結
`getVCShareLinks`	Query	列出/檢視先前產生的連結
`deactivateVCShareLinks`	Mutation	停用（使失效）你所產生的連結
所有傳送卡片作業皆位於 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` 筆分享請求並回傳每筆請求的一個託管連結。

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

輸入欄位

欄位	類型	必填	說明
`cardLimit`	`Int!`	是	每張卡的消費上限（亦為加值金額），單位為整數貨幣。必須為不小於方案最低限額的整數。
`offerId`	`String!`	是	卡片綁定的商家優惠之 UUID v4。該優惠必須為啟用中，且其商家必須可分享。
`quantity`	`Int!`	是	要產生的連結數量。每個單位會建立一個獨立的託管 URL。
`shareMethod`	`ShareMethodType!`	是	識別收件人與交付連結的方式：`GENERATE_URL`、`EMAIL`、`PHONE_NUMBER`、`EXISTING_USER` 或 `REGISTER_USER`。
`userCashBalanceId`	`UUID`	是*	用於資助卡片的消費帳戶。在綱要中標為選填，但實務上必填——省略會驗證失敗。

s

`daysUntilExpiration`	`Int`	否	連結到期的天數。最少 1。若省略，預設為方案預設值（30 天）。此日期同時也會成為卡片的鎖定/凍結日期——請見到期與凍結。
`recipientListEmail`	`[String]`	條件式	當 `shareMethod = EMAIL` 時必填且不可為空，長度須等於 `quantity`。其他情況必須為空。
`recipientListPhone`	`[String]`	條件式	當 `shareMethod = PHONE_NUMBER` 時必填且不可為空，長度須等於 `quantity`。其他情況必須為空。
`recipientUserIds`	`[UUID]`	條件式	當 `shareMethod = EXISTING_USER` 時，需提供要綁定為收件人的已知 Fluz 使用者 ID。長度須等於 `quantity`。與 `recipientRegistrations` 互斥。
`recipientRegistrations`	`[ShareLinkRecipientRegistrationInput]`	條件式	當 `shareMethod = REGISTER_USER` 時，內嵌預先註冊負載——Fluz 會為每個項目建立或重用一個（無席位）占位使用者，之後再產生連結。長度須等於 `quantity`。與 `recipientUserIds` 互斥。
`usePrepaymentBalance`	`Boolean`	否	設定是否使用你的預付餘額作為額外資金來源。預設為 false。更多使用方式請參考：資金如何運作。
`useRewardsBalance`	`Boolean`	否	設定是否使用你的 Fluz 獎勵餘額作為額外資金來源。預設為 false。更多使用方式請參考：資金如何運作。

資金來源。 userCashBalanceId（屬於你—發送者—帳戶的消費帳戶）為主要且必填的資金來源。可選擇性將 usePrepaymentBalance 與/或 useRewardsBalance 設為 true，以便在消費帳戶於領取時不足以覆蓋全額時，讓 Fluz 退回使用你的預付或獎勵餘額。銀行帳戶與銀行卡片目前不支援作為資金來源。

收件人識別與交付方式（`shareMethod`）

值	行為	收件人欄位	建立卡片時間點

)

`GENERATE_URL`	Fluz 於回應中回傳託管 URL；你自行分發。	兩個名單欄位皆須為空/省略。	於領取時
`EMAIL`	Fluz 會寄送連結到各收件人的電子郵件。	必填 `recipientListEmail`；長度須等於 `quantity`。	於領取時
`PHONE_NUMBER`	Fluz 會以簡訊傳送連結到各收件人的手機。	必填 `recipientListPhone`；長度須等於 `quantity`。	於領取時
`EXISTING_USER`	連結自一開始即綁定到已知的 Fluz 使用者；僅該使用者可領取。透過該使用者檔案中已存在的聯絡管道交付。	必填 `recipientUserIds`；長度須等於 `quantity`。	立即，在產生時
`REGISTER_USER`	Fluz 為每個項目建立或重用一個占位使用者，並將連結綁定到該使用者，與 `EXISTING_USER` 相同。	必填 `recipientRegistrations`；長度須等於 `quantity`。	立即，在產生時

EXISTING_USER 與 REGISTER_USER 都會在 generateVCShareLinks 呼叫中建立虛擬卡，而不是延後到領取時才建立。完整的 EXISTING_USER 流程（包含如何先用 registerUser 註冊收件人）請見註冊與傳送。

驗證規則

cardLimit 必須為整數，且不小於方案最低限額。
offerId 必須是啟用中優惠、其商家可分享的有效 UUID v4。
quantity 必須為整數。
與 shareMethod 對應的收件人欄位（recipientListEmail、recipientListPhone、recipientUserIds 或 recipientRegistrations）其長度必須等於 quantity。若不相符會回傳明確錯誤，且不會建立任何紀錄。
recipientUserIds 與 recipientRegistrations 彼此互斥，且與名單式交付欄位互斥。
recipientUserIds 中的每個 ID 必須是有效且存在的 Fluz 使用者。
userCashBalanceId 為必填，且必須是發送者帳戶所擁有的有效 UUID v4。usePrepaymentBalance 與 useRewardsBalance 為選填的後援資金來源，可同時啟用。
無效的卡片類型或不合規的輸入會回傳明確錯誤且不會建立任何紀錄。

範例

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

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 1,
    "shareMethod": "EXISTING_USER",
    "recipientUserIds": ["f1320ac4-52dc-4c67-9e80-24e506b18450"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

對於 EXISTING_USER，請先註冊收件人（或直接使用既有使用者的 ID）——完整流程包含 registerUser 呼叫與回應處理，請見註冊與傳送。

回應

{
  "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} 形式。

回應僅回傳 URL。若要取得你剛建立之連結的批次 ID與顯示用 ID（供列出與停用時使用），請以狀態篩選呼叫 getVCShareLinks。

getVCShareLinks

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

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

輸入欄位

欄位	類型	說明

s

`shareObjectStatuses`	`[ShareObjectStatus]`	以狀態篩選：`PENDING`、`ISSUED`、`USED`、`EXPIRED`。	.
`shareRequestBatchIds`	`[String]`	僅回傳屬於這些批次的連結。
	`shareRequestDisplayIds`	`[String]`	僅回傳具有這些顯示用 ID 的連結。

建議流程。 第一次呼叫時，僅以 shareObjectStatuses 篩選。回應會提供 shareRequestBatchId 與 shareRequestDisplayId；後續呼叫（以及停用）時請用這些欄位精準篩選。

回應欄位（`GeneratedShareLink`）

欄位	類型	說明
`senderAppId`	`String`	產生該連結的應用/開發者應用程式。

)

`shareRequestBatchId`	`String`	一次呼叫中所產生之所有連結共用的批次識別碼。
`shareRequestDisplayId`	`String`	便於閱讀的每連結識別碼。
`shareObjectStatus`	`ShareObjectStatus`	`PENDING`、`ISSUED`、`USED` 或 `EXPIRED`。
`recipientEmail`	`String`	若以電子郵件交付，則為收件人 Email。
`recipientPhone`	`String`	若以簡訊交付，則為收件人電話。
`linkExpirationDate`	`DateTime`	連結到期/卡片凍結時間。
`virtualCardId`	`String`	領取後發行之虛擬卡 ID。
`linkUrl`	`String`	該連結的託管 URL。
`shareRequestDetails`	`ShareRequestDetails`	原始設定（卡片上限、優惠、數量、交付、資金）。
範例

By status

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

By batch

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

By display ID

{ "input": { "shareRequestDisplayIds": ["SR-000001", "SR-000002"] } }

By display ID

deactivateVCShareLinks

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

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

輸入欄位

欄位	類型	說明

s

`shareRequestBatchIds`	`[String]`	停用這些批次中的每個連結。	.
`shareRequestDisplayIds`	`[String]`	僅停用具有這些顯示用 ID 的連結。
			從 `getVCShareLinks` 取得批次 ID。

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

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

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

到期與凍結

連結的到期日具有雙重作用：

連結到期——在此日期之後，未被領取的連結將無法再被領取。
卡片凍結/鎖定日期——對於已發行的卡片，該日期為鎖定日期（當天結束）。之後卡片會被凍結且無法消費。
卡片有效期會對齊至凍結月份的月底（例如凍結日為 2026/6/15，卡片有效期為 2026/6/30）。
. 在產生時以 daysUntilExpiration 設定此視窗。若省略，則使用方案預設（30 天）。此日期也會顯示給收件人（通常作為「Valid until」日期）——請見收件人體驗。

狀態與錯誤參考

分享物件狀態

狀態	意義
`PENDING`	連結已產生，尚未被領取。

s

`ISSUED`	收件人已領取連結；虛擬卡已發行。	s
`USED`	已發行的卡片曾被使用。
`EXPIRED`	連結已到期或被停用；不可再領取。
關於當連結已到期、被撤銷或已被領取時，收件人所見的狀態，請見收件人端連結錯誤。常見 API 錯誤

成因	結果
缺少/無效的 Bearer 權杖，或缺少 `CREATE_SHARE_LINK` 權限範圍	請求被拒（未授權）。
收件人欄位（`recipientListEmail`、`recipientListPhone`、`recipientUserIds` 或 `recipientRegistrations`）長度 ≠ `quantity`	清楚的驗證錯誤；不會建立任何紀錄。
`recipientUserIds` 參照到不存在的 Fluz 使用者	驗證錯誤；不會建立任何紀錄。
優惠未啟用、商家不可分享，或 `offerId` 無效	驗證錯誤；不會建立任何紀錄。
缺少/無效的 `userCashBalanceId`	驗證錯誤；不會建立任何紀錄。

注意事項與限制

回傳的 URL 為託管目的地，非短連結。 內部會以短連結服務包裹，但 API 回傳的是標準託管 URL（/virtual-prepaid-card/{share_request_id}）。請照原樣分發該 URL。
儘管綱要標示為選填，userCashBalanceId 在實務上為必填。
隱藏/內部欄位不屬於本 API。 物件類型與卡片類型為固定值（VIRTUAL_CARD / SINGLE_LOAD）。銀行帳戶與銀行卡片資金尚未啟用；請勿傳送。usePrepaymentBalance 與 useRewardsBalance 是目前唯一支援的額外資金來源。
不支援託管的禮品卡連結。 本 API 僅適用於虛擬卡。

下一步

收件人體驗

當收件人開啟託管連結時所見的畫面，以及管理其卡片的規則。

註冊與傳送

使用 EXISTING_USER 先行註冊收件人並預先建立其卡片，而非在領取時才建立。

建立大量訂單

一次發行多張卡片以供程式化分發。

​運作方式

​可用性與範圍

​e

​作業參考

​ce

generateVCShareLinks

​輸入欄位

​s

​收件人識別與交付方式（shareMethod）

​)

​驗證規則

​範例

​回應

​getVCShareLinks

​輸入欄位

​s

​回應欄位（GeneratedShareLink）

​)

s

範例

​deactivateVCShareLinks

​輸入欄位

​s

​到期與凍結

​狀態與錯誤參考

​分享物件狀態

​s

s

常見 API 錯誤

​注意事項與限制

​下一步

收件人體驗

註冊與傳送

建立大量訂單

運作方式

可用性與範圍

e

作業參考

ce

輸入欄位

s

收件人識別與交付方式（`shareMethod`）

)

驗證規則

範例

回應

getVCShareLinks

輸入欄位

s

回應欄位（`GeneratedShareLink`）

)

deactivateVCShareLinks

輸入欄位

s

到期與凍結

狀態與錯誤參考

分享物件狀態

s

注意事項與限制

下一步