數位錢包推送佈建（Push Provisioning）

使用 getCardProvisioningUrl 查詢來鑄造一個短的、一次性使用的 URL；當最終使用者在手機上開啟時，會在裝置上啟動 Fluz，並將指定優惠對應的虛擬卡加入 Apple Pay（iOS）或 Google Pay（Android）。你可以用任何方式傳遞該 URL：QR code、SMS、電子郵件，或應用內按鈕。從那之後，Fluz 會處理錢包佈建流程。

何時使用

在任何你通常會把虛擬卡交給使用者、並希望他們能在手機錢包中輕觸即可使用、而不需輸入卡號的地方。典型流程：

在為使用者建立卡片優惠後，於螢幕上顯示 QR code。
透過簡訊或電子郵件把 URL 傳給持卡人。
在你自己的行動應用中嵌入「加入 Apple Pay / Google Pay」按鈕。

先決條件： 具備包含 CREATE_VIRTUALCARD 權限範圍的最終使用者 OAuth 存取權杖，以及該使用者的虛擬卡優惠（透過既有的優惠 API 建立）。

這個查詢不接受基本認證（client_id / client_secret）— 必須使用使用者情境的 Bearer 權杖。

查詢

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

輸入

欄位	型別	必填	說明
`offerId`	`String!` (UUIDv4)	yes	要佈建的虛擬卡優惠。必須為有效、可代幣化（tokenization-eligible），且使用者帳戶可存取。
`platform`	`ProvisioningPlatform`	no	關於使用者將在哪裡開啟 URL 的提示。預設為 `IOS`。見下文 — 這不會將 URL 鎖定於某一平台。

`ProvisioningPlatform`

回傳的 URL 會識別平台：iOS 使用者自動獲得 App Clip 體驗，Android 使用者自動獲得 Fluz 應用的深層連結。platform 值僅影響當 URL 被在非 iOS 或 Android 裝置（例如桌面瀏覽器）開啟時的行為。

值	桌面／未知裝置後備行為
`IOS` (default)	Apple App Clip 啟動器
`ANDROID`	Fluz Android 深層連結
`OTHER`	Fluz 網頁應用

選擇最符合你預期 URL 會被開啟位置的值。若不確定，保持 IOS 即可。

輸出

欄位	型別	說明
`url`	`String!`	要傳遞給使用者的短連結。一次性使用。
`expiresAt`	`String!`	ISO-8601 時戳。URL 於此時間後失效（約建立後 5 分鐘）。

範例

請求

curl -X POST https://api.fluz.app/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 為不透明且不含敏感資料 — 你可以放心地以 QR code、SMS、電子郵件，或應用內 UI 呈現。常見模式：

螢幕上的 QR code — 由 url 產生 QR，顯示於畫面；使用者以手機相機掃描。
SMS / 電子郵件 — 直接將連結傳送到使用者的手機或收件匣。
應用內深層連結 — 在你的行動應用中連接一個按鈕以開啟 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 流程中請求該權限範圍。
`Generic.EXTERNAL_SERVICE_ERROR`	下游暫時性問題。	重試 — 呼叫可安全重覆。

常見問題

該 URL 會包含卡號嗎？

不會。該 URL 僅攜帶短期有效且不透明的查詢代號。當使用者開啟連結後，憑證會在裝置上以安全方式交換。

同一個 URL 可以重複使用嗎？

不行。它是一次性使用。每次需要啟動該流程時請產生新的連結。

如果使用者在桌面裝置上怎麼辦？

他們會進入你以 platform 所選的後備頁面（App Clip 啟動器、Android 深層連結，或 Fluz 網頁應用）。要使錢包佈建本身生效，他們最終需要在行動裝置上開啟該 URL。

我需要針對 iOS 與 Android 做不同處理嗎？

不需要。相同的 URL 適用於兩者 — Fluz 會自動依裝置路由。

下一步

傳送卡片

透過電子郵件、SMS，或分享連結，將虛擬卡發送給收件人。

設定虛擬卡 PIN

在面對面、需要輸入 PIN 的交易前，先為符合資格的卡片設定 PIN。

​何時使用

​查詢

​輸入

​ProvisioningPlatform

​輸出

​範例

​請求

​回應

​如何傳遞 URL

​存活時間與重新簽發

​錯誤處理

​常見問題

​下一步

傳送卡片

設定虛擬卡 PIN

何時使用

查詢

輸入

`ProvisioningPlatform`

輸出

範例

請求

回應

如何傳遞 URL

存活時間與重新簽發

錯誤處理

常見問題

下一步