--- title: ZEPETO.Product slug: world-sdk-guide-kr/zepetoproduct docTags: createdAt: 2026-09-04T06:31:09.209Z --- | 형식 | 설명 | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [BaseResponse](./#baseresponse) | 응답 클래스의 기본 클래스입니다. | | [BaseRequest](./#baserequest) | 응답 데이터로 제네릭 타입 `TResponse`를 받는 `BaseRequest` 클래스입니다. | | [ProductListResponse](./#productlistresponse) | `ProductListResponse` 클래스는 API 호출 결과와 가져온 상품 정보 목록을 제공합니다. | | [ProductBaseResponse](./#productbaseresponse) | 상품 관련 응답 클래스의 기본 클래스입니다. | | [ProductResponse](./#productresponse) | `ProductResponse` 클래스는 API 호출 결과와 가져온 상품 정보를 제공합니다. | | [PurchaseResponse](./#purchaseresponse) | `ProductResponse` 클래스는 API 호출 결과와 구매 정보를 제공합니다. | | [CurrencyListResponse](./#currencylistresponse) | `CurrencyListResponse` 클래스는 API 호출 결과와 재화 정보 목록을 제공합니다. | | [CurrencyResponse](./#currencyresponse) | `CurrencyResponse` 클래스는 API 호출 결과와 재화 정보를 제공합니다. | | [ProductRecord](./#productrecord) | 상품 정보입니다. | | [CurrencyRecord](./#currencyrecord) | 재화 정보입니다. | | [ItemPackageUnitRecord](./#itempackageunitrecord) | 아이템 상품 패키지에 포함된 개별 상품의 세부 정보입니다. | | [CurrencyPackageUnitRecord](./#currencypackageunitrecord) | 재화 상품 패키지에 포함된 개별 재화의 세부 정보입니다. | | [ProductType](./#producttype) | 상품 유형을 나타내는 열거형입니다. | | [PurchaseType](./#purchasetype) | 상품 구매 유형을 나타내는 열거형입니다. | | [ProductStatus](./#productstatus) | 상품 상태를 나타내는 열거형입니다. | | [CurrencyType](./#currencytype) | 재화 유형을 나타내는 열거형입니다. | | [ProductService](./#productservice) | `ProductService`는 World 내 상품과 관련된 작업을 관리합니다. 이 서비스를 통해 플레이어는 World 내 상품 정보에 접근하고 구매를 진행할 수 있습니다. | | [ProductPurchaseButton](./#productpurchasebutton) | World 내 상품 구매 버튼의 기능을 관리하는 클래스입니다. | | [ProductError](./#producterror) | 상품 관련 요청이 실패한 원인을 나타내는 오류 코드입니다. | | [OfficialCurrencyBalanceRequest](./#officialcurrencybalancerequest) | ZEPETO 공식 재화(ZEM)의 잔액을 가져오기 위한 비동기 요청을 나타냅니다. | ## BaseResponse `class` 응답 클래스의 기본 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | --------- | --------- | ----------------------------------------- | | isSuccess | `boolean` | 요청의 성공 여부를 나타냅니다. 정상적으로 완료되면 true로 설정됩니다. | | message | `string` | 요청 결과를 설명합니다. | ## BaseRequest `class` · extends `BaseAPIRequest` 응답 데이터로 제네릭 타입 `TResponse`를 받는 `BaseRequest` 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | ------------ | ----------- | ------------------------------ | | responseData | `TResponse` | 제네릭 타입 `TResponse`의 응답 데이터입니다. | ## ProductListResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `ProductListResponse` 클래스는 API 호출 결과와 가져온 상품 정보 목록을 제공합니다. ### 속성 | 이름 | 형식 | 설명 | | -------- | ------------------------------------- | ------------ | | products | [ProductRecord\[\]](./#productrecord) | 상품 정보 목록입니다. | ## ProductBaseResponse `class` · extends [BaseResponse](./#baseresponse) 상품 관련 응답 클래스의 기본 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | --------- | ------------------------------- | ------------------------ | | ErrorCode | [ProductError](./#producterror) | 실패한 상품 요청의 오류 코드를 가져옵니다. | ## ProductResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `ProductResponse` 클래스는 API 호출 결과와 가져온 상품 정보를 제공합니다. ### 속성 | 이름 | 형식 | 설명 | | ------- | --------------------------------- | --------- | | product | [ProductRecord](./#productrecord) | 상품 정보입니다. | ## PurchaseResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `ProductResponse` 클래스는 API 호출 결과와 구매 정보를 제공합니다. ### 속성 | 이름 | 형식 | 설명 | | ----------- | -------- | -------------------------- | | userId | `string` | 구매를 진행한 플레이어의 사용자 ID입니다. | | productId | `string` | 구매한 World 내 상품의 ID입니다. | | price | `number` | 구매한 World 내 상품의 가격입니다. | | receiptId | `string` | 구매의 영수증 ID입니다. | | purchasedAt | `Date` | World 내 상품을 구매한 날짜와 시간입니다. | ## CurrencyListResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `CurrencyListResponse` 클래스는 API 호출 결과와 재화 정보 목록을 제공합니다. ### 속성 | 이름 | 형식 | 설명 | | ---------- | --------------------------------------- | ------------ | | currencies | [CurrencyRecord\[\]](./#currencyrecord) | 재화 정보 목록입니다. | ## CurrencyResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `CurrencyResponse` 클래스는 API 호출 결과와 재화 정보를 제공합니다. ### 속성 | 이름 | 형식 | 설명 | | -------- | ----------------------------------- | --------- | | currency | [CurrencyRecord](./#currencyrecord) | 재화 정보입니다. | ## ProductRecord `class` 상품 정보입니다. ### 속성 | 이름 | 형식 | 설명 | | -------------------- | ------------------------------------------------------------- | --------------------------------------------------- | | productId | `string` | 상품 ID입니다. | | name | `string` | 상품 이름입니다. | | price | `number` | 상품 가격입니다. | | isPurchased | `boolean` | 사용자가 해당 상품을 구매했는지 여부를 나타냅니다. 비소모성 상품에만 적용됩니다. | | itemPackageUnits | [ItemPackageUnitRecord\[\]](./#itempackageunitrecord) | `ProductType`이 `ItemPackage`인 경우 상품에 포함된 아이템입니다. | | currencyPackageUnits | [CurrencyPackageUnitRecord\[\]](./#currencypackageunitrecord) | `ProductType`이 `CurrencyPackage`인 경우 상품에 포함된 재화입니다. | | ProductType | [ProductType](./#producttype) | 상품의 `ProductType`을(를) 반환합니다. | | PurchaseType | [PurchaseType](./#purchasetype) | 상품의 `PurchaseType`을(를) 반환합니다. | | ProductStatus | [ProductStatus](./#productstatus) | 상품의 `ProductStatus`을(를) 반환합니다. | | CurrencyType | [CurrencyType](./#currencytype) | 상품 구매에 사용되는 재화의 유형을 반환합니다. | | currencyId | `string` | 상품 구매에 사용되는 재화의 ID를 반환합니다. | | currencyName | `string` | 상품 구매에 사용되는 재화의 이름을 반환합니다. | ### 메서드 ### GetCurrencySprite `GetCurrencySprite() → Sprite` 상품 구매에 사용되는 재화의 이미지를 반환합니다. **반환값:** `Sprite` ## CurrencyRecord `class` 재화 정보입니다. ### 속성 | 이름 | 형식 | 설명 | | ------------------ | --------- | ----------------------------------------------- | | currencyId | `string` | 재화 ID입니다. | | name | `string` | 재화 이름입니다. | | isOfficialCurrency | `boolean` | 해당 재화가 ZEPETO 공식 재화(ZEM)인지 World 내 재화인지를 나타냅니다. | ## ItemPackageUnitRecord `class` 아이템 상품 패키지에 포함된 개별 상품의 세부 정보입니다. ### 속성 | 이름 | 형식 | 설명 | | --------- | -------- | ---------- | | productId | `string` | 상품 ID입니다. | | itemName | `string` | 아이템 이름입니다. | | quantity | `bigint` | 아이템 수량입니다. | ## CurrencyPackageUnitRecord `class` 재화 상품 패키지에 포함된 개별 재화의 세부 정보입니다. ### 속성 | 이름 | 형식 | 설명 | | ------------ | -------- | --------- | | currencyId | `string` | 재화 ID입니다. | | currencyName | `string` | 재화 이름입니다. | | quantity | `bigint` | 재화 수량입니다. | ## ProductType `enum` 상품 유형을 나타내는 열거형입니다. | 이름 | 값 | 설명 | | --------------- | - | --------------------------- | | Item | 0 | 단일 아이템 상품입니다. | | ItemPackage | 1 | 여러 아이템을 포함하는 아이템 상품 패키지입니다. | | CurrencyPackage | 2 | 여러 재화를 포함하는 재화 상품 패키지입니다. | ## PurchaseType `enum` 상품 구매 유형을 나타내는 열거형입니다. | 이름 | 값 | 설명 | | ------------- | - | ----------- | | Consumable | 0 | 소모성 상품입니다. | | NonConsumable | 1 | 비소모성 상품입니다. | ## ProductStatus `enum` 상품 상태를 나타내는 열거형입니다. | 이름 | 값 | 설명 | | --------- | - | ----------------------- | | Active | 0 | 활성 상태입니다. | | InActive | 1 | 비활성 상태입니다. | | Forbidden | 2 | 이용 기간 만료로 인해 금지된 상태입니다. | ## CurrencyType `enum` 재화 유형을 나타내는 열거형입니다. | 이름 | 값 | 설명 | | ---------------- | - | ----------------- | | OfficialCurrency | 0 | ZEPETO 공식 재화(ZEM) | | UserCurrency | 1 | World 내 재화입니다. | ## ProductService `class` `ProductService`는 World 내 상품과 관련된 작업을 관리합니다. 이 서비스를 통해 플레이어는 World 내 상품 정보에 접근하고 구매를 진행할 수 있습니다. ### 이벤트 | 이름 | 형식 | 설명 | | ---------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | OnPurchaseCompleted (static) | `UnityEvent` | World 내 상품 구매에 성공했을 때 발생하는 이벤트입니다. 리스너를 추가할 수 있으며, `ProductRecord`(구매한 상품 정보)와 `PurchaseResponse`(구매 결과 정보) 인스턴스가 인자로 전달됩니다. | | OnPurchaseFailed (static) | `UnityEvent` | World 내 상품 구매에 실패했을 때 발생하는 이벤트입니다. 리스너를 추가할 수 있으며, `ProductRecord`(구매를 시도한 상품 정보)와 `PurchaseResponse`(실패한 구매 결과 정보) 인스턴스가 인자로 전달됩니다. | ### 메서드 ### GetProductsAsync `static GetProductsAsync(productIds: string[]) → BaseRequest` 전달된 상품 ID를 기준으로 World 내 상품 목록을 가져오는 비동기 메서드입니다. | 매개변수 | 형식 | 설명 | | ---------- | ---------- | --------------- | | productIds | `string[]` | 가져올 상품들의 ID입니다. | **반환값:** [BaseRequest\](./#baserequest) — `BaseRequest` 객체입니다. 비동기 처리가 완료되면 `responseData` 속성을 통해 `ProductListResponse` 객체에 접근할 수 있습니다. ### GetProductAsync `static GetProductAsync(productId: string) → BaseRequest` 전달된 상품 ID를 기준으로 World 내 상품 정보를 가져오는 비동기 메서드입니다. | 매개변수 | 형식 | 설명 | | --------- | -------- | -------------- | | productId | `string` | 가져올 상품의 ID입니다. | **반환값:** [BaseRequest\](./#baserequest) — `BaseRequest` 객체입니다. 비동기 처리가 완료되면 `responseData` 속성을 통해 `ProductResponse` 객체에 접근할 수 있습니다. ### PurchaseProductAsync `static PurchaseProductAsync(product: ProductRecord, reason?: string) → BaseRequest` 전달된 상품 정보를 기준으로 World 내 상품을 구매하는 비동기 메서드입니다. | 매개변수 | 형식 | 설명 | | -------------- | --------------------------------- | -------------------------------- | | product | [ProductRecord](./#productrecord) | 구매할 상품의 `ProductRecord` 인스턴스입니다. | | reason (선택 사항) | `string` | 구매에 대한 설명입니다. | **반환값:** [BaseRequest\](./#baserequest) — `BaseRequest` 객체입니다. 비동기 처리가 완료되면 `responseData` 속성을 통해 `PurchaseResponse` 객체에 접근할 수 있습니다. ### PurchaseProductAsync `static PurchaseProductAsync(productId: string, reason?: string) → BaseRequest` 전달된 상품 ID를 기준으로 World 내 상품을 구매하는 비동기 메서드입니다. | 매개변수 | 형식 | 설명 | | -------------- | -------- | -------------- | | productId | `string` | 구매할 상품의 ID입니다. | | reason (선택 사항) | `string` | 구매에 대한 설명입니다. | **반환값:** [BaseRequest\](./#baserequest) — `BaseRequest` 객체입니다. 비동기 처리가 완료되면 `responseData` 속성을 통해 `PurchaseResponse` 객체에 접근할 수 있습니다. ### GetCurrenciesAsync `static GetCurrenciesAsync() → BaseRequest` 재화 목록을 가져오는 비동기 메서드입니다. 처리가 완료되면 재화 목록을 얻을 수 있으며, `responseData` 속성을 통해 `CurrencyListResponse` 객체에 접근할 수 있습니다. **반환값:** [BaseRequest\](./#baserequest) ### GetCurrencyAsync `static GetCurrencyAsync(currencyId: string) → BaseRequest` 전달된 상품 ID를 기준으로 World 내 재화 정보를 가져오는 비동기 메서드입니다. | 매개변수 | 형식 | 설명 | | ---------- | -------- | -------------- | | currencyId | `string` | 가져올 재화의 ID입니다. | **반환값:** [BaseRequest\](./#baserequest) — `BaseRequest` 객체입니다. 비동기 처리가 완료되면 `responseData` 속성을 통해 `CurrencyResponse` 객체에 접근할 수 있습니다. ### OpenPurchaseUI `static OpenPurchaseUI(product: ProductRecord) → void` 이 메서드는 World 내 상품 구매 UI를 엽니다. | 매개변수 | 형식 | 설명 | | ------- | --------------------------------- | -------------------------------- | | product | [ProductRecord](./#productrecord) | 구매할 상품의 `ProductRecord` 인스턴스입니다. | ## ProductPurchaseButton `class` World 내 상품 구매 버튼의 기능을 관리하는 클래스입니다. ### 속성 | 이름 | 형식 | 설명 | | --------- | --------------------------------- | -------------------------------------- | | productId | `string` | 구매 가능한 World 내 상품의 ID를 가져옵니다. | | product | [ProductRecord](./#productrecord) | `productId`에 연결된 World 내 상품 정보를 가져옵니다. | ### 메서드 ### SetProductId `SetProductId(productId: string) → void` 이 버튼으로 구매할 수 있는 World 내 상품의 ID를 설정합니다. | 매개변수 | 형식 | 설명 | | --------- | -------- | --------- | | productId | `string` | 상품 ID입니다. | ## ProductError `enum` 상품 관련 요청이 실패한 원인을 나타내는 오류 코드입니다. | 이름 | 값 | 설명 | | -------------------------------- | ---- | ---------------------------------------------------------------------------------- | | Unknown | -1 | 오류: 알 수 없는 오류입니다. | | NetworkError | 0 | 오류: 연결 끊김이나 불안정한 연결 등 네트워크 문제와 관련된 오류입니다. | | UserCanceled | 1 | 오류: 사용자가 요청을 취소했습니다. | | ProductRefreshResponseError | 2 | 오류: 요청의 상품 메타데이터가 유효하지 않습니다. | | ItemPackageProductsResponseError | 3 | 오류: 아이템 상품 패키지 내 하나 이상의 아이템 정보를 가져오지 못했습니다. | | IAPCardError | 4 | 오류: 재화 상품 패키지 내 하나 이상의 재화 정보를 가져오지 못했습니다. | | ProductPriceChanged | 4001 | 오류: 상품 가격이 일치하지 않습니다. | | ProductAlreadyPurchased | 4002 | 오류: 이미 구매한 상품입니다. | | BalanceOfficialCurrencyNotEnough | 4003 | 오류: 구매에 필요한 ZEPETO 공식 재화(ZEM) 잔액이 부족합니다. | | BalanceUserCurrencyNotEnough | 4004 | 오류: 구매에 필요한 World 내 재화 잔액이 부족합니다. | | ProductNotActive | 4005 | 오류: 상품이 활성 상태가 아닙니다. | | InvalidCreator | 4006 | 오류: 플레이어의 사용자 ID가 World 크리에이터의 사용자 ID와 다릅니다. 이 오류는 Unity 에디터를 사용하는 개발 환경에서만 발생합니다. | ## OfficialCurrencyBalanceRequest `class` · extends [BaseRequest\](./#baserequest) ZEPETO 공식 재화(ZEM)의 잔액을 가져오기 위한 비동기 요청을 나타냅니다.