匯入產品

在 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 顯示的錯誤。