生成分享链接

从你的平台生成托管虚拟卡链接（“开放环”发送卡）。你调用一个 API 来创建一个或多个链接，然后通过电子邮件、短信，或你自己的分发流程将这些链接发送给收件人。收件人打开链接后，会进入由 Fluz 托管的激活页面，完成验证，并领取一张由你的账户出资的一次性充值虚拟卡。

先决条件： 一个带有 CREATE_SHARE_LINK 范围的 Bearer 访问令牌，以及已启用托管虚拟卡发送功能的账户。若你的账户未启用，该 API 将返回权限错误并指引你联系你的 Fluz 代表。

“托管”/“开放环”含义。 托管链接会指向由 Fluz 托管的激活页面。开放环表示收件人领取的是网络虚拟卡，可依据你的项目规则在合格商户处使用。

需要完整功能说明——收件人流程、项目规则，以及完整的状态/错误参考？参见发送卡概览。本页是针对三个分享链接操作的聚焦 API 参考。

工作原理

你的平台调用 generateVCShareLinks，传入优惠、卡限额、数量、资金来源和交付方式。
Fluz 为每个请求的链接创建一个分享请求和一个托管 URL。
交付方式取决于 shareMethod：
- GENERATE_URL：Fluz 在 API 响应中返回托管 URL，由你自行分发。
- EMAIL：Fluz 向每位收件人发送其链接邮件。
- PHONE_NUMBER：Fluz 向每位收件人发送其链接短信。
收件人打开托管链接，登录、完成验证并领取该卡。
Fluz 向收件人签发一次性充值虚拟卡，资金来自发送方账户。

认证

所有发送卡分享链接操作都使用 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	虚拟卡优惠的 UUID v4。该优惠必须为激活状态且其商户可分享。
`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 必须是处于激活且可分享优惠的有效 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`	校验错误；不会创建任何链接。
不活跃或不可分享的优惠	校验错误；不会创建任何链接。
缺少或无效的 `userCashBalanceId`	校验错误；不会创建任何链接。
提供了多个资金来源	校验错误；不会创建任何链接。

备注与限制

此 API 仅适用于托管虚拟卡。不支持托管礼品卡链接。
API 返回托管目标 URL，而非短链接。
userCashBalanceId 在实践中是必填项。
本阶段对象类型和卡类型是固定的，不应在公共 API 请求中提供。

发送前须知：

若收件人在领取卡片时你的资金来源余额不足，发卡将失败。请确保余额充足。
recipientListPhone 中的电话号码必须为无空格的字符串，并且必须在开头包含国家代码——例如 +18883606660，其中 +1 为国家代码。

功能

生成分享链接

工作原理

认证

操作

generateVCShareLinks

输入字段

交付方式

校验规则

示例：生成 URL 以供你自行分发

示例：向收件人发送邮件链接

示例：向收件人发送短信链接

响应

getVCShareLinks

输入字段

示例

响应字段

deactivateVCShareLinks

输入字段

示例

响应

收件人激活体验

到期与卡片冻结

项目规则

状态参考

常见错误

备注与限制

后续步骤

发送卡概览

创建批量订单

​工作原理

​认证

​操作

​generateVCShareLinks

​输入字段

​交付方式

​校验规则

​示例：生成 URL 以供你自行分发

​示例：向收件人发送邮件链接

​示例：向收件人发送短信链接

​响应

​getVCShareLinks

​输入字段

​示例

​响应字段

​deactivateVCShareLinks

​输入字段

​示例

​响应

​收件人激活体验

​到期与卡片冻结

​项目规则

​状态参考

​常见错误

​备注与限制

​后续步骤

发送卡概览

创建批量订单

工作原理

认证

操作

generateVCShareLinks

输入字段

交付方式

校验规则

示例：生成 URL 以供你自行分发

示例：向收件人发送邮件链接

示例：向收件人发送短信链接

响应

getVCShareLinks

输入字段

示例

响应字段

deactivateVCShareLinks

输入字段

示例

响应

收件人激活体验

到期与卡片冻结

项目规则

状态参考

常见错误

备注与限制

后续步骤