---
title: "상품 가져오기"
description: "상품을 하나씩 생성하는 대신 Tokenz 대시보드에서 파일을 업로드하여 여러 상품을 한 번에 추가하거나 업데이트하세요."
source: "https://docs.tokenz.one/ko-KR/v1/product/import"
api_version: "v1"
locale: "ko-KR"
version_status: "legacy"
docs_stage: "prod"
---

# 상품 가져오기

상품을 하나씩 생성하는 대신 Tokenz 대시보드에서 파일을 업로드하여 여러 상품을 한 번에 추가하거나 업데이트하세요.

**상품**(Products)에서 **상품 가져오기**(Import products)를 선택하세요. 상품은 라이브 모드에서 관리하므로 먼저 테스트 모드를 끄세요.

## 시작하기 전에

역할에 다음 권한이 모두 있어야 **상품 가져오기**(Import products) 버튼이 표시됩니다. 누락된 권한은 관리자에게 요청하세요.

| 그룹 | 권한 |
| --- | --- |
| **카탈로그 아이템**(Catalog items) | **카탈로그 아이템 보기**(View catalog items), **카탈로그 아이템 생성**(Create catalog items), **카탈로그 아이템 편집**(Edit catalog items) |
| **요금제**(Price plans) | **요금제 보기**(View price plans), **요금제 생성**(Create price plans), **요금제 게시**(List price plans) |

## 형식 선택

| 형식 | 적합한 경우 |
| --- | --- |
| CSV (`.csv`) | 상품당 가격 하나, 이미지 URL 하나를 사용하는 일반적인 카탈로그입니다. 스프레드시트에서 쉽게 내보낼 수 있습니다. |
| JSON (`products.json`) | 지역별 가격이나 상품당 여러 이미지가 필요한 경우입니다. 모든 이미지를 URL로 지정합니다. |
| ZIP (`products.json` + 이미지) | JSON과 같지만 매니페스트와 이미지 파일을 함께 업로드하는 경우입니다. |

모든 형식에 같은 규칙이 적용됩니다. `sku`로 상품을 식별하며, 가져오기는 상품을 추가하거나 업데이트하기만 합니다. 파일에 없는 상품을 삭제하지 않습니다.

## CSV 형식

### 파일 규칙

- UTF-8 인코딩을 사용합니다. Excel이 추가하는 바이트 순서 표시(BOM)는 있어도 없어도 됩니다. 일본어 Excel의 일반 CSV(Shift_JIS)와 Unicode Text(UTF-16)도 읽을 수 있습니다. [스프레드시트에서 CSV 저장](https://docs.tokenz.one/ko-KR/v1/product/import#save-a-csv-from-a-spreadsheet)을 참고하세요.
- 값은 쉼표로 구분합니다. 세미콜론과 탭으로 구분한 파일도 지원하며, 헤더 행에서 구분자를 감지합니다.
- 가격의 소수점에는 `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/ko-KR/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 저장

가져오기 대화상자에서 **템플릿 다운로드**(Download template)를 선택하고, 템플릿을 작성한 후 CSV로 저장하세요.

### Microsoft Excel

- **File** > **Save As**(또는 **Save a Copy**)에서 **CSV UTF-8 (Comma delimited) (*.csv)**를 선택하세요. 모든 언어에서 권장하는 형식입니다.
- 일본어 시스템에서 Excel의 기본 **CSV (Comma delimited)**는 Shift_JIS로 저장합니다. 이 형식도 지원하며 일본어를 올바르게 가져옵니다.
- 소수점에 쉼표를 사용하는 지역(유럽의 여러 국가 등)에서는 Excel이 파일 구분자로 세미콜론을 쓰고 가격을 `7,50`처럼 저장합니다. 파일 구분자인 세미콜론은 인식하지만 쉼표를 소수점으로 쓴 가격은 읽지 못합니다. 저장 전 소수점 구분자를 마침표로 바꾸거나(Windows Excel의 **File** > **Options** > **Advanced**에서 **Use system separators**를 해제하고 **Decimal separator**를 `.`으로 설정), 가격을 마침표가 있는 텍스트로 입력하세요.
- Excel은 `123456789012` 같은 긴 숫자 SKU를 `1.23457E+11`로 바꾸고 앞의 0을 제거합니다. SKU 입력 전 `sku` 열 서식을 **Text**로 설정하세요. 지수 표기된 SKU는 이미 숫자가 손실되었으므로 거부됩니다.

### Google Sheets

**File** > **Download** > **Comma-separated values (.csv)**를 사용하세요. UTF-8 파일이므로 그대로 가져올 수 있습니다.

### Apple Numbers

**File** > **Export To** > **CSV**를 사용하세요. **Text Encoding**을 **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
```

## 가격

모든 가격은 통화의 기본 단위(¥480은 `480`, $4.99는 `4.99`)로, 0보다 큰 숫자로 입력하세요. CSV·JSON의 `price`와 모든 `regionPrices` 금액에 적용됩니다.

- **소수 자릿수.** 통화에서 허용하는 자릿수를 초과할 수 없습니다. JPY와 KRW는 소수점이 없으므로 `480.5` JPY는 거부됩니다. USD, EUR 등은 2자리, BHD, KWD 등은 3자리입니다. [지원 통화](https://docs.tokenz.one/ko-KR/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 건너뛰기)**(Create only (skip existing SKUs))를 선택하세요. 기존 `sku` 행은 건너뛰고 결과에 건너뛴 항목으로 집계됩니다.

가져오기로 기존 상품에서 변경되지 않는 항목은 다음과 같습니다.

- **기존 요금제 가격.** 같은 청구 주기(예: 일회성)에 다른 가격의 요금제가 이미 있으면 현재 가격을 유지합니다. 나머지 값은 업데이트하고 결과에 “price not applied”를 표시합니다. 가격 변경은 대시보드에서 해당 상품을 열어 수행하세요. 요금제 가격 교체는 되돌릴 수 없는 별도 작업이므로 가져오기에서는 수행하지 않습니다.
- **세금 카테고리.** 상품 생성 시 설정됩니다.

## 가져오기 절차

1. **상품 가져오기**(Import products)를 선택하고 `.csv`, `products.json`, `.zip` 파일을 업로드하세요.
2. 미리 보기를 검토하세요. 행별 생성, 업데이트, 건너뛰기 여부와 오류가 표시됩니다.
3. 오류를 수정하고 다시 업로드하세요. 오류가 있으면 아무것도 저장되지 않습니다.
4. **상품 N개 가져오기**(Import N products)를 선택하세요. N은 버튼에 표시되는 상품 수입니다. 상품 생성 및 업데이트 진행 상황이 표시됩니다.
5. 생성, 업데이트, 건너뛰기, 실패 수와 각 실패 사유를 확인하세요.

## 일반적인 오류

대화상자는 “Row 3 (SKU gem-pack-500): add a currency for the price, such as USD or JPY.”처럼 문제의 행과 SKU를 표시합니다. JSON은 위치 순서로 “Product 2 (SKU …)”처럼 표시합니다. 문제가 하나라도 남아 있으면 저장하지 않으므로 파일을 수정해 다시 업로드하세요.

### 파일 문제

다음 문제가 있으면 파일을 읽을 수 없습니다.

| 메시지 | 해결 방법 |
| --- | --- |
| Add these columns to the header row: sku, description. | 누락된 필수 열을 추가하세요. `description`이 비어 있어도 `sku`, `name`, `description` 열은 항상 필요합니다. 확실하지 않으면 템플릿을 사용하세요. |
| Unknown columns: … Rename or remove them. | [지원 열](https://docs.tokenz.one/ko-KR/v1/product/import#columns) 중 하나로 이름을 변경하거나 삭제하세요. |
| … can't be imported from a CSV. | `regionPrices` 등 JSON이 필요한 열입니다. [형식 선택](https://docs.tokenz.one/ko-KR/v1/product/import#choose-a-format)을 참고하세요. |
| These columns appear more than once: … | 같은 이름의 열을 하나만 남기세요. |
| Column 7 has no name but row 2 has a value in it. | 데이터는 있지만 헤더가 삭제되었습니다. 헤더를 복원하거나 열 전체를 삭제하세요. |
| Row 4: a quoted value is never closed. | `"`로 시작한 값이 닫히지 않아 나머지 파일을 하나의 값으로 읽습니다. 닫는 따옴표를 추가하거나 불필요한 따옴표를 제거하세요. |
| Row 4: there is text after a closing quote. | 전체 값을 따옴표로 감싸고 내부 따옴표는 `""`로 쓰세요. |
| Row 5 has more values than the 10 columns in the header. | 구분자(쉼표, 세미콜론, 탭)가 든 값을 따옴표로 감싸지 않아 이후 값의 열이 밀렸습니다. 해당 값을 큰따옴표로 감싸세요. |
| This CSV's text encoding can't be read. | Excel에서 **CSV UTF-8**로 다시 저장하거나 Google Sheets, Numbers에서 다시 다운로드하세요. |
| This file has a header row but no products. | 헤더 아래에 상품당 한 행씩 추가하세요. |
| This file is larger than 25MB. | 카탈로그를 여러 파일로 나누어 순서대로 가져오세요. |
| The ZIP has no products.json. | `products.json`을 폴더 안이 아닌 ZIP 최상위에 두세요. |

### 행 문제

| 메시지 | 해결 방법 |
| --- | --- |
| price "7,50" isn't a number. | 소수점에는 마침표(`7.50`)를 사용하고 통화 기호나 천 단위 구분자를 넣지 마세요. Excel이 소수점에 쉼표를 사용하면 [CSV 저장](https://docs.tokenz.one/ko-KR/v1/product/import#microsoft-excel)을 참고하세요. |
| JPY allows 0 decimal places, so 480.5 can't be charged. Round the price. | 통화가 허용하는 자릿수로 반올림하세요. JPY와 KRW는 소수점이 없습니다. [가격](https://docs.tokenz.one/ko-KR/v1/product/import#prices)을 참고하세요. |
| price 150000000 is above the maximum of 99,999,999 JPY. | 통화별 [최대값](https://docs.tokenz.one/ko-KR/v1/product/import#prices) 이내로 지정하세요. |
| add a currency for the price, such as USD or JPY. | CSV에서 `price`가 있는 모든 행에 `currency`가 필요합니다. |
| currency … isn't supported. | [지원 통화](https://docs.tokenz.one/ko-KR/v1/checkout/currency)의 코드를 사용하세요. |
| another row uses SKU … too. Give each product its own SKU. | 파일마다 각 `sku`는 한 번만 나와야 합니다. 중복 행을 변경하거나 제거하세요. |
| SKU 1.23457E+11 looks like a number Excel turned into scientific notation. | `sku` 열을 텍스트 서식으로 설정하고 SKU를 다시 입력한 후 저장하세요. |
| add a SKU. / remove the spaces before or after the SKU. | 모든 행에 앞뒤 공백 없는 `sku`를 지정하세요. |
| add a name. / add a description. | `name`을 입력하세요. 비어 있어도 `description`은 포함하세요. |
| add a price and currency, or set free to true. | 가격과 통화를 지정하거나 무료 상품으로 설정하세요. |
| set a price or set free to true, not both. | 무료 상품은 `price`와 `currency`를 비우세요. |
| price must be more than 0. | 0보다 큰 가격을 입력하거나 값을 비우고 `free`를 `true`로 설정하세요. |
| taxCategory "…" isn't valid. | `virtualCurrency`, `digitalGoodsAndServices`, `eBook`, `saas` 중 하나를 사용하세요. |
| publish is "…". Set it to true or false. | CSV는 `true`/`false`, `yes`/`no`, `1`/`0`을 사용하세요. JSON은 따옴표 없는 `true` 또는 `false`를 쓰세요. |
| image_url "…" isn't a full https URL. | `https://`로 시작하는 전체 URL을 사용하세요. |
| A product uses an image that isn't in the ZIP. | 같은 경로로 파일을 추가하거나 경로를 수정하세요. 대소문자를 구분합니다. |
| A product uses an image that is empty or larger than 25MB. | 더 작은 이미지로 교체하세요. |
| Set version to 1. | `products.json`에 `"version": 1`을 설정하세요. |

### 가져오기 이후

결과에는 실패했거나 파일에서 요청한 것보다 적게 변경된 행이 영어 메모와 함께 표시됩니다.

| 메모 | 의미 |
| --- | --- |
| price not applied: this interval already has a plan… | 기존 가격을 유지했습니다. 변경하려면 [다시 가져오기 및 업데이트](https://docs.tokenz.one/ko-KR/v1/product/import#re-import-and-updates)를 참고하세요. |
| sku already exists | **새로 만들기만 (기존 SKU 건너뛰기)**(Create only (skip existing SKUs))를 선택하여 기존 상품을 건너뛰었습니다. |
| sku belongs to another product | 가져오기로 수정할 수 없는 상품이 SKU를 사용 중입니다. 다른 SKU를 사용하세요. |

가져온 텍스트가 깨지면 파일 인코딩을 잘못 감지한 것입니다. **CSV UTF-8**로 저장하고 다시 가져오세요.

## 도움이 필요하신가요?

가져오려던 파일과 대시보드 오류 메시지를 첨부하여 Tokenz 지원팀에 문의하세요.