--- title: "상품" description: "Product API로 가상 아이템과 번들을 관리하고 조회하는 방법을 알아봅니다." source: "https://docs.tokenz.one/ko-KR/v2/product" api_version: "v2" locale: "ko-KR" version_status: "current" docs_stage: "prod" --- # 상품 > **얼리 액세스**: Product API는 얼리 액세스로 제공됩니다. 기능을 추가하고 지원 범위를 확대하고 있습니다. 일부 기능은 제한되거나 변경될 수 있습니다. 운영 환경에 사용하기 전에 연동을 충분히 테스트하세요. Product API로 가상 아이템과 번들을 관리하고 조회하는 방법을 알아봅니다. Product API는 가상 아이템 관리와 번들 생성을 위한 콘텐츠 관리 시스템입니다. 페이지네이션과 필터를 통해 상품 카탈로그에 안전하게 접근할 수 있습니다. 각 상품의 가격은 하나의 통화로 설정되지만 결제는 여러 통화를 지원합니다. 상품 정보를 조회하여 상점에 표시하고, 재고를 관리하고, 원하는 통화로 가격을 설정할 수 있습니다. **금액 형식:** 모든 금액 값(`price` 필드 등)은 각 통화의 최소 단위로 표시합니다. 통화별 정확한 형식은 [지원 통화](https://docs.tokenz.one/ko-KR/v2/checkout/currency)를 참고하세요. ## 개요 상품 시스템의 주요 구성 요소는 두 가지입니다. - **가상 아이템**: 이름, 설명, 이미지, 가격을 가진 개별 디지털 상품 - **번들**: 여러 가상 아이템을 묶어 번들 가격으로 판매하는 상품 상품은 단일 통화 가격과 리치 미디어 첨부를 지원합니다. API에는 페이지네이션과 필터 기능이 있습니다. 상품마다 기준 통화는 하나이지만 고객은 현지 통화로 결제할 수 있습니다. ## 상품 수명 주기 1. **상품 생성**: Tokenz 대시보드에서 가상 아이템과 번들을 생성하고 설정합니다. 2. **API 조회**: 필터 및 페이지네이션으로 상품 데이터를 조회합니다. 3. **표시**: 상점에 적절한 가격으로 상품을 표시합니다. 4. **연동**: 구매 흐름에서 상품 데이터를 Checkout Session과 연동합니다. ```mermaid sequenceDiagram; autonumber; participant M as 판매자 앱; participant T as Product API; participant DB as 상품 데이터베이스; %% 1 ── Request product catalog; M->>T: GET /v2/product/virtual-items; T->>DB: 가상 아이템 조회; DB-->>T: 상품 데이터 반환; T-->>M: 페이지 단위 상품 목록; %% 2 ── Request specific product details; M->>T: GET /v2/product/virtual-items/{id}; T->>DB: 특정 아이템 조회; DB-->>T: 상품 상세 정보 반환; T-->>M: 전체 상품 상세 정보; %% 3 ── Integration with checkout; M->>M: 고객 상품 선택; M->>T: 상품으로 Checkout Session 생성; T-->>M: Checkout Session 생성 완료; ``` ## API 호출 예제 ### 가상 아이템 목록 조회 필터와 정렬을 선택하여 페이지 단위로 가상 아이템 목록을 조회합니다. ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/virtual-items' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` 다음 쿼리 매개변수를 지원합니다. ### 쿼리 매개변수 #### 페이지네이션 - `limit`: 반환할 항목 수(최대 100, 기본 20) - `offset`: 페이지네이션을 위해 건너뛸 항목 수 #### 필터 - `sku`: SKU로 필터(정확히 일치) - `category`: 카테고리로 필터 #### 정렬 가상 아이템과 번들은 다음 정렬을 지원합니다. - `name_asc` / `name_desc`: 이름순 - `sku_asc` / `sku_desc`: SKU순 - `created_asc` / `created_desc`: 생성일순(기본: `created_desc`) ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/virtual-items?limit=10&offset=0&sku=gold-ring-350&sort=name_asc' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **응답:** ```json { "data": [ { "id": "virtualitem_YJoSoHrd9R1", "sku": "gold-ring-350", "label": { "en_US": "Gold Ring" }, "description": { "en_US": "" }, "images": [ { "id": "3ZUJBfy7M99jRh0YglPUQv", "fileName": "gold-ring.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png", "width": 240, "height": 240 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 350, "currency": "JPY" } ], "taxCategory": "DIGITAL_GOODS_AND_SERVICES", "createdAt": "2025-07-28T04:28:21.112Z", "updatedAt": "2025-07-28T04:28:21.112Z", "publishedAt": "2025-07-28T04:28:21.112Z" } ], "pagination": { "total": 1, "limit": 10, "offset": 0, "hasNext": false, "hasPrevious": false } } ``` ### ID로 가상 아이템 조회 ID로 특정 가상 아이템의 상세 정보를 조회합니다. ```bash curl --request GET \ --url https://api.tokenz.one/v2/product/virtual-items/{VirtualItemID} \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **응답:** ```json { "data": { "id": "virtualitem_YJoSoHrd9R1", "sku": "gold-ring-350", "label": { "en_US": "Gold Ring" }, "description": { "en_US": "" }, "images": [ { "id": "3ZUJBfy7M99jRh0YglPUQv", "fileName": "gold-ring.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png", "width": 240, "height": 240 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 350, "currency": "JPY" } ], "taxCategory": "DIGITAL_GOODS_AND_SERVICES", "createdAt": "2025-07-28T04:28:21.112Z", "updatedAt": "2025-07-28T04:28:21.112Z", "publishedAt": "2025-07-28T04:28:21.112Z" } } ``` ### 번들 목록 조회 필요에 따라 구성 아이템을 포함하여 번들을 조회합니다. ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/bundles' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` 다음 쿼리 매개변수를 지원합니다. #### 페이지네이션 - `limit`: 반환할 항목 수(최대 100, 기본 20) - `offset`: 페이지네이션을 위해 건너뛸 항목 수 #### 아이템 포함 - `include_items`: 응답에 번들 아이템 포함 여부(기본: false) #### 필터 - `sku`: SKU로 필터(정확히 일치) #### 정렬 번들은 다음 정렬을 지원합니다. - `name_asc` / `name_desc`: 이름순 - `sku_asc` / `sku_desc`: SKU순 - `created_asc` / `created_desc`: 생성일순(기본: `created_desc`) ```bash curl --request GET \ --url 'https://api.tokenz.one/v2/product/bundles?include_items=true&limit=10&offset=0&sku=treasure-box&sort=name_asc' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **응답:** ```json { "data": [ { "id": "bundle_GavBmyQmH43", "sku": "treasure-box", "label": { "en_US": "Treasure Box" }, "description": { "en_US": "" }, "images": [ { "id": "3CeCTmaDg0SbVBh1oegKam", "fileName": "treasure-box-1.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png", "width": 360, "height": 360 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 1500, "currency": "JPY" } ], "bundleItems": [], "createdAt": "2025-07-28T12:43:28.991Z", "updatedAt": "2025-09-12T07:25:13.994Z", "publishedAt": "2025-09-12T07:25:13.994Z" } ], "pagination": { "total": 1, "limit": 10, "offset": 0, "hasNext": false, "hasPrevious": false } } ``` ### ID로 번들 조회 ID로 특정 번들의 상세 정보를 조회합니다. ```bash curl --request GET \ --url https://api.tokenz.one/v2/product/bundles/{BundleID} \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --header 'Content-Type: application/json' ``` **응답:** ```json { "data": { "id": "bundle_GavBmyQmH43", "sku": "treasure-box", "label": { "en_US": "Treasure Box" }, "description": { "en_US": "" }, "images": [ { "id": "3CeCTmaDg0SbVBh1oegKam", "fileName": "treasure-box-1.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png", "width": 360, "height": 360 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 1500, "currency": "JPY" } ], "bundleItems": [ { "quantity": 5, "item": { "id": "virtualitem_YJoSoHrd9R1", "sku": "gold-ring-350", "label": { "en_US": "Gold Ring" }, "description": { "en_US": "" }, "images": [ { "id": "3ZUJBfy7M99jRh0YglPUQv", "fileName": "gold-ring.png", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png", "width": 240, "height": 240 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 350, "currency": "JPY" } ], "taxCategory": "DIGITAL_GOODS_AND_SERVICES", "createdAt": "2025-07-28T04:28:21.112Z", "updatedAt": "2025-07-28T04:28:21.112Z", "publishedAt": "2025-07-28T04:28:21.112Z" } }, { "quantity": 10, "item": { "id": "virtualitem_83f3aWcvJ4w", "sku": "diamond-currency", "label": { "en_US": "Diamond" }, "description": { "en_US": "" }, "images": [ { "id": "3jOZHd2Ht3uOL1bBxLGmeM", "fileName": "pngtree-blue-diamond-for-game-png-image_2914528.jpg", "url": "https://images.ctfassets.net/z82qbo7cv7ia/3jOZHd2Ht3uOL1bBxLGmeM/397c603cb7b968bfa9ebba2fcd21216e/pngtree-blue-diamond-for-game-png-image_2914528.jpg", "width": 360, "height": 360 } ], "defaultFiatCurrency": "JPY", "unitPrices": [ { "amount": 100, "currency": "JPY" } ], "taxCategory": "VIRTUAL_CURRENCY", "createdAt": "2025-09-12T02:35:53.272Z", "updatedAt": "2025-09-12T02:35:53.272Z", "publishedAt": "2025-09-12T02:35:53.272Z" } } ], "createdAt": "2025-07-28T12:43:28.991Z", "updatedAt": "2025-09-12T07:25:13.994Z", "publishedAt": "2025-09-12T07:25:13.994Z" } } ``` ## 번들 관리 여러 가상 아이템을 묶어 할인된 가격으로 판매할 수 있습니다. 번들 조회 시 다음을 참고하세요. - `include_items=true`로 구성 아이템 상세 정보를 받습니다. - 번들 가격은 개별 아이템 가격과 독립적입니다. - 각 구성 아이템에는 수량 정보가 있습니다. ## 오류 처리 API는 표준 HTTP 상태 코드와 상세 오류 메시지를 반환합니다. - `401 Unauthorized`: API 키가 없거나 유효하지 않습니다. - `404 Not Found`: 상품 또는 번들을 찾을 수 없습니다. - `429 Too Many Requests`: 요청 빈도 제한을 초과했습니다. - `500 Server Error`: 내부 서버 오류가 발생했습니다. 모든 오류 응답에는 코드에서 처리할 수 있도록 오류 코드와 메시지를 담은 구조화된 오류 객체가 포함됩니다. ## 얼리 액세스 현황 Product API는 얼리 액세스 단계입니다. 현재 기능과 제한 사항은 다음과 같습니다. **현재 제공:** - 가상 아이템 및 번들 관리 - 상품별 단일 통화 가격 - 기본 페이지네이션 및 필터 - 리치 미디어 첨부 - Checkout 연동 **제공 예정:** - 다국어 현지화 지원 - 향상된 필터 및 검색 기능 - 고급 재고 관리 기능 - 확장 API 엔드포인트 **알려진 제한 사항:** - 상품명과 설명의 현지화는 아직 지원되지 않습니다. - 일부 고급 필터 옵션이 제한될 수 있습니다. 이 기능들은 개발 중입니다. 얼리 액세스를 사용하면서 느낀 점이나 개선 의견을 알려 주세요.