--- title: "产品" description: "了解如何通过 Product API (产品 API) 管理和访问您的虚拟物品和组合包。" source: "https://docs.tokenz.one/zh-CN/v2/product" api_version: "v2" locale: "zh-CN" version_status: "current" docs_stage: "prod" --- # 产品 > **抢先体验**：Product API 目前处于抢先体验阶段。我们正在开发更多功能并扩大支持范围。部分功能存在限制，或可能发生变化。请在用于生产环境前充分测试集成。 了解如何通过 Product API (产品 API) 管理和访问您的虚拟物品和组合包。 Product API 是一个内容管理系统，允许商家管理他们的虚拟物品并创建组合包。API 提供对您的产品目录的安全访问，支持分页和过滤。每个产品都以单一货币定价，而结账时支持多种支付货币。 您可以检索产品信息以在店面中显示，管理库存，并以您偏好的货币设置价格。 **金额格式：** API 中所有货币值（如 `price` 字段）均以各货币的最小单位表示。请参阅[支持的货币](https://docs.tokenz.one/zh-CN/v2/checkout/currency)了解每种货币的确切编码。 ## 概述 产品系统由两个主要组件组成： - **虚拟物品**：具有名称、描述、图片和定价的个人数字产品 - **组合包**：以组合包价格一起销售的虚拟物品集合 产品支持单一货币定价和丰富的媒体附件。API 包括分页和过滤功能。虽然每个产品都有一个基础货币，但客户可以在结账时使用他们的当地货币支付。 ## 产品生命周期 1. **产品创建**：虚拟物品和组合包在 Tokenz Dashboard (仪表板) 中创建和配置 2. **API 访问**：您的应用程序使用 Product API 通过过滤和分页检索产品数据 3. **显示**：产品在您的店面中显示适当的定价 4. **集成**：产品数据与 Checkout Session 集成，用于购买流程 ```mermaid sequenceDiagram; autonumber; participant M as 商家应用; participant T as 产品 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 端点 **已知限制：** - 产品名称和描述的本地化尚未支持 - 某些高级过滤选项可能受限 我们正在开发这些功能，欢迎您在抢先体验期间提供反馈。