产品

抢先体验：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/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 端点

已知限制：

产品名称和描述的本地化尚未支持
某些高级过滤选项可能受限

我们正在开发这些功能，欢迎您在抢先体验期间提供反馈。