--- title: "產品" description: "了解如何透過 Product API (產品 API) 管理和存取您的虛擬物品和組合包。" source: "https://docs.tokenz.one/zh-TW/v2/product" api_version: "v2" locale: "zh-TW" version_status: "current" docs_stage: "prod" --- # 產品 > **搶先體驗**：Product API 目前處於搶先體驗階段。我們正在開發更多功能並擴大支援範圍。部分功能有限制，或可能有所變更。請在用於正式環境前充分測試整合。 了解如何透過 Product API (產品 API) 管理和存取您的虛擬物品和組合包。 Product API 是一個內容管理系統，允許商家管理他們的虛擬物品並建立組合包。API 提供對您的產品目錄的安全存取，支援分頁和篩選。每個產品都以單一貨幣定價，而結帳時支援多種支付貨幣。 您可以檢索產品資訊以在店面中顯示，管理庫存，並以您偏好的貨幣設置價格。 **金額格式：** API 中所有貨幣值（如 `price` 欄位）均以各貨幣的最小單位表示。請參閱[支援的貨幣](https://docs.tokenz.one/zh-TW/v2/checkout/currency)以了解每種貨幣的確切編碼。 ## 概述 產品系統由兩個主要組件組成： - **虛擬物品**：具有名稱、描述、圖片和定價的個人數位產品 - **組合包**：以組合包價格一起銷售的虛擬物品集合 產品支援單一貨幣定價和豐富的媒體附件。API 包括分頁和篩選功能。雖然每個產品都有一個基礎貨幣，但客戶可以在結帳時使用他們的當地貨幣支付。 ## 產品生命週期 1. **產品建立**：虛擬物品和組合包在 Tokenz Dashboard (後台) 中建立和設定 2. **API 存取**：您的應用程式使用 Product API 透過篩選和分頁檢索產品資料 3. **顯示**：產品在您的店面中顯示適當的定價 4. **整合**：產品資料與 Checkout Session 整合，用於購買流程 ```mermaid sequenceDiagram; autonumber; participant M as 商家應用程式; participant T as Product API; participant DB as 產品資料庫; %% 1 ── 請求產品目錄; M->>T: GET /v2/product/virtual-items; T->>DB: 查詢虛擬物品; DB-->>T: 回傳產品資料; T-->>M: 分頁產品清單; %% 2 ── 請求特定產品詳情; M->>T: GET /v2/product/virtual-items/{id}; T->>DB: 查詢特定物品; DB-->>T: 回傳詳細產品; T-->>M: 完整產品詳情; %% 3 ── 與結帳整合; M->>M: 客戶選擇產品; M->>T: 使用產品建立 Checkout Session; T-->>M: 結帳工作階段已建立; ``` ## API 呼叫範例 ### 列出虛擬物品 使用可選的篩選和排序檢索虛擬物品的分頁清單。 ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/virtual-items' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` 支援以下查詢參數： ### 查詢參數 #### 分頁 - `limit`: 回傳的項目數量（最大 100，預設 20） - `offset`: 分頁跳過的項目數量 #### 篩選 - `sku`: 按 SKU 篩選（完全匹配） - `category`: 按類別篩選 #### 排序 虛擬物品和組合包支援以下排序： - `name_asc` / `name_desc`: 按名稱排序 - `sku_asc` / `sku_desc`: 按 SKU 排序 - `created_asc` / `created_desc`: 按建立日期排序（預設：`created_desc`） ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/virtual-items?limit=10&offset=0&sku=gold-ring-350&sort=name_asc' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **回應：** ```json { "data": [ { "id": "virtualitem_YJoSoHrd9R1", "sku": "gold-ring-350", "label": { "en_US": "Gold Ring" }, "description": { "en_US": "" }, "images": [ { "id": "3ZUJBfy7M99jRh0YglPUQv", "fileName": "gold-ring.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png", "width": 240, "height": 240 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 350, "currency": "JPY" } ], "taxCategory": "DIGITAL_GOODS_AND_SERVICES", "createdAt": "2025-07-28T04:28:21.112Z", "updatedAt": "2025-07-28T04:28:21.112Z", "publishedAt": "2025-07-28T04:28:21.112Z" } ], "pagination": { "total": 1, "limit": 10, "offset": 0, "hasNext": false, "hasPrevious": false } } ``` ### 透過 ID 取得虛擬物品 使用其 ID 檢索特定虛擬物品的詳細資訊。 ```bash curl --request GET \ --url https://api.tokenz.one/v2/product/virtual-items/{VirtualItemID} \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **回應：** ```json { "data": { "id": "virtualitem_YJoSoHrd9R1", "sku": "gold-ring-350", "label": { "en_US": "Gold Ring" }, "description": { "en_US": "" }, "images": [ { "id": "3ZUJBfy7M99jRh0YglPUQv", "fileName": "gold-ring.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png", "width": 240, "height": 240 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 350, "currency": "JPY" } ], "taxCategory": "DIGITAL_GOODS_AND_SERVICES", "createdAt": "2025-07-28T04:28:21.112Z", "updatedAt": "2025-07-28T04:28:21.112Z", "publishedAt": "2025-07-28T04:28:21.112Z" } } ``` ### 列出組合包 檢索組合包，可選擇包含組合包物品。 ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/bundles' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` 支援以下查詢參數： #### 分頁 - `limit`: 回傳的項目數量（最大 100，預設 20） - `offset`: 分頁跳過的項目數量 #### 包含項目 - `include_items`: 在回應中包含組合包項目（預設：false） #### 篩選 - `sku`: 按 SKU 篩選（完全匹配） #### 排序 組合包支援以下排序： - `name_asc` / `name_desc`: 按名稱排序 - `sku_asc` / `sku_desc`: 按 SKU 排序 - `created_asc` / `created_desc`: 按建立日期排序（預設：`created_desc`） ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/bundles?include_items=true&limit=10&offset=0&sku=treasure-box&sort=name_asc' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **回應：** ```json { "data": [ { "id": "bundle_GavBmyQmH43", "sku": "treasure-box", "label": { "en_US": "Treasure Box" }, "description": { "en_US": "" }, "images": [ { "id": "3CeCTmaDg0SbVBh1oegKam", "fileName": "treasure-box-1.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png", "width": 360, "height": 360 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 1500, "currency": "JPY" } ], "bundleItems": [], "createdAt": "2025-07-28T12:43:28.991Z", "updatedAt": "2025-09-12T07:25:13.994Z", "publishedAt": "2025-09-12T07:25:13.994Z" } ], "pagination": { "total": 1, "limit": 10, "offset": 0, "hasNext": false, "hasPrevious": false } } ``` ### 透過 ID 取得組合包 使用其 ID 檢索特定組合包的詳細資訊。 ```bash curl --request GET \ --url https://api.tokenz.one/v2/product/bundles/{BundleID} \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **回應：** ```json { "data": { "id": "bundle_GavBmyQmH43", "sku": "treasure-box", "label": { "en_US": "Treasure Box" }, "description": { "en_US": "" }, "images": [ { "id": "3CeCTmaDg0SbVBh1oegKam", "fileName": "treasure-box-1.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png", "width": 360, "height": 360 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 1500, "currency": "JPY" } ], "bundleItems": [ { "quantity": 5, "item": { "id": "virtualitem_YJoSoHrd9R1", "sku": "gold-ring-350", "label": { "en_US": "Gold Ring" }, "description": { "en_US": "" }, "images": [ { "id": "3ZUJBfy7M99jRh0YglPUQv", "fileName": "gold-ring.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png", "width": 240, "height": 240 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 350, "currency": "JPY" } ], "taxCategory": "DIGITAL_GOODS_AND_SERVICES", "createdAt": "2025-07-28T04:28:21.112Z", "updatedAt": "2025-07-28T04:28:21.112Z", "publishedAt": "2025-07-28T04:28:21.112Z" } }, { "quantity": 10, "item": { "id": "virtualitem_83f3aWcvJ4w", "sku": "diamond-currency", "label": { "en_US": "Diamond" }, "description": { "en_US": "" }, "images": [ { "id": "3jOZHd2Ht3uOL1bBxLGmeM", "fileName": "pngtree-blue-diamond-for-game-png-image_2914528.jpg", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3jOZHd2Ht3uOL1bBxLGmeM/397c603cb7b968bfa9ebba2fcd21216e/pngtree-blue-diamond-for-game-png-image_2914528.jpg", "width": 360, "height": 360 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 100, "currency": "JPY" } ], "taxCategory": "VIRTUAL_CURRENCY", "createdAt": "2025-09-12T02:35:53.272Z", "updatedAt": "2025-09-12T02:35:53.272Z", "publishedAt": "2025-09-12T02:35:53.272Z" } } ], "createdAt": "2025-07-28T12:43:28.991Z", "updatedAt": "2025-09-12T07:25:13.994Z", "publishedAt": "2025-09-12T07:25:13.994Z" } } ``` ## 組合包管理 組合包允許您以折扣價格將多個虛擬物品組合在一起。檢索組合包時： - 使用`include_items=true`取得捆綁物品的詳細資訊 - 組合包定價獨立於單個物品定價 - 每個組合包物品包含數量資訊 ## 錯誤處理 API 回傳標準 HTTP 狀態碼和詳細錯誤訊息： - `401 Unauthorized`：無效或缺失的 API 權杖 - `404 Not Found`：產品或組合包未找到 - `429 Too Many Requests`：超出速率限制 - `500 Server Error`：內部伺服器錯誤 所有錯誤回應都包含結構化錯誤物件，包含代碼和訊息以便程式化處理。 ## 搶先體驗狀態 Product API 目前處於搶先體驗階段。目前支援的功能與限制如下： **當前可用：** - 虛擬物品和組合包管理 - 每個產品的單一貨幣定價 - 基本分頁和篩選 - 豐富的媒體附件 - 結帳整合 **即將推出：** - 多語言本地化支援 - 增強的篩選和搜尋功能 - 高級庫存管理功能 - 擴展的 API 端點 **已知限制：** - 產品名稱和描述的本地化尚未支援 - 某些高級篩選選項可能受限 我們正在開發這些功能，歡迎您在搶先體驗期間提供意見。