---
title: "匯入產品"
description: "在 Tokenz Dashboard 上傳檔案，即可一次新增或更新多項產品，不必逐一建立。"
source: "https://docs.tokenz.one/zh-TW/v1/product/import"
api_version: "v1"
locale: "zh-TW"
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-TW/v1/product/import#%E5%BE%9E%E8%A9%A6%E7%AE%97%E8%A1%A8%E5%84%B2%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-TW/v1/checkout/currency)。 |
| `free` | 否 | 免費產品填寫 `true`，並將 `price` 和 `currency` 留空。 |
| `category` | 否 | 分類名稱。不存在的分類會自動建立。 |
| `taxCategory` | 否 | `virtualCurrency`、`digitalGoodsAndServices`、`eBook` 或 `saas`。預設值：`digitalGoodsAndServices`。遊戲內貨幣請使用 `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-TW/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-TW/v1/product/import#%E6%AC%84%E4%BD%8D)中列出的名稱，或刪除該欄位。 |
| … 無法從 CSV 匯入。 | `regionPrices` 等欄位需要使用 JSON。請參閱[選擇格式](https://docs.tokenz.one/zh-TW/v1/product/import#%E9%81%B8%E6%93%87%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-TW/v1/product/import#microsoft-excel)。 |
| JPY 最多允許 0 位小數，無法收取 480.5。請將價格四捨五入。 | 依該貨幣使用的小數位數四捨五入。JPY 與 KRW 沒有小數。請參閱[價格](https://docs.tokenz.one/zh-TW/v1/product/import#%E5%83%B9%E6%A0%BC)。 |
| price 150000000 超過上限 99,999,999 JPY。 | 使用不超過該貨幣[上限](https://docs.tokenz.one/zh-TW/v1/product/import#%E5%83%B9%E6%A0%BC)的價格。 |
| 請為價格填寫 currency，例如 USD 或 JPY。 | 在 CSV 中，每個設定了 `price` 的列都需要 `currency`。 |
| 不支援幣別 …。 | 使用[支援的貨幣](https://docs.tokenz.one/zh-TW/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-TW/v1/product/import#%E9%87%8D%E6%96%B0%E5%8C%AF%E5%85%A5%E8%88%87%E6%9B%B4%E6%96%B0)。 |
| sku already exists | 您選擇了 **僅新建**，因此既有產品被略過。 |
| sku belongs to another product | 該 SKU 已被匯入無法更新的另一項產品使用。請使用其他 SKU。 |

如果匯入後文字出現亂碼，代表檔案編碼被誤判。請另存為 **CSV UTF-8** 後重新匯入。

## 需要協助？

請聯絡 Tokenz 支援團隊，並附上您嘗試匯入的檔案及 Dashboard 顯示的錯誤。