数字钱包推送开卡（Push Provisioning）

使用 getCardProvisioningUrl 查询来铸造一个短的、一次性 URL——当在终端用户的手机上打开时，将在设备上启动 Fluz，并把给定优惠的虚拟卡添加到 Apple Pay（iOS）或 Google Pay（Android）。你可以以任意方式分发该 URL：二维码、短信、电子邮件，或应用内按钮。随后，Fluz 会处理从那里的钱包开卡流程。

适用场景

在任何你通常会把虚拟卡交给用户、并希望他们无需输入卡号就能将其添加到手机钱包的地方。典型流程包括：

在为用户创建卡片优惠后，在屏幕上展示二维码。
通过短信或电子邮件将 URL 发送给持卡人。
在你自己的移动应用中嵌入“添加到 Apple Pay / Google Pay”按钮。

先决条件： 终端用户的 OAuth 访问令牌，且包含 CREATE_VIRTUALCARD scope，以及一个为该用户创建的虚拟卡优惠（通过现有的优惠 API 创建）。

此查询不接受基本认证（client_id / client_secret）——必须使用用户上下文的 Bearer 令牌。

查询

query ProvisionCard($offerId: String!) {
  getCardProvisioningUrl(input: { offerId: $offerId, platform: IOS }) {
    url
    expiresAt
  }
}

输入

字段	类型	必填	说明
`offerId`	`String!` (UUIDv4)	是	要开卡的虚拟卡优惠。必须处于活动状态、符合令牌化资格，并且对该用户账户可访问。
`platform`	`ProvisioningPlatform`	否	关于用户将从哪里打开 URL 的提示。默认为 `IOS`。见下文——这并不会将 URL 锁定到单一平台。

`ProvisioningPlatform`

返回的 URL 具备平台感知：iOS 用户会自动获得 App Clip 体验，Android 用户会自动获得 Fluz 应用深链。platform 的取值仅影响当 URL 在 iOS 或 Android 设备之外（如桌面浏览器）被打开时的行为。

取值	桌面 / 未知设备回退
`IOS` (默认)	Apple App Clip 启动器
`ANDROID`	Fluz Android 深链
`OTHER`	Fluz Web 应用

选择与你预期 URL 将被打开的位置最匹配的取值。如不确定，保持为 IOS。

输出

字段	类型	说明
`url`	`String!`	要交付给用户的短链接。一次性使用。
`expiresAt`	`String!`	ISO-8601 时间戳。URL 在此时间后失效（≈ 创建后 5 分钟）。

示例

请求

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ getCardProvisioningUrl(input:{ offerId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "11111111-2222-3333-4444-555555555555" }
  }'

响应

{
  "data": {
    "getCardProvisioningUrl": {
      "url": "https://fluz.app.link/abc123XYZ",
      "expiresAt": "2026-05-26T17:42:11.000Z"
    }
  }
}

如何分发 URL

该 URL 是不透明的且不包含敏感数据——可安全用于二维码、短信、电子邮件或应用内界面。常见模式：

屏幕上的二维码——从 url 生成二维码并展示；用户用手机相机扫描。
短信 / 电子邮件——将链接直接发送到用户的手机或收件箱。
应用内深链——在你的移动应用中接一个打开 url 的按钮。

无论采用何种分发渠道，用户必须在移动设备上打开该 URL——钱包开卡流程在移动端完成。

有效期与重新签发

每次调用都会返回一个全新的、一次性 URL。
该 URL 在 expiresAt 前有效（≈ 5 分钟）。
如果用户未能及时操作，只需再次调用 getCardProvisioningUrl 以生成一个新的。没有单独的“刷新”端点。

错误处理

所有错误均以标准 Fluz GraphQL 错误结构返回，错误名称位于 extensions.code 中。

代码	含义	处理方式
`Arguments.INVALID`	`offerId` 不是有效的 UUID。	在你方校验输入。
`VirtualCard.OFFER_NOT_FOUND`	优惠不存在或已失效。	确认优惠 ID；必要时创建新优惠。
`VirtualCard.OFFER_NOT_ACCESSIBLE`	用户账户无资格使用该优惠（活动访问权限）。	呈现通用的“不可用”消息。
`VirtualCard.OFFER_NOT_AVAILABLE`	该优惠已被兑换为卡且该卡已不再有效。	不要用同一优惠重试；创建新的优惠。
`VirtualCard.OFFER_NOT_TOKENIZATION_ELIGIBLE`	该优惠的卡计划不支持钱包开卡。	不要为该卡计划提供“添加到钱包”。
`Auth.USER_REVOKED_DEVELOPER_ACCESS`	用户已撤销对你应用的 OAuth 访问。	让用户重新走 OAuth 授权流程。
`Auth.INVALID_SCOPE`	令牌不包含 `CREATE_VIRTUALCARD`。	在 OAuth 时请求该 scope。
`Generic.EXTERNAL_SERVICE_ERROR`	下游临时性问题。	重试——该调用可安全重复。

常见问题

这个 URL 会包含卡号吗？

不会。该 URL 仅携带短期有效的不透明查询 ID。一旦用户打开链接，凭据会在设备上安全交换。

同一个 URL 可以重复使用吗？

不可以。它是一次性的。每次需要触发该流程时都要生成一个新的。

如果用户在桌面端怎么办？

他们会落到你通过 platform 选择的回退方案（App Clip 启动器、Android 深链，或 Fluz Web 应用）。要完成钱包开卡，本质上仍需要他们在移动设备上打开该 URL。

针对 iOS 和 Android，我需要做不同处理吗？

不需要。同一个 URL 同样适用于两者——Fluz 会按设备自动路由。

后续步骤

发送卡片

通过电子邮件、短信或分享链接分发虚拟卡。

设置虚拟卡 PIN

在符合条件的卡片上预先设置 PIN，以便进行线下、需要 PIN 的交易。

​适用场景

​查询

​输入

​ProvisioningPlatform

​输出

​示例

​请求

​响应

​如何分发 URL

​有效期与重新签发

​错误处理

​常见问题

​后续步骤

发送卡片

设置虚拟卡 PIN

适用场景

查询

输入

`ProvisioningPlatform`

输出

示例

请求

响应

如何分发 URL

有效期与重新签发

错误处理

常见问题

后续步骤