상품 가져오기
상품을 하나씩 생성하는 대신 Tokenz 대시보드에서 파일을 업로드하여 여러 상품을 한 번에 추가하거나 업데이트하세요.
상품(Products)에서 상품 가져오기(Import products)를 선택하세요. 가져오기는 테스트 모드와 라이브 모드 모두에서 실행할 수 있습니다. 테스트와 라이브는 상품을 따로 관리하므로, 한 모드에서 가져온 상품은 다른 모드에 나타나지 않습니다.
Xsolla에서 옮겨 오시나요? Xsolla 카탈로그 내보내기 파일을 그대로 업로드할 수 있습니다.
시작하기 전에
역할에 다음 권한이 모두 있어야 상품 가져오기(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 저장을 참고하세요.
- 값은 쉼표로 구분합니다. 세미콜론과 탭으로 구분한 파일도 지원하며, 헤더 행에서 구분자를 감지합니다.
- 가격의 소수점에는
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)입니다. 지원 통화를 참고하세요. |
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 가격의 게임 아이템 세 개입니다. 두 번째 행은 따옴표 사용 예이며, 세 번째는 무료 상품입니다.
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 중 정확히 하나의 가격 필드가 필요합니다.
예제
{
"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
가격
모든 가격은 통화의 기본 단위(¥480은 480, $4.99는 4.99)로, 0보다 큰 숫자로 입력하세요. CSV·JSON의 price와 모든 regionPrices 금액에 적용됩니다.
- 소수 자릿수. 통화에서 허용하는 자릿수를 초과할 수 없습니다. JPY와 KRW는 소수점이 없으므로
480.5JPY는 거부됩니다. USD, EUR 등은 2자리, BHD, KWD 등은 3자리입니다. 지원 통화를 참고하세요. - 최대값. 통화의 소수 자릿수에 맞춘 최대 가격은 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 건너뛰기(Skip SKUs that already exist)를 켜세요. 기존 sku 행은 건너뛰고 결과에 건너뛴 항목으로 집계됩니다. 결과에서는 이 행들이 새로 만들기만(Create only)으로 표시됩니다.
가져오기로 기존 상품에서 변경되지 않는 항목은 다음과 같습니다.
- 기존 요금제 가격. 같은 청구 주기(예: 일회성)에 다른 가격의 요금제가 이미 있으면 현재 가격을 유지합니다. 나머지 값은 업데이트하고 결과에 “price not applied”를 표시합니다. 가격 변경은 대시보드에서 해당 상품을 열어 수행하세요. 요금제 가격 교체는 되돌릴 수 없는 별도 작업이므로 가져오기에서는 수행하지 않습니다.
- 세금 카테고리. 상품 생성 시 설정됩니다.
가져오기 절차
- 상품 가져오기(Import products)를 선택하고
.csv,products.json,.zip파일을 업로드하세요. - 미리 보기를 검토하세요. 행별 생성, 업데이트, 건너뛰기 여부와 오류가 표시됩니다.
- 오류를 수정하고 다시 업로드하세요. 오류가 있으면 아무것도 저장되지 않습니다.
- 상품 N개 가져오기(Import N products)를 선택하세요. N은 버튼에 표시되는 상품 수입니다. 상품 생성 및 업데이트 진행 상황이 표시됩니다.
- 생성, 업데이트, 건너뛰기, 실패 수와 각 실패 사유를 확인하세요.
일반적인 오류
대화상자는 “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. | 지원 열 중 하나로 이름을 변경하거나 삭제하세요. |
| … can't be imported from a CSV. | regionPrices 등 JSON이 필요한 열입니다. 형식 선택을 참고하세요. |
| 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 저장을 참고하세요. |
| JPY allows 0 decimal places, so 480.5 can't be charged. Round the price. | 통화가 허용하는 자릿수로 반올림하세요. JPY와 KRW는 소수점이 없습니다. 가격을 참고하세요. |
| price 150000000 is above the maximum of 99,999,999 JPY. | 통화별 최대값 이내로 지정하세요. |
| add a currency for the price, such as USD or JPY. | CSV에서 price가 있는 모든 행에 currency가 필요합니다. |
| currency … isn't supported. | 지원 통화의 코드를 사용하세요. |
| 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… | 기존 가격을 유지했습니다. 변경하려면 다시 가져오기 및 업데이트를 참고하세요. |
| sku already exists | 이미 있는 SKU 건너뛰기(Skip SKUs that already exist)가 켜져 있어 기존 상품을 건너뛰었습니다. |
| sku belongs to another product | 가져오기로 수정할 수 없는 상품이 SKU를 사용 중입니다. 다른 SKU를 사용하세요. |
가져온 텍스트가 깨지면 파일 인코딩을 잘못 감지한 것입니다. CSV UTF-8로 저장하고 다시 가져오세요.
도움이 필요하신가요?
가져오려던 파일과 대시보드 오류 메시지를 첨부하여 Tokenz 지원팀에 문의하세요.