导入产品

在 Tokenz Dashboard 上传文件，即可一次添加或更新多个产品，无需逐个创建。

打开 产品（Products），然后选择 导入商品。产品在正式模式下管理，请先关闭测试模式。

导入界面和错误信息以 Dashboard 的显示语言显示。本指南按简体中文界面上的原文引用这些内容。

开始之前

只有当您的角色拥有以下全部权限时，才会显示 导入商品 按钮。如有缺少，请联系管理员添加。

选择格式

所有格式遵循相同的规则：产品按 sku 匹配，导入只会添加或更新产品，不会删除文件中没有的产品。

CSV 格式

文件规则

• 编码为 UTF-8，带不带 Excel 添加的字节顺序标记（BOM）都可以。日文版 Excel 默认的“CSV”（Shift_JIS）和 Excel 的“Unicode 文本”（UTF-16）也能读取。请参阅从电子表格保存 CSV。
• 值以逗号分隔。分号或制表符分隔的文件也可以使用，分隔符会根据标题行自动识别。
• 价格的小数点使用英文句点，例如 7.50。小数逗号（7,50）、货币符号（¥480）或千位分隔符（1,000）会被判定为不是数字。
• 值中包含文件的分隔符（逗号；分号或制表符分隔的文件中则为分号或制表符）、双引号或换行时，用双引号括起来。值中的双引号写作 ""。例如在分号分隔的文件中：gem-pack-500;500 Gems;"500 gems; added instantly.";480;JPY
• 第一行必须是标题行。标题名称不区分大小写。电子表格添加的空列和空行会被忽略。
• 错误信息中的行号按数据行计算：标题下方的第一行为第 1 行。
• CSV 和 JSON 文件最大 25 MB，行数没有上限。

列

布尔值列（free、publish）可使用 true/false、yes/no 或 1/0。

示例

三个以 JPY 定价的游戏道具。第二行演示引号的用法，第三行是免费道具。

sku,name,description,price,currency,free,category,taxCategory,publish,image_url
gem-pack-500,500 Gems,"500 gems, added to your account instantly.",480,JPY,false,Gems,virtualCurrency,true,https://cdn.example.com/items/gem-pack-500.webp
starter-bundle,Starter Bundle,"1,200 gems and the ""Rookie"" badge.",1980,JPY,false,Bundles,virtualCurrency,false,https://cdn.example.com/items/starter-bundle.webp
daily-gift,Daily Free Gift,One free reward per day.,,,true,Free gifts,virtualCurrency,true,

从电子表格保存 CSV

最稳妥的做法是在导入窗口中选择 下载模板，填写后另存为 CSV。

Microsoft Excel

• 选择 文件 > 另存为（或 保存副本），然后选择 CSV UTF-8（逗号分隔）(*.csv)。无论使用哪种语言，都推荐这种格式。
• 在日文系统上，Excel 默认的 CSV（逗号分隔） 以 Shift_JIS 保存。这种文件也可以导入，日文能正确读取。
• 在使用小数逗号的地区（例如欧洲大部分地区），Excel 会以分号分隔保存“CSV”，并把价格写成 7,50。分号会被自动识别，但小数逗号无法作为价格读取。保存前请将小数点改为句点（在 Windows 版 Excel 中，选择 文件 > 选项 > 高级，取消勾选 使用系统分隔符，并将 小数分隔符 设为 .），或以带句点的文本形式输入价格。
• Excel 会把 123456789012 这类较长的数字 SKU 转成 1.23457E+11，并删除开头的零。输入 SKU 之前，请先将 sku 列的格式设为 文本。以科学计数法保存的 SKU 已经丢失位数，因此会被拒绝。

Google 表格

选择 文件 > 下载 > 逗号分隔值文件 (.csv)。文件为 UTF-8 编码，可直接导入。

Apple Numbers

选择 文件 > 导出为 > CSV。文本编码 请保持 Unicode (UTF-8)。

JSON 格式

JSON 导入使用一个名为 products.json 的清单文件。若所有图片都是 URL，可直接上传该文件；若引用了图片文件，请将其放入 ZIP 中上传。

清单

产品字段

每个产品必须且只能设置一个定价字段：price、free: true 或 regionPrices。

示例

{
  "version": 1,
  "defaults": {
    "currency": "JPY",
    "taxCategory": "virtualCurrency",
    "publish": false
  },
  "products": [
    {
      "sku": "starter-bundle",
      "name": "Starter Bundle",
      "description": "1,200 gems and the Rookie badge.",
      "price": 1980,
      "category": "Bundles",
      "images": ["images/starter-bundle.webp"]
    },
    {
      "sku": "daily-gift",
      "name": "Daily Free Gift",
      "description": "",
      "free": true,
      "images": ["https://cdn.example.com/items/daily-gift.webp"],
      "publish": true
    },
    {
      "sku": "gem-pack-1200",
      "name": "1,200 Gems",
      "description": "Priced for each region.",
      "regionPrices": { "JP": 980, "US": 6.99, "GB": 5.99 },
      "category": "Gems",
      "images": [
        "images/gem-pack-1200.webp",
        "https://cdn.example.com/items/gem-pack-1200-alt.webp"
      ]
    }
  ]
}

将图片打包为 ZIP

如果有图片使用相对路径（例如 images/starter-bundle.webp），请上传根目录包含 products.json 的 ZIP 文件。相对路径从 ZIP 内部读取。

products.zip
  products.json
  images/
    starter-bundle.webp
    gem-pack-1200.webp

价格

所有价格都以货币的常用单位、大于 0 的数字填写（¥480 写 480，$4.99 写 4.99）。此规则适用于 CSV 和 JSON 中的 price，以及 regionPrices 中的每个金额。

• 小数位数。 价格的小数位数不能超过该货币使用的位数。JPY 和 KRW 没有小数，因此 480.5 JPY 会被拒绝。USD、EUR 等大多数货币使用 2 位，BHD、KWD 等少数货币使用 3 位。各货币的小数位数请参阅支持的货币。
• 上限。 价格上限为 99,999,999.99，并按货币的小数位数调整：

预览会在写入任何内容之前检查所有价格。价格不符合这些规则时，会显示指出该行的信息，导入不会进行。

图片

• 格式：WebP、PNG、JPEG 或 GIF。
• 每张图片最大 25 MB。空文件会被拒绝。
• 图片 URL 必须可公开访问。需要登录的 URL，以及私有或本地地址（例如 localhost）会被拒绝。
• CSV 中每个产品在 image_url 中填写一个 URL。如需多张图片或上传图片文件，请使用 JSON 或 ZIP。
• 更新产品时如果未提供图片，产品会保留现有图片。

重新导入与更新

产品按 sku 匹配：

• 新的 sku：创建产品。
• 已有的 sku：用文件中的值更新产品。这是默认行为。
• 文件中没有的 sku：产品保持不变。导入永远不会删除产品。

如果只想添加新产品而不改动现有产品，请在导入前勾选 仅新建（跳过已有 SKU）。sku 已存在的行会被跳过，并在结果中计为跳过。

对于已有产品，导入不会更改以下内容：

• 已有方案的价格。 如果产品已有相同计费周期的方案（例如一次性价格）且价格不同，该行会保留当前价格。该行的其他值仍会更新，结果中会注明“price not applied”。如需更改价格，请在 Dashboard 中打开该产品并在那里修改。替换方案价格是一个无法撤销的单独操作，因此导入不会执行。
• 税务类别。 在创建产品时设定。

导入步骤

1. 选择 导入商品，上传 .csv、products.json 或 .zip 文件。
2. 查看预览。每一行会显示将被创建、更新还是跳过，以及是否有错误。
3. 如有错误，修正后重新上传。文件存在错误时不会写入任何数据。
4. 选择 导入。创建和更新产品时会显示进度。
5. 查看结果：已创建、已更新、已跳过和失败的数量，以及每个失败行的原因。

常见错误

导入窗口会针对每个问题显示所在的行和 SKU，例如：“第 3 行（SKU gem-pack-500）：请为价格填写 currency，例如 USD 或 JPY。”在 JSON 文件中，产品按顺序编号（“第 2 个商品（SKU …）”）。只要还有问题，就不会写入任何内容。请修正文件后重新上传。

文件问题

这些问题会导致整个文件无法读取。

行问题

导入之后

导入结果会列出失败的行，以及未完全按文件内容更改的行，并附有英文说明。

如果导入后文字出现乱码，说明文件编码被误判。请另存为 CSV UTF-8 后重新导入。

需要帮助？

请联系 Tokenz 支持团队，并附上您尝试导入的文件和 Dashboard 中显示的错误。