---
title: "导入产品"
description: "在 Tokenz Dashboard 上传文件，即可一次添加或更新多个产品，无需逐个创建。"
source: "https://docs.tokenz.one/zh-CN/v1/product/import"
api_version: "v1"
locale: "zh-CN"
version_status: "legacy"
docs_stage: "prod"
---

# 导入产品

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

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

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

## 开始之前

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

| 分组 | 权限 |
| --- | --- |
| 目录商品 | 查看目录商品、创建目录商品、编辑目录商品 |
| 价格方案 | 查看价格方案、创建价格方案、上架价格方案 |

## 选择格式

| 格式 | 适用场景 |
| --- | --- |
| CSV（`.csv`） | 适合大多数商品目录：每个产品一个价格、一个图片 URL。可以直接从电子表格导出。 |
| JSON（`products.json`） | 需要按地区定价，或每个产品需要多张图片。所有图片都使用 URL。 |
| ZIP（`products.json` 和图片） | 与 JSON 相同，但希望将图片文件与清单一起上传。 |

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

## CSV 格式

### 文件规则

- 编码为 UTF-8，带不带 Excel 添加的字节顺序标记（BOM）都可以。日文版 Excel 默认的“CSV”（Shift_JIS）和 Excel 的“Unicode 文本”（UTF-16）也能读取。请参阅[从电子表格保存 CSV](https://docs.tokenz.one/zh-CN/v1/product/import#%E4%BB%8E%E7%94%B5%E5%AD%90%E8%A1%A8%E6%A0%BC%E4%BF%9D%E5%AD%98-csv)。
- 值以逗号分隔。分号或制表符分隔的文件也可以使用，分隔符会根据标题行自动识别。
- 价格的小数点使用英文句点，例如 `7.50`。小数逗号（`7,50`）、货币符号（`¥480`）或千位分隔符（`1,000`）会被判定为不是数字。
- 值中包含文件的分隔符（逗号；分号或制表符分隔的文件中则为分号或制表符）、双引号或换行时，用双引号括起来。值中的双引号写作 `""`。例如在分号分隔的文件中：`gem-pack-500;500 Gems;"500 gems; added instantly.";480;JPY`
- 第一行必须是标题行。标题名称不区分大小写。电子表格添加的空列和空行会被忽略。
- 错误信息中的行号按数据行计算：标题下方的第一行为第 1 行。
- CSV 和 JSON 文件最大 25 MB，行数没有上限。

### 列

| 列 | 必填 | 说明 |
| --- | --- | --- |
| `sku` | 是 | 产品的唯一 ID。再次导入相同的 `sku` 会更新该产品。 |
| `name` | 是 | 产品名称。 |
| `description` | 是 | 产品描述。该列必须存在，但值可以为空。 |
| `price` | `free` 不为 true 时 | 以货币常用单位表示的数字价格，例如 ¥480 写作 `480`，$4.99 写作 `4.99`。 |
| `currency` | 设置了 `price` 时 | ISO 4217 货币代码，例如 `JPY` 或 `USD`。请参阅[支持的货币](https://docs.tokenz.one/zh-CN/v1/checkout/currency)。 |
| `free` | 否 | 免费产品填写 `true`，并将 `price` 和 `currency` 留空。 |
| `category` | 否 | 分类名称。不存在的分类会被自动创建。 |
| `taxCategory` | 否 | `virtualCurrency`、`digitalGoodsAndServices`、`eBook` 或 `saas`。默认值：`virtualCurrency`。 |
| `publish` | 否 | `true` 表示发布产品。默认值为 `false`，即保存为草稿。 |
| `image_url` | 否 | 一个可公开访问的 `https` 图片 URL。 |

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

### 示例

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

```csv
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 中上传。

### 清单

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `version` | 是 | 固定为 `1`。 |
| `defaults` | 否 | 应用于未单独设置的产品的值：`currency`、`taxCategory`、`category` 和 `publish`。 |
| `products` | 是 | 产品列表。 |

### 产品字段

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `sku` | 是 | 产品的唯一 ID，前后不能有空格。 |
| `name` | 是 | 产品名称。 |
| `description` | 是 | 产品描述。没有描述时使用 `""`。 |
| `price` | 定价字段之一 | 以货币常用单位表示的数字价格。 |
| `free` | 定价字段之一 | 免费产品填写 `true`。 |
| `regionPrices` | 定价字段之一 | 按地区设置的价格，以两位国家代码为键，例如 `{ "JP": 980, "US": 6.99 }`。每个地区使用其本地货币。第一项是所有未列出地区的价格。 |
| `currency` | 否 | `price` 的货币。默认为 `defaults.currency`，未设置时为 `JPY`。不能与 `regionPrices` 同时使用。 |
| `category` | 否 | 分类名称。不存在时会被创建。 |
| `taxCategory` | 否 | `virtualCurrency`、`digitalGoodsAndServices`、`eBook` 或 `saas`。 |
| `images` | 否 | 图片路径或 URL。第一张图片为主图。 |
| `publish` | 否 | `true` 表示发布，`false` 表示保存为草稿。必须是布尔值，不能是字符串。 |

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

### 示例

```json
{
  "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 内部读取。

```text
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 位。各货币的小数位数请参阅[支持的货币](https://docs.tokenz.one/zh-CN/v1/checkout/currency)。
- **上限。** 价格上限为 99,999,999.99，并按货币的小数位数调整：

| 小数位数 | 货币示例 | 价格上限 |
| --- | --- | --- |
| 0 | JPY、KRW | 99,999,999 |
| 2 | USD、EUR | 99,999,999.99 |
| 3 | BHD、KWD | 99,999,999.999 |

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

## 图片

- 格式：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 …）”）。只要还有问题，就不会写入任何内容。请修正文件后重新上传。

### 文件问题

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

| 信息 | 解决方法 |
| --- | --- |
| 请在标题行中添加以下列：sku, description | 添加缺少的必填列。`sku`、`name` 和 `description` 始终必填，即使 `description` 为空也需要该列。不确定时请从模板开始。 |
| 未知列：…。请重命名或删除。 | 将其改为[列](https://docs.tokenz.one/zh-CN/v1/product/import#%E5%88%97)中列出的名称，或删除该列。 |
| … 无法从 CSV 导入。 | `regionPrices` 等列需要使用 JSON。请参阅[选择格式](https://docs.tokenz.one/zh-CN/v1/product/import#%E9%80%89%E6%8B%A9%E6%A0%BC%E5%BC%8F)。 |
| 以下列重复出现：… | 同名的列只保留一个。 |
| 第 7 列没有列名，但第 2 行在该列中有值。 | 标题单元格被删除了，但该列仍有数据。请补回标题，或删除整列。 |
| 第 4 行：带引号的值没有闭合。 | 某个值以 `"` 开头却没有以 `"` 结尾，导致之后的内容都被读成同一个值。请补上闭合引号，或删除多余的引号。 |
| 第 4 行：闭合引号后还有文字。 | 用引号括起整个值，值中的引号写作 `""`。 |
| 第 5 行的值多于标题行的 10 列。 | 某个值包含分隔符（逗号，或分号、制表符）但没有加引号，导致后面的值错位。请用双引号括起该值。 |
| 无法读取此 CSV 的文字编码。 | 从 Excel 重新另存为 **CSV UTF-8**，或从 Google 表格或 Numbers 重新下载。 |
| 此文件只有标题行，没有商品。 | 在标题下方每行添加一个产品。 |
| 此文件超过 25MB。 | 将商品目录拆分为多个文件，依次导入。 |
| ZIP 中没有 products.json。 | 将 `products.json` 放在 ZIP 的顶层，而不是文件夹中。 |

### 行问题

| 信息 | 解决方法 |
| --- | --- |
| price「7,50」不是数字。 | 小数点使用句点（`7.50`），不要带货币符号或千位分隔符。如果 Excel 写出小数逗号，请参阅 [Microsoft Excel](https://docs.tokenz.one/zh-CN/v1/product/import#microsoft-excel)。 |
| JPY 最多允许 0 位小数，无法收取 480.5。请对价格取整。 | 按该货币使用的小数位数取整。JPY 和 KRW 没有小数。请参阅[价格](https://docs.tokenz.one/zh-CN/v1/product/import#%E4%BB%B7%E6%A0%BC)。 |
| price 150000000 超过上限 99,999,999 JPY。 | 使用不超过该货币[上限](https://docs.tokenz.one/zh-CN/v1/product/import#%E4%BB%B7%E6%A0%BC)的价格。 |
| 请为价格填写 currency，例如 USD 或 JPY。 | 在 CSV 中，每个设置了 `price` 的行都需要 `currency`。 |
| 不支持币种 …。 | 使用[支持的货币](https://docs.tokenz.one/zh-CN/v1/checkout/currency)中的代码。 |
| 另一行也使用了 SKU …。 | 同一文件中每个 `sku` 只能出现一次。请修改重复行的 SKU 或删除该行。 |
| SKU 1.23457E+11 看起来是被 Excel 转成科学计数法的数字，部分位数已丢失。 | 将 `sku` 列的格式设为文本，重新输入 SKU 后保存。 |
| 请填写 SKU。／请删除 SKU 前后的空格。 | 为每一行填写前后没有空格的 `sku`。 |
| 请填写 name。／请添加 description。 | 填写 `name`。即使为空也要包含 `description`。 |
| 请填写 price 和 currency，或将 free 设为 true。 | 设置价格和货币，或将产品设为免费。 |
| price 和 free = true 只能选择其一。 | 免费产品请将 `price` 和 `currency` 留空。 |
| price 必须大于 0。 | 使用正数价格，或将其留空并把 `free` 设为 `true`。 |
| taxCategory「…」无效。 | 使用 `virtualCurrency`、`digitalGoodsAndServices`、`eBook` 或 `saas`。 |
| publish 为「…」。请设为 true 或 false。 | CSV 中可使用 `true`/`false`、`yes`/`no` 或 `1`/`0`。JSON 中请写不带引号的 `true` 或 `false`。 |
| image_url「…」不是完整的 https URL。 | 使用以 `https://` 开头的完整链接。 |
| 商品使用了 ZIP 中没有的图片。 | 按相同路径将文件加入 ZIP，或修正路径。路径区分大小写。 |
| 商品使用的图片为空或大于 25MB。 | 换成较小的图片。 |
| 请将 version 设为 1。 | 在 `products.json` 中设置 `"version": 1`。 |

### 导入之后

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

| 说明 | 含义 |
| --- | --- |
| price not applied: this interval already has a plan… | 产品保留了当前价格。更改方法请参阅[重新导入与更新](https://docs.tokenz.one/zh-CN/v1/product/import#%E9%87%8D%E6%96%B0%E5%AF%BC%E5%85%A5%E4%B8%8E%E6%9B%B4%E6%96%B0)。 |
| sku already exists | 您选择了 **仅新建**，因此已有产品被跳过。 |
| sku belongs to another product | 该 SKU 已被导入无法更新的另一个产品使用。请使用其他 SKU。 |

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

## 需要帮助？

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