Skip to main content
标准托管链接流程将所有步骤留给收件人：你生成一个链接，Fluz 只有在收件人打开链接、完成验证并认领后才会创建虚拟卡。 对于你已识别的收件人，本流程将其反转。你使用 registerUser 自行注册收件人的身份与账单地址，然后使用 generateVCShareLinks 并设置 shareMethod: EXISTING_USER 生成分享链接。Fluz 会在生成时点立即创建虚拟卡，而不是等到认领时，并将其绑定到该唯一收件人。链接仍按照常规方式发送与认领；只有卡片创建提前。资金仍在认领时扣取，与标准流程相同——优先从 userCashBalanceId 扣取，如果启用了预付款或奖励余额且消费账户不足，则回退至你的预付款或奖励余额。
何时选择此方式而非普通分享链接
  • 你已明确知道收件人是谁（通过用户 ID），并希望在通知他们之前卡片已创建完毕并可用，而不是等待他们去认领。
  • 你需要硬性保证只有目标收件人才能查看该链接——而不是“第一个点击的人”。
  • 你要发送给一批已知收件人，并希望在收件人与卡片之间实现确定性的 1:1 映射。

​
开始之前

你需要一个 Bearer 访问令牌。两个操作都不接受基本认证（Basic auth）。
用户注册默认不启用。 registerUser 是受限的变更操作——你的应用必须经 Fluz 明确批准后才能创建用户。请联系你的 Fluz 销售代表或客户经理以启用此功能。 来自未获批应用的调用会以 AUTH-0022 失败。如果收件人已拥有 Fluz 账户，你可以跳过注册，直接在 generateVCShareLinks 中使用其现有的 recipientUserIds。
参见身份验证了解如何生成带作用域的令牌。

​
流程

1

注册收件人

使用收件人的个人信息、账单地址，以及其对持卡人协议的接受来调用 registerUser。
acceptCardholderAgreement 必须为 true——否则注册会被拒绝。注册失败将以 HTTP 200 返回并携带 success: false，而非出现在 GraphQL 的 errors 数组中；请务必检查 success。保存返回的 userId——你将在下一步将其传入 generateVCShareLinks。返回的 accountId 与 billingAddressId 在此流程中不需要。
此步骤不会创建卡片或持卡人协议。 它只会创建用户记录、保存账单地址，并记录协议已被接受。虚拟卡及其与收件人的绑定会在下一步创建。
AUTH-0026 与 AUTH-0027 并非失败。 它们表示该人已拥有 Fluz 账户——这很常见，因为 Fluz 账户并不限定于你的应用。跳过注册，直接使用其现有的用户 ID。
完整参数参考：registerUser。
2

生成分享链接

使用 shareMethod: EXISTING_USER 调用 generateVCShareLinks，并将 recipientUserIds 设置为注册返回的用户 ID（或其他已知的 Fluz 用户 ID）。recipientUserIds 的长度必须等于 quantity。
对于多个收件人，请为每张卡传入一个用户 ID——顺序与生成的链接一一对应：
不要设置 recipientListEmail 和 recipientListPhone——对于该 shareMethod，收件人由 recipientUserIds 标识，且 Fluz 已为每位注册用户保存了联系方式。可选地将 usePrepaymentBalance 和/或 useRewardsBalance 设为 true，以便在认领时若 userCashBalanceId 余额不足，Fluz 可回退使用你的预付款或奖励余额：
With fallback funding
详情参见资金来源。
3

Fluz 创建卡片并分配链接

与标准流程不同，虚拟卡会在生成时点立即创建，而不是延后至认领。调用返回后，收件人会被分配到该卡及其链接。资金仍在认领时扣取，与标准流程相同——主要从 userCashBalanceId 扣取；若你设置了 usePrepaymentBalance / useRewardsBalance 且消费账户不足，则回退使用预付款或奖励余额。返回的每个链接都被锁定到其分配的收件人：只有该收件人的 Fluz 账户才能打开并认领。如果其他用户打开该 URL，他们在登录后会看到拒绝访问的状态，与任何已绑定的链接一致。
4

链接被投递

链接将与任何托管链接相同的方式发送给收件人——通过短信或电子邮件，使用 Fluz 为该用户备案的联系方式。之后收件人登录、完成 2FA，并进入其卡片页面。由于卡片已存在，认领时不会出现账单地址提示或等待发卡——此时进行资金扣取，与标准流程相同。

​
与标准流程的差异

标准流程参见发送开放式卡，完整认领体验参见收件人体验。

​
注意事项与限制

  • recipientUserIds 必须指向已存在的 Fluz 用户。 如果收件人尚未注册，请先使用 registerUser 注册（本流程），或使用标准托管链接流程让 Fluz 在认领时为其开户。
  • recipientUserIds 的长度必须等于 quantity。 不匹配会返回校验错误且不创建任何记录。
  • 卡片创建提前至生成时点——资金扣取则不变。 当你调用 generateVCShareLinks 时会创建虚拟卡对象并完成收件人绑定，但资金仍在认领时扣取，与标准流程一致：先从 userCashBalanceId 扣取；若设置了 usePrepaymentBalance / useRewardsBalance 且消费账户不足，则回退使用你的预付款或奖励余额。
  • 注册权限按应用与环境分别授予。 在预发环境获得的权限不会自动延续到生产环境。参见部署到生产。
  • 切勿在预发环境注册真实用户。 参见预发 vs. 线上。

​
下一步

发送开放式卡

标准流程——生成链接并在认领时由 Fluz 发卡。

收件人体验

收件人打开并认领托管链接时的所见即所得。

注册客户

registerUser 的完整参考，包括错误处理与回退模式。