產品

搶先體驗：Product API 目前處於搶先體驗階段。我們正在開發更多功能並擴大支援範圍。部分功能有限制，或可能有所變更。請在用於正式環境前充分測試整合。

了解如何透過 Product API (產品 API) 管理和存取您的虛擬物品和組合包。

Product API 是一個內容管理系統，允許商家管理他們的虛擬物品並建立組合包。API 提供對您的產品目錄的安全存取，支援分頁和篩選。每個產品都以單一貨幣定價，而結帳時支援多種支付貨幣。

您可以檢索產品資訊以在店面中顯示，管理庫存，並以您偏好的貨幣設置價格。

金額格式： API 中所有貨幣值（如 price 欄位）均以各貨幣的最小單位表示。請參閱支援的貨幣以了解每種貨幣的確切編碼。

概述

產品系統由兩個主要組件組成：

虛擬物品：具有名稱、描述、圖片和定價的個人數位產品
組合包：以組合包價格一起銷售的虛擬物品集合

產品支援單一貨幣定價和豐富的媒體附件。API 包括分頁和篩選功能。雖然每個產品都有一個基礎貨幣，但客戶可以在結帳時使用他們的當地貨幣支付。

產品生命週期

產品建立：虛擬物品和組合包在 Tokenz Dashboard (後台) 中建立和設定
API 存取：您的應用程式使用 Product API 透過篩選和分頁檢索產品資料
顯示：產品在您的店面中顯示適當的定價
整合：產品資料與 Checkout Session 整合，用於購買流程

流程圖

API 呼叫範例

列出虛擬物品

使用可選的篩選和排序檢索虛擬物品的分頁清單。

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/virtual-items' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

支援以下查詢參數：

查詢參數

分頁

limit: 回傳的項目數量（最大 100，預設 20）
offset: 分頁跳過的項目數量

篩選

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/v1/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/v1/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/v1/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/v1/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/v1/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 端點

已知限制：

產品名稱和描述的本地化尚未支援
某些高級篩選選項可能受限

我們正在開發這些功能，歡迎您在搶先體驗期間提供意見。