> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

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

使用 `getCardProvisioningUrl` 查詢來鑄造一個短的、一次性使用的 URL；當最終使用者在手機上開啟時，會在裝置上啟動 Fluz，並將指定優惠對應的虛擬卡加入 Apple Pay（iOS）或 Google Pay（Android）。

你可以用任何方式傳遞該 URL：QR code、SMS、電子郵件，或應用內按鈕。從那之後，Fluz 會處理錢包佈建流程。

## 何時使用

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

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

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

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

## 查詢

```graphql theme={null}
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 分鐘）。 |

## 範例

### 請求

```bash theme={null}
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" }
  }'
```

### 回應

```json theme={null}
{
  "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`              | 下游暫時性問題。                   | 重試 — 呼叫可安全重覆。        |

## 常見問題

<AccordionGroup>
  <Accordion title="該 URL 會包含卡號嗎？">
    不會。該 URL 僅攜帶短期有效且不透明的查詢代號。當使用者開啟連結後，憑證會在裝置上以安全方式交換。
  </Accordion>

  <Accordion title="同一個 URL 可以重複使用嗎？">
    不行。它是一次性使用。每次需要啟動該流程時請產生新的連結。
  </Accordion>

  <Accordion title="如果使用者在桌面裝置上怎麼辦？">
    他們會進入你以 `platform` 所選的後備頁面（App Clip 啟動器、Android 深層連結，或 Fluz 網頁應用）。要使錢包佈建本身生效，他們最終需要在行動裝置上開啟該 URL。
  </Accordion>

  <Accordion title="我需要針對 iOS 與 Android 做不同處理嗎？">
    不需要。相同的 URL 適用於兩者 — Fluz 會自動依裝置路由。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="傳送卡片" icon="send" href="/features/send-cards">
    透過電子郵件、SMS，或分享連結，將虛擬卡發送給收件人。
  </Card>

  <Card title="設定虛擬卡 PIN" icon="key-round" href="/set-virtual-card-pin">
    在面對面、需要輸入 PIN 的交易前，先為符合資格的卡片設定 PIN。
  </Card>
</CardGroup>