상품 가져오기

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

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

시작하기 전에

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

형식 선택

모든 형식에 같은 규칙이 적용됩니다. 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입니다. 행 수 제한은 없습니다.

열

불리언 열(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에 넣으세요.

매니페스트

상품 필드

각 상품에는 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.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 건너뛰기)(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 …)”처럼 표시합니다. 문제가 하나라도 남아 있으면 저장하지 않으므로 파일을 수정해 다시 업로드하세요.

파일 문제

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

행 문제

가져오기 이후

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

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

도움이 필요하신가요?

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