开放式卡片概览

先决条件： 一个携带 CREATE_SHARE_LINK 范围的 Bearer 访问令牌。Basic auth 会被拒绝。联系你的销售代表以开通权限。参见 Authentication。

“托管”/“开放式”的含义。 托管链接指向 Fluz 托管的激活页面。开放式 意味着生成的虚拟卡是一张网络卡（Visa/Mastercard 风格），可在多家商户消费，但需遵循你项目的规则——而非单品牌的封闭式礼品卡。

工作原理

你生成链接

使用 generateVCShareLinks，传入 offer、卡片限额、数量、资金来源和投递方式。每个链接代表一张卡片，拥有各自的限额，并从你指定的消费账户出资。

Fluz 为每个链接创建一个分享请求

每个链接映射到一个分享请求（PENDING）和一个托管 URL。

链接被投递

使用 GENERATE_URL 时，你会拿回 URL 自行分发。使用 EMAIL 或 PHONE_NUMBER 时，Fluz 会为你把链接投递给每位收件人。

收件人激活并领取卡片

收件人打开链接并用一次性验证码验证手机号——无需下载 App、无需密码。卡片限额会在领取时从你的消费账户中扣划，而不是在生成链接时。卡片在领取后不会自动展示；展示卡片会提示收件人输入其 PIN，若尚未设置则先创建。完整流程见 Recipient Experience。

收件人仅成为该虚拟卡对象的授权用户——他们无法访问你的账户、余额或任何其他卡片。发送卡片流程图

可用性与范围

能力	状态
一次性充值虚拟卡	✅ 支持
一次性使用虚拟卡	✅ 支持
可重复充值卡	❌ 不支持

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!`	是	卡片绑定的商户 offer 的 UUID v4。该 offer 必须处于活跃状态，其商户必须可分享。
`quantity`	`Int!`	是	要生成的链接数量。每个数量单位会创建一个独立的托管 URL。
`shareMethod`	`ShareMethodType!`	是	如何识别收件人及如何投递链接：`GENERATE_URL`、`EMAIL`、`PHONE_NUMBER`、`EXISTING_USER` 或 `REGISTER_USER`。
`userCashBalanceId`	`UUID`	是*	用于为卡片出资的消费账户。在 schema 中标记为可选，但实际必填——省略会导致校验失败。

s

`daysUntilExpiration`	`Int`	否	链接到期天数。最小 1。若省略，默认为项目默认值（30 天）。此日期也会成为卡片的锁定/冻结日期——参见 Expiration & freeze。
`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。其使用方式详见：How funding works。
`useRewardsBalance`	`Boolean`	否	设置是否将你的 Fluz 奖励余额作为附加资金来源。默认 false。其使用方式详见：How funding works。

资金来源。 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 注册收件人）见 Register & Send。

校验规则

cardLimit 必须为整数，且不小于项目最小值。
offerId 必须是活跃 offer 的有效 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）——完整流程见 Register & Send，包括 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`	若通过邮件投递，则为收件人邮箱。
`recipientPhone`	`String`	若通过短信投递，则为收件人手机号。
`linkExpirationDate`	`DateTime`	链接过期 / 卡片冻结时间。
`virtualCardId`	`String`	被领取后发放的虚拟卡 ID。
`linkUrl`	`String`	该链接的托管 URL。
`shareRequestDetails`	`ShareRequestDetails`	原始配置（卡片限额、offer、数量、投递、资金）。
示例

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 天）。此日期会展示给收件人（通常为“有效期至”）——参见 Recipient Experience。

状态与错误参考

分享对象状态

状态	含义
`PENDING`	链接已生成，尚未被领取。

s

`ISSUED`	收件人已领取链接；已发放虚拟卡。	s
`USED`	已发卡片已被使用。
`EXPIRED`	链接已过期或被停用；不可再领取。
收件人在链接已过期、被撤销或已被他人领取时看到的状态，参见 Recipient-facing link errors。常见 API 错误

原因	结果
缺失/无效的 Bearer 令牌或缺少 `CREATE_SHARE_LINK` 范围	请求被拒（未授权）。
收件人字段（`recipientListEmail`、`recipientListPhone`、`recipientUserIds` 或 `recipientRegistrations`）长度 ≠ `quantity`	明确的校验错误；不创建任何记录。
`recipientUserIds` 引用不存在的 Fluz 用户	校验错误；不创建任何记录。
非活跃 offer、不可分享的商户或无效的 `offerId`	校验错误；不创建任何记录。
缺失/无效的 `userCashBalanceId`	校验错误；不创建任何记录。

注意事项与限制

返回的 URL 是托管目标，而非短链。 在内部，链接也会被短链服务包装，但 API 返回规范的托管 URL（/virtual-prepaid-card/{share_request_id}）。请按原样分发该 URL。
即使 schema 标记为可选，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

注意事项与限制

下一步