콘텐츠로 건너뛰기

카탈로그 API (2.0.0)

개요

  • 버전: 2.0.0
  • 서버: https://store.xsolla.com/api
  • 이메일로 문의하기
  • 연락처 URL: https://xsolla.com/
  • 필수 TLS 버전: 1.2

카탈로그 API를 통해 엑솔라 측 인게임 아이템에 대한 카탈로그를 구성하고 스토어 사용자에게 카탈로그를 표시합니다.

API를 통해 다음 카탈로그 엔터티를 관리할 수 있습니다:

  • 가상 아이템 - 무기, 스킨, 부스터와 같은 인게임 아이템.
  • 인게임 재화 - 가상 아이템을 구매하는 데 사용되는 가상 화폐.
  • 인게임 재화 패키지 - 사전 정의된 인게임 재화 번들.
  • 번들 - 가상 아이템, 통화 또는 단일 SKU로 판매되는 게임 키의 결합 패키지.
  • 게임 키 - Steam이나 기타 DRM 제공업체와 같은 플랫폼을 통해 배포되는 게임 및 DLC의 키.
  • 그룹 - 카탈로그 내 아이템을 정리하고 분류하기 위한 로직 그룹.

API 호출

API는 다음 그룹으로 구분됩니다:

  • Admin - 카탈로그 아이템 및 그룹 생성, 업데이트, 삭제 및 구성을 위한 호출. 상품 또는 프로젝트 자격 증명으로 기본 액세스 인증을 통해 인증됩니다. 스토어프런트 용도로 사용되지 않습니다.
  • Catalog - 아이템 검색 및 최종 사용자를 위한 맞춤형 스토어프론트 구축을 위한 호출. 높은 부하 시나리오를 처리하도록 설계되었습니다. 사용자별 한도나 진행 중인 프로모션과 같은 개인화된 데이터를 반환하기 위해 선택적 사용자 JWT 인증을 지원합니다.

인증

API 호출은 사용자 또는 프로젝트를 대신하여 인증이 필요합니다. 사용된 인증 체계는 각 호출 설명의 보안 섹션에 명시되어 있습니다.

사용자의 JWT를 사용한 인증

사용자의 JWT 인증은 브라우저, 모바일 애플리케이션 또는 게임에서 요청이 전송될 때 사용됩니다. 기본적으로 XsollaLoginUserJWT 체계가 적용됩니다. 토큰 생성 방법에 대한 자세한 내용은 엑솔라 로그인 API 문서를 참조하십시오.

토큰은 다음 형식으로 Authorization 헤더에 전달됩니다: Authorization: Bearer <user_JWT>, 여기에서 <user_JWT>는 사용자 토큰입니다. 이 토큰은 사용자를 식별하고 개인화된 데이터에 대한 액세스를 제공합니다.

또는 결제 UI를 여는 토큰을 사용할 수 있습니다.

기본 HTTP 인증

기본 HTTP 인증은 서버 간 상호작용에 사용되며, API 호출이 사용자의 브라우저나 모바일 애플리케이션이 아닌 서버에서 직접 전송될 때 사용됩니다. 일반적으로 API 키를 사용한 HTTP 기본 인증이 사용됩니다.

참고

API 키는 기밀이며 클라이언트 애플리케이션에 저장하거나 사용해서는 안 됩니다.

기본 서버 측 인증을 사용하면 모든 API 요청에 다음 헤더를 포함해야 합니다:

  • basicAuth의 경우 - Authorization: Basic <your_authorization_basic_key>, 여기에서 your_authorization_basic_key는 Base64로 인코딩된 project_id:api_key 쌍입니다.
  • basicMerchantAuth의 경우 - Authorization: Basic <your_authorization_basic_key>, 여기에서 your_authorization_basic_key는 Base64로 인코딩된 merchant_id:api_key 쌍입니다.

관리자 페이지에서 매개 변수 값을 찾을 수 있습니다:

  • merchant_id는 다음 위치에 표시됩니다:
    • Company settings > Company에서.
    • 관리자 페이지의 모든 페이지에서 브라우저 주소 표시줄의 URL에. URL 형식은 다음과 같습니다: https://publisher.xsolla.com/<merchant_id>.
  • project_id는 다음 위치에 표시됩니다:
    • 관리자 페이지에서 프로젝트 이름 옆.
    • 관리자 페이지에서 프로젝트 작업 시 브라우저 주소 표시줄의 URL. URL 형식은 다음과 같습니다: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
  • api_key는 생성 시에만 관리자 페이지에 표시되며 귀하의 측에서 안전하게 저장해야 합니다. API 키는 다음 섹션에서 생성할 수 있습니다:
알림

필수 API 호출에 project_id 경로 매개 변수가 포함되지 않은 경우, 모든 회사 프로젝트에 대해 유효한 API 키를 사용하여 인증하십시오.

API 키 작업에 대한 자세한 내용은 API 참조 문서를 참조하십시오.

게스트 액세스 지원을 통한 인증

이 AuthForCart 인증 체계는 장바구니 구매에 사용되며 두 가지 모드를 지원합니다.

  1. 사용자의 JWT를 사용한 인증. 토큰은 다음 형식으로 Authorization 헤더에 전달됩니다: Authorization: Bearer <user_JWT>, 여기에서 <user_JWT>는 사용자 토큰입니다. 이 토큰은 사용자를 식별하고 개인화된 데이터에 대한 액세스를 제공합니다. 또한, 결제 UI 열기 위한 토큰을 사용할 수 있습니다.

  2. Simplified mode without Authorization header. 이 모드는 미인증 사용자만 사용하며, 게임 키 판매에만 적용할 수 있습니다. 토큰 대신 요청에 다음 헤더를 포함해야 합니다.

    • 요청 ID와 x-unauthorized-id
    • Base64로 인코딩된 사용자의 이메일 주소와 x-user

핵심 엔티티 구조

모든 유형의 아이템(가상 아이템, 번들, 인게임 재화, 키)은 유사한 데이터 구조를 사용합니다. 기본 구조를 이해하면 API 작업이 간소화되고 문서를 더 쉽게 탐색할 수 있습니다.

참고

일부 호출에는 추가 입력란이 포함될 수 있지만 기본 구조는 변경되지 않습니다.

식별

  • merchant_id- 관리자 페이지의 회사 ID
  • project_id - 관리자 페이지의 프로젝트 ID
  • sku - 프로젝트 내의 고유한 아이템 SKU

Store display

  • name - 아이템 이름
  • description - 아이템 설명
  • image_url - 이미지 URL
  • is_enabled - 아이템 가용성
  • is_show_in_store - 카탈로그에 아이템이 표시되는지 여부

카탈로그에서 아이템 가용성 관리에 대한 자세한 정보는 문서를 참조하세요.

Organization

  • type - 아이템 유형, 예를 들어 가상 아이템(virtual_item) 또는 번들(bundle)
  • groups - 아이템이 속한 그룹
  • order - 카탈로그 내 디스플레이 순서

판매 조건

  • prices - 실제 화폐 또는 인게임 재화로 된 가격
  • limits - 구매 한도
  • periods - 가용 기간
  • regions - 지역 제한

핵심 엔티티 구조 예시:

{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "content": [
    {
      "description": {
        "en": "Main in-game currency"
      },
      "image_url": "https://.../image.png",
      "name": {
        "en": "Crystals",
        "de": "Kristalle"
      },
      "quantity": 500,
      "sku": "com.xsolla.crystal_2",
      "type": "virtual_currency"
    }
  ],
  "description": {
    "en": "Crystals x500"
  },
  "groups": [],
  "image_url": "https://.../image.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "limits": {
    "per_item": null,
    "per_user": null,
    "recurrent_schedule": null
  },
  "long_description": null,
  "media_list": [],
  "name": {
    "en": "Medium crystal pack"
  },
  "order": 1,
  "periods": [
    {
      "date_from": null,
      "date_until": "2020-08-11T20:00:00+03:00"
    }
  ],
  "prices": [
    {
      "amount": 20,
      "country_iso": "US",
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "regions": [],
  "sku": "com.xsolla.crystal_pack_2",
  "type": "bundle",
  "vc_prices": []
}

기본 구매 흐름

엑솔라 API를 사용하면 아이템 카탈로그 검색, 장바구니 관리, 주문 생성 및 상태 추적을 포함한 인게임 스토어 로직을 구현할 수 있습니다. 통합 시나리오에 따라 API 호출은 Admin와 Catalog 하위 섹션으로 구분되며, 서로 다른 인증 방식을 사용합니다.

다음 예시는 아이템 생성부터 구매까지 스토어 설정 및 운영을 위한 기본 흐름을 보여줍니다.

아이템 및 그룹 생성(관리자)

가상 아이템, 번들, 인게임 재화와 같은 스토어의 아이템 카탈로그를 생성합니다.

예시 API 호출:

프로모션, 체인 및 한도 설정(관리자)

할인, 보너스, 일일 보상 또는 혜택 체인과 같은 사용자 획득 및 수익화 도구를 구성합니다.

예시 API 호출:

아이템 정보 가져오기(클라이언트)

애플리케이션에서 아이템 디스플레이를 구성합니다.

알림

사용자 카탈로그를 구축하는 데 관리자 하위 섹션의 API 호출을 사용하지 마십시오. 이러한 API 호출에는 속도 제한이 있으며 사용자 트래픽을 위한 것이 아닙니다.

API 호출 예시:

참고

기본적으로 카탈로그 API 호출은 요청 시점에 스토어에서 현재 사용 가능한 아이템을 반환합니다. 아직 사용 가능하지 않거나 더 이상 사용 가능하지 않은 아이템을 검색하려면 카탈로그 요청에 "show_inactive_time_limited_items": 1 매개 변수를 포함하십시오.

아이템 판매

다음 방법을 사용하여 아이템을 판매할 수 있습니다:

  • 빠른 구매 - 하나의 SKU를 여러 번 판매합니다.
  • 장바구니 구매 - 사용자가 장바구니에 아이템을 추가하고, 제거하고, 수량을 업데이트합니다.

아이템이 실제 돈 대신 인게임 재화로 구매된 경우, 인게임 재화로 구매한 특정 아이템으로 주문 생성 API 호출을 사용하십시오. 결제 UI는 필요하지 않으며, API 호출이 실행될 때 청구가 처리됩니다.

무료 아이템 구매의 경우, 특정 무료 아이템으로 주문 생성 API 호출 또는 무료 장바구니로 주문 생성 API 호출을 사용하십시오. 결제 UI는 필요하지 않으며, 주문은 즉시 done 상태로 설정됩니다.

빠른 구매

클라이언트 측 API 호출을 사용하여 특정 아이템으로 주문 생성을 수행합니다. 호출은 결제 UI를 열기 위한 토큰을 반환합니다.

참고

할인 정보는 결제 UI에서만 사용자에게 제공됩니다. 프로모션 코드는 지원되지 않습니다.

장바구니 구매

장바구니 설정 및 구매는 클라이언트 또는 서버 측에서 수행할 수 있습니다.

클라이언트에서 장바구니 설정 및 구매

아이템 추가 및 제거 로직을 직접 구현하십시오. 장바구니 설정을 위한 API 호출 전에는 구매에 적용될 프로모션에 대한 정보를 알 수 없습니다. 이는 총 비용과 추가 보너스 아이템의 세부 사항을 알 수 없음을 의미합니다.

다음 장바구니 로직을 구현하십시오:

  1. 플레이어가 장바구니를 채운 후, 아이템으로 장바구니 채우기 API 호출을 사용하십시오. 호출은 선택한 아이템에 대한 현재 정보를 반환합니다 (할인 전후 가격, 보너스 아이템).
  2. 사용자 작업에 따라 장바구니 내용을 업데이트하십시오:
참고

현재 장바구니 상태를 얻으려면 현재 사용자의 장바구니 가져오기 API 호출을 사용하십시오.
  1. 현재 장바구니의 모든 아이템으로 주문 생성 API 호출을 사용하십시오. 호출은 주문 ID와 결제 토큰을 반환합니다. 새로 생성된 주문은 기본적으로 new 상태로 설정됩니다.

서버에서 장바구니 설정 및 구매

이 설정 옵션은 장바구니 설정에 더 많은 시간이 걸릴 수 있습니다. 장바구니의 각 변경 사항은 API 호출을 동반해야 하기 때문입니다.

다음 장바구니 로직을 구현하십시오:

  1. 플레이어가 장바구니를 채운 후, 아이템으로 장바구니 채우기 API 호출을 사용하십시오. 호출은 선택한 아이템에 대한 현재 정보를 반환합니다(할인 전후 가격, 보너스 아이템).
  2. 현재 장바구니의 모든 아이템으로 주문 생성 API 호출을 사용하십시오. 호출은 주문 ID와 결제 토큰을 반환합니다. 새로 생성된 주문은 기본적으로 new 상태로 설정됩니다.

결제 UI 열기

반환된 토큰을 사용하여 새 창에서 결제 UI를 엽니다. 결제 UI를 여는 다른 방법은 문서에 설명되어 있습니다.

작업엔드포인트
프로덕션 환경에서 열기.https://secure.xsolla.com/paystation4/?token={token}
샌드박스 모드에서 열기.https://sandbox-secure.xsolla.com/paystation4/?token={token}
참고

개발 및 테스트 중에는 샌드박스 모드를 사용하세요. 테스트 구매는 실제 계정에 청구되지 않습니다. 테스트 은행 카드를 사용할 수 있습니다.

첫 번째 실제 결제가 이루어진 후에는 엄격한 샌드박스 결제 정책이 적용됩니다. 샌드박스 모드에서의 결제는 관리자 페이지 > 회사 설정 > 사용자에 지정된 사용자에게만 가능합니다.

실제 통화로 인게임 재화와 아이템을 구매하려면 엑솔라와의 라이선스 계약을 체결해야 합니다. 이를 위해 관리자 페이지에서 Agreements & Taxes > Agreements으로 이동하여 계약 양식을 작성하고 확인을 기다리세요. 계약 검토에는 최대 3영업일이 소요될 수 있습니다.

샌드박스 모드를 활성화하거나 비활성화하려면 빠른 구매 및 장바구니 구매 요청에서 sandbox 매개 변수의 값을 변경하세요. 기본적으로 샌드박스 모드는 꺼져 있습니다.

가능한 주문 상태:

  • new - 주문 생성됨
  • paid - 결제 완료됨
  • done - 아이템 전달됨
  • canceled - 주문 취소됨
  • expired -주문 만료됨

다음 방법 중 하나를 사용하여 주문 상태를 추적하세요:

페이지 매김

대량의 레코드를 반환하는 API 호출(예: 카탈로그 작성 시)은 데이터를 페이지 단위로 반환합니다. 페이지 매김은 단일 API 응답에서 반환되는 항목 수를 제한하고 이후 페이지를 순차적으로 검색할 수 있는 메커니즘입니다.

반환되는 아이템 수를 제어하기 위해 다음 매개 변수를 사용하세요:

  • limit - 페이지당 항목 수
  • offset - 페이지의 첫 번째 항목의 인덱스(번호는 0부터 시작)
  • has_more - 다른 페이지가 있는지 여부를 나타냄
  • total_items_count - 총 항목 수

요청 예시:

GET /items?limit=20&offset=40

응답 예시:

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

응답이 has_more = false를 반환할 때까지 후속 요청을 보내는 것이 좋습니다.

날짜 및 시간 형식

날짜 및 시간 값은 ISO 8601 형식으로 전달됩니다.

다음이 지원됩니다:

  • UTC 오프셋
  • 항목 표시 시간 제한이 없는 경우 null 값
  • 일부 입력란에서 사용되는 Unix 타임스탬프(초 단위)

형식: YYYY-MM-DDTHH:MM:SS±HH:MM

예시: 2026-03-16T10:00:00+03:00

현지화

엑솔라는 항목 이름 및 설명과 같은 사용자 대상 입력란의 현지화를 지원합니다. 현지화된 값은 언어 코드를 키로 사용하는 개체로 전달됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

Supported fields

다음 매개 변수에 대해 현지화를 지정할 수 있습니다:

  • name
  • description
  • long_description

Locale format

로케일 키는 다음 형식 중 하나로 지정할 수 있습니다:

  • 두 글자 언어 코드: en, ru
  • 다섯 글자 언어 코드: en-US, ru-RU, de-DE

Examples

두 글자 언어 코드 예시:

{
  "name": {
    "en": "Starter Pack",
    "ru": "Стартовый набор"
  }
}

다섯 글자 언어 코드 예시:

{
  "description": {
    "en-US": "Premium bundle",
    "de-DE": "Premium-Paket"
  }
}

오류 응답 형식

오류가 발생하면, API는 HTTP 상태와 JSON 응답 본문을 반환합니다. 스토어 관련 오류의 전체 목록은 문서에서 확인할 수 있습니다.

Response example:

{
  "errorCode": 1102,
  "errorMessage": "Validation error",
  "statusCode": 422,
  "transactionId": "c9e1a..."
}
  • errorCode - 오류 코드.
  • errorMessage - 짧은 오류 설명.
  • statusCode - HTTP 응답 상태.
  • transactionId - 요청 ID. 일부 경우에만 반환됩니다.
  • errorMessageExtended - 요청 매개 변수와 같은 추가 오류 세부 정보. 일부 경우에만 반환됩니다.

Extended response example:

{
  "errorCode": 7001,
  "errorMessage": "Chain not found",
  "errorMessageExtended": {
    "chain_id": "test_chain_id",
    "project_id": "test_project_id",
    "step_number": 2
  },
  "statusCode": 404
}

Common HTTP status codes

  • 400 - 잘못된 요청
  • 401 - 인증 오류
  • 403 - 권한 부족
  • 404 - 리소스를 찾을 수 없음
  • 422 - 유효성 검사 오류
  • 429 - 속도 제한 초과

Recommendations

  • HTTP 상태와 응답 본문을 함께 처리하세요.
  • errorCode를 사용하여 애플리케이션 로직과 관련된 오류를 처리하세요.
  • transactionId를 사용하여 오류 분석 시 요청을 더 빠르게 식별하세요.
OpenAPI 설명 다운로드
index.json
index.yaml
언어
서버
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ko/api/catalog/

개요

가상 아이템과 인게임 재화를 사용하여 인게임 스토어를 구축하고 사용자에게 어떻게 디스플레이할지를 구성할 수 있습니다. 다음과 같은 아이템 유형이 제공됩니다:

  • 가상 아이템 - 무기, 스킨, 부스터와 같은 인게임 상품. 실제 돈이나 가상 머니로 판매할 수 있습니다.
  • 가상 머니 - 가상 아이템을 구매하는 데 사용되는 인게임 화폐. 실제 돈이나 인게임 재화로 판매할 수 있습니다.
  • 인게임 재화 패키지 - 고정된 양의 인게임 재화. 실제 돈이나 인게임 재화로 판매할 수 있습니다.

그룹은 카탈로그에서 아이템을 구성하는 데 사용됩니다. 아이템을 논리적으로 그룹화하고 디스플레이 방식을 관리할 수 있습니다.

Admin 하위 섹션의 API 호출을 사용하여 아이템을 생성, 업데이트 및 삭제하세요.

Catalog 하위 섹션의 API 호출을 사용하여 아이템 목록을 검색하고 사용자에게 디스플레이하세요.

알림

스토어 카탈로그를 작성하는 데 Admin 하위 섹션의 API 호출을 사용하지 마세요.

참고

가상 아이템 목록 가져오기 API 호출은 가격 및 특성을 포함한 자세한 아이템 데이터를 반환하며, 페이지 매김을 지원합니다. 스토어프론트에서 카탈로그 페이지를 표시하는 데 사용하세요.

모든 가상 아이템 목록 가져오기 API 호출은 페이지 매김 없이 아이템 SKU, 이름, 설명, 그룹 ID 및 이름을 반환합니다. 클라이언트 측 검색 또는 색인에 사용하세요.

인게임 재화로 구매할 경우, 인게임 재화로 구매한 지정된 아이템으로 주문 생성 API 호출을 사용하세요. 결제 UI는 필요하지 않으며, API 호출이 실행될 때 청구가 처리됩니다.

인게임 재화를 사용한 구매 절차 예시:

인게임 재화를 사용한 구매 절차 예시

관리자

작업

카탈로그

작업

가상 결제

작업

개요

게임 키는 게임 플랫폼에서 사용자가 게임이나 DLC에 접근할 수 있도록 해주는 일회용 고유 영숫자 코드입니다. 직접 링크, 스토어 UI, 또는 위젯을 통해 게임 키를 판매할 수 있습니다. 또한 지역 제한 설정을 통해 특정 국가에서만 게임 키를 판매하도록 설정할 수 있습니다. 자세한 내용은 게임 키 패키지 섹션을 참조해 주세요.

게임 키를 판매하는 데 사용자 인증은 필요하지 않습니다. 키는 사용자가 결제 시 지정한 이메일 주소로 발송됩니다. 추가 시나리오를 활성화하기 위해 인증을 구성할 수 있습니다. 사용자 맞춤 설정, 구매 제한, 또는 자격 시스템. 자세한 내용은 게임 키 판매 시 인증 설정 방법 섹션을 참조해 주세요.

게임 키 판매 절차:

  1. 게임 생성 API 호출을 사용하여 게임을 생성합니다.
  2. 지역 제한을 구성합니다.
  3. 코드 업로드 API 호출을 사용하여 게임 키 패키지에 키를 업로드하고 구매가 가능하게 합니다.
  4. 게임 목록 가져오기 API 호출을 사용하여 사용자의 지역에 맞는 가격이 포함된 게임 카탈로그를 표시합니다.
  5. 주문을 생성합니다. 빠른 구매를 위해 게임 키 SKU를 전달하여 현재 장바구니의 모든 아이템으로 주문 생성 API 호출을 사용할 수 있습니다. 응답으로 결제 UI를 열기 위한 토큰이 반환됩니다.
  6. 주문 결제를 위해 결제 UI 열기를 구현합니다.

결제 성공 알림을 실시간으로 받고 사용자에게 아이템을 전달하려면, 웹훅 등을 사용하여 주문 상태 추적을 설정하세요. 키는 사용자가 결제 시 지정한 이메일로 전송되며, 주문 상태가 done으로 변경됩니다.

게임 키

카탈로그

작업

권한

작업

관리자

작업

개요

번들은 하나의 단위로 판매되는 아이템 세트입니다. 번들에는 가상 아이템, 인게임 재화, 인게임 재화 패키지, 게임 키 및 기타 번들이 포함될 수 있습니다. 번들을 활용하여 스타터 팩, 시즌 한정 혜택 및 특별 상품을 구성해 보세요.

번들을 처리하려면 다음 API 호출 그룹을 사용하세요.

  • 번들을 생성, 업데이트, 삭제하고 번들의 표시 여부를 관리하려면 관리자 섹션의 API 호출을 사용하세요.
  • 번들을 불러오려면 카탈로그 섹션의 API 호출을 사용하세요.

구매 한도는 번들을 생성하거나 업데이트할 때 limits 개체를 통해 구성됩니다. 자세한 내용은 한도 개요를 참조해 주세요. 지역 제한을 설정하여 특정 국가에서만 아이템을 판매할 수도 있습니다.

참고

번들 구성에 대한 자세한 내용은 번들 섹션을 참조해 주세요.

번들 관리 시나리오:

  1. 번들 생성 API 호출을 사용하여 번들을 생성합니다. 생성한 번들을 확인하려면 번들 가져오기 API 호출을 사용합니다. 프로젝트의 모든 번들을 검색하려면 번들 목록 가져오기 API 호출을 사용합니다.
  2. 필요한 경우 번들 업데이트 API 호출을 사용하여 번들 콘텐츠 또는 설정을 수정합니다.
  3. 번들 목록 가져오기, 지정한 번들 가져오기 또는 지정한 그룹별 번들 목록 가져오기 API 호출을 사용하여 스토어프론트에서 번들 표시 로직을 구현합니다.
  4. 장바구니 및 결제 섹션을 사용하여 주문을 생성합니다. 예를 들어 빠른 구매의 경우 번들 SKU를 전달하여 지정한 아이템으로 주문 생성 API 호출을 사용할 수 있습니다. 응답에는 결제 UI를 여는 데 필요한 토큰이 포함됩니다.
  5. 주문을 결제하기 위해 결제 UI 열기를 구현합니다.
  6. 웹훅 등을 사용하여 주문 상태 추적을 설정하면 성공적으로 결제된 아이템에 대한 데이터를 신속하게 수신하고 사용자에게 제공할 수 있습니다.

번들 관리 시나리오

관리자

작업

카탈로그

작업

개요

장바구니는 여러 아이템을 하나의 주문으로 결합할 수 있는 구매 매커니즘입니다. 사용자는 실제 통화로 모든 유형의 아이템을 원하는 수량만큼 구매할 수 있으며, 프로모션 코드도 사용할 수 있습니다.

장바구니는 엑솔라 측에 저장됩니다. 세션 간 장바구니 저장은 사용자의 인증 여부에 따라 달라집니다.

  • 인증된 사용자의 경우, 같은 사용자를 대신하여 요청이 전송되는 한 장바구니가 특정 사용자와 연결되어 세션 간에 저장됩니다.

  • 미인증 사용자의 경우, 장바구니 저장은 x-unauthorized-id 헤더 전달 여부에 따라 달라집니다. 미인증 사용자의 장바구니를 세션 간에 저장하려면 모든 요청에서 동일한 x-unauthorized-id를 전달합니다. 이 옵션은 게임 키 판매에만 사용할 수 있습니다.

장바구니는 두 가지 방식, 즉 사용자의 JWT를 통해 자동으로 식별하거나 장바구니 ID(cart_id)로 식별할 수 있습니다.

장바구니 관리는 클라이언트 측과 서버 측 모두에서 가능합니다.

서버 측에서는 사용자 세션을 복원할 때와 같이 장바구니에 아이템을 채울 수 있습니다. 클라이언트 측에서 가능한 작업은 다음과 같습니다:

  • 현재 사용자의 장바구니 또는 ID로 장바구니 가져오기
  • 장바구니 채우기
  • 장바구니의 아이템 업데이트
  • 장바구니에서 아이템 삭제

장바구니에서 아이템을 구매하려면 주문 생성을 위한 클라이언트 및 서버 호출을 사용합니다.

장바구니의 유효 기간(TTL)은 기본적으로 72시간입니다. 새 아이템이 추가되는 등 콘텐츠가 변경되면 TTL이 연장됩니다.

결제가 성공적으로 완료되어도 장바구니는 자동으로 비워지지 않습니다. 장바구니를 비우려면 다음 클라이언트 측 API 호출을 사용합니다.

장바구니 사용 시나리오:

  1. 사용자가 아이템을 선택할 스토어 UI를 구현합니다.

  2. 사용자가 스토어에서 아이템을 선택하면 해당 아이템을 장바구니에 추가합니다(예: 아이템으로 장바구니 채우기 호출 사용). 아이템 배열에서 SKU와 필요한 아이템 수량을 전달해야 합니다.

  3. 장바구니 보기 UI를 구현합니다. 사용자가 장바구니로 이동하면 현재 사용자의 장바구니 가져오기 호출을 사용하여 장바구니의 콘텐츠를 표시합니다. 응답은 할인 및 적용된 프로모션을 포함한 아이템의 최종 가격 정보를 반환합니다.

  4. 주문을 결제하기 위해 결제 UI 열기를 구현합니다. 예를 들어 특정 장바구니의 모든 아이템으로 주문 생성 호출을 사용할 수 있습니다. 응답은 결제 UI를 여는 데 필요한 토큰을 반환합니다.

  5. 웹훅 등을 사용하여 주문 상태 추적을 구성하면 성공적으로 결제된 아이템에 대한 데이터를 신속하게 수신하고 사용자에게 제공할 수 있습니다.

참고

인게임 및 온라인에서 아이템을 판매하려면통합 가이드를 참조하세요.

장바구니 및 결제 절차

주문 수명 주기

주문 수명 주기를 이해하면 주문을 추적)하고 아이템 배송과 같은 구매 후 로직을 올바르게 구현하는 데 도움이 됩니다.

주문은 다음 단계들을 거칩니다:

상태설명참고
new주문이 생성되었습니다. 시스템은 결제 확인을 기다리고 있습니다.거래 상태 설명은 페이 스테이션 API 문서에서 확인할 수 있습니다.
paid주문 대금이 결제되었으며(거래 상태가 done로 변경됨), 해당 아이템을 사용자에게 제공할 수 있습니다. 결제가 확인될 때까지 주문은 new 상태로 남아 있습니다.
done아이템이 사용자에게 부여됩니다. -
canceled결제가 환불됩니다. 거래 상태가 refunded로 변경될 때 주문이 이 상태로 이동합니다.
expired한정 아이템, 프로모션 코드 또는 프로모션에 대한 새 주문을 생성하면 해당 아이템이 포함된 기존 미결제 주문은 모두 expired 상태로 변경됩니다. 가장 최근에 주문한 상품에 대해서만 결제가 가능합니다. 사용자가 만료된 주문에 대해 비용 결제를 시도하면 2002 오류가 표시되며 결제가 실패합니다.

주문 수명 주기

참고

사용자가 결제를 완료하는 도중에 주문 상태가 expired로 변경되었으나 결제가 성공적으로 완료된 경우, 주문 상태는 expired에서 paid로 변경됩니다. 이는 결제 시 해당 주문 품목의 구매 한도를 초과하지 않는 경우에만 적용됩니다.

장바구니(클라이언트 측)

이 섹션의 호출을 사용하여 클라이언트 측에서 장바구니를 관리합니다.

작업

장바구니(서버 측)

이 섹션의 호출을 사용하여 서버 측에서 장바구니를 관리합니다.

작업

결제(클라이언트 측)

이 섹션의 호출을 사용하여 클라이언트 측에서 결제 토큰을 생성합니다.

작업

결제(서버 측)

이 섹션의 호출을 사용하여 서버 측에서 결제 토큰을 생성합니다.

작업

주문

이 섹션의 호출을 사용하여 주문에 대한 정보를 얻습니다.

작업

무료 아이템

이 섹션의 호출을 사용하여 사용자에게 무료 아이템을 제공하세요.

작업

개요

구매 한도를 통해 단일 사용자 또는 모든 사용자가 구매할 수 있는 아이템 수량을 제한할 수 있습니다. 또한 예약된 한도 재설정을 구성할 수 있습니다.

한도는 엑솔라 측에 저장되며 관리자 페이지 또는 다음 API 호출의 limits 객체를 통해 개별 아이템 수준에서 구성됩니다:

한도 정보는 아이템 카탈로그를 가져오는 다음 API 호출의 items.limits 객체에 반환됩니다:

한도 그룹의 관리 하위 섹션에 있는 API 호출은 현재 한도의 상태를 검색하고 특정 사용자에 대해 업데이트할 수 있도록 합니다. 예를 들어, 퀘스트 완료 후 카운터를 재설정하거나 남은 수량을 수동으로 조정할 수 있습니다.

참고

카탈로그에서 한도를 구성하는 방법에 대한 자세한 정보는 아이템 구매 한도 섹션을 참조하세요.

관리

작업

관리자

작업

선주문

작업

판매자

작업

카탈로그

이 API를 사용하면 모든 종류의 판매할 수 있는 아이템 또는 특정 아이템을 가져올 수 있습니다.

작업

판매할 수 있는 아이템 목록 가져오기Client-side

요청

카탈로그 작성을 위해 판매할 수 있는 아이템 목록을 가져옵니다.

주의

모든 프로젝트에는 응답에서 가져올 수 있는 항목 수에 제한이 있습니다. 기본 및 최대 값은 응답당 50개 항목입니다. 페이지별로 더 많은 데이터를 얻으려면 limit 및 offset 입력란을 사용하세요.

참고

이 API 호출은 인증 없이 사용될 때 일반적인 아이템 카탈로그 데이터를 반환합니다. 인증을 사용하여 아이템과 관련된 제한 및 프로모션과 같은 개인화된 사용자 데이터를 검색하세요. 이를 위해 Authorization 헤더에 사용자 JWT를 전달하십시오. 사용자 JWT에 대한 자세한 내용은 이 호출의 보안 블록을 참조하십시오.
보안
XsollaLoginUserJWT
경로
project_idinteger필수

프로젝트 ID입니다. 이 매개 변수는 관리자 페이지의 프로젝트 이름 옆에서 확인할 수 있습니다.

예제: 59080
쿼리
limitinteger>= 1

페이지 요소 개수 제한입니다.

예제: limit=50
offsetinteger>= 0

목록이 생성된 요소의 개수입니다(개수는 0부터 시작함).

예제: offset=0
localestring

응답 언어. ISO 639-1 표준에 따른 소문자 두 글자 언어 코드(예: en)입니다. name 및 description과 같은 현지화 입력란에서는 다섯 글자 로케일 코드(예: en-US)를 사용할 수 있지만, 응답에서는 두 글자 코드로 정규화됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

기본값 "en"
additional_fields[]Array of strings

응답에 포함할 추가 필드입니다. 기본적으로 이러한 필드는 반환되지 않습니다. 포함하려면 필수 값을 전달해야 합니다.

항목 열거형"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

ISO 3166-1 alpha-2에 따른 2자리 대문자 국가 코드입니다. 엑솔라에서 지원하는 국가 및 국가 판별 프로세스에 대한 자세한 정보는 설명서를 확인하십시오.

예제: country=US
promo_codestring[ 1 .. 128 ] characters

고유한 대/소문자 구분 코드입니다. 문자와 숫자를 포함합니다.

예제: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

사용자가 사용할 수 없는 사용기간 제한 아이템을 표시합니다. 해당 아이템의 사용기간이 아직 시작되지 않았거나 이미 만료되었습니다.

기본값 0
예제: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/59080/items?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

응답

판매할 수 있는 아이템 목록을 성공적으로 수신했습니다.

본문application/json
has_moreboolean

페이지가 더 있다는 표시로 사용됩니다.

itemsArray of objects
예제: [{"item_id":259765,"sku":"com.xsolla.gold_1","type":"virtual_currency","name":"Gold","description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","price":{"amount":"1.00","amount_without_discount":"1.00","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"limits":{"per_user":{"total":5,"available":3,"recurrent_schedule":{"interval_type":"weekly","reset_next_date":1746057600},"limit_exceeded_visibility":"show"}},"vp_rewards":[{"item_id":175232,"sku":"com.xsolla.value_point_1","amount":130,"name":"Value point","image_url":"https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg"},{"item_id":186321,"sku":"com.xsolla.clan_value_point_1","amount":50,"name":"Clan Reward VP 1","image_url":"https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg","is_clan":true}]},{"item_id":259766,"sku":"com.xsolla.silver_1","type":"virtual_currency","name":"Silver","description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","price":{"amount":"0.50","amount_without_discount":"0.50","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"limits":null,"vp_rewards":[]},{"item_id":259767,"sku":"com.xsolla.bronze_1","type":"virtual_currency","name":"Bronze","description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","price":{"amount":"0.10","amount_without_discount":"0.10","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"limits":null,"vp_rewards":[]},{"item_id":259768,"sku":"com.xsolla.gold_chest_1","type":"bundle","name":"Chest of gold","bundle_type":"virtual_currency_package","description":"Chest of gold","image_url":"https://cdn3.xsolla.com/img/misc/images/61b8d0785093017ce1f50ebed55c42a9.png","price":{"amount":"7.99","amount_without_discount":"7.99","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"content":[{"item_id":259765,"sku":"com.xsolla.gold_1","type":"virtual_currency","name":"Gold","description":null,"image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","quantity":10}],"limits":null,"vp_rewards":[]},{"item_id":259769,"sku":"com.xsolla.silver_chest_1","type":"bundle","name":"Chest of silver","bundle_type":"virtual_currency_package","description":"Chest of silver","image_url":"https://cdn3.xsolla.com/img/misc/images/f0b59a3370404e8881107249051b70bd.png","price":{"amount":"19.99","amount_without_discount":"19.99","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"content":[{"item_id":259766,"sku":"com.xsolla.silver_1","type":"virtual_currency","name":"Silver","description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","quantity":50}],"limits":null,"vp_rewards":[]},{"item_id":259770,"sku":"com.xsolla.bronze_chest_1","type":"bundle","name":"Chest of bronze","bundle_type":"virtual_currency_package","description":"Chest of bronze","image_url":"https://cdn3.xsolla.com/img/misc/images/b32eb5b1f4f0c202ea6ac4e21c2eae18.png","price":{"amount":"5.99","amount_without_discount":"5.99","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"content":[{"item_id":259767,"sku":"com.xsolla.bronze_2","type":"virtual_currency","name":"Bronze","description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","quantity":100}],"limits":null,"vp_rewards":[]},{"item_id":259771,"sku":"com.xsolla.sword_1","type":"virtual_good","name":"Sword","description":"Sword","image_url":"https://cdn3.xsolla.com/img/misc/images/a558727a420cad609556e4449b9ecb12.png","price":{"amount":"1.99","amount_without_discount":"1.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_2","name":"Gold","type":"virtual_currency","amount":2,"amount_without_discount":2,"calculated_price":{"amount":"2.00","amount_without_discount":"2.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_2","name":"Silver","type":"virtual_currency","amount":5,"amount_without_discount":5,"calculated_price":{"amount":"5.00","amount_without_discount":"5.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_2","name":"Bronze","type":"virtual_currency","amount":50,"amount_without_discount":50,"calculated_price":{"amount":"50.00","amount_without_discount":"50.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"swords","name":"Swords"}],"virtual_item_type":"non_consumable","limits":null,"vp_rewards":[]},{"item_id":259772,"sku":"com.xsolla.saber_1","type":"virtual_good","name":"Saber","description":"Saber","image_url":"https://cdn3.xsolla.com/img/misc/images/edd914d60301d77b94926478d253fcb6.png","price":{"amount":"3.99","amount_without_discount":"3.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_3","name":"Gold","type":"virtual_currency","amount":3,"amount_without_discount":3,"calculated_price":{"amount":"3.00","amount_without_discount":"3.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_3","name":"Silver","type":"virtual_currency","amount":7,"amount_without_discount":7,"calculated_price":{"amount":"7.00","amount_without_discount":"7.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_3","name":"Bronze","type":"virtual_currency","amount":70,"amount_without_discount":70,"calculated_price":{"amount":"70.00","amount_without_discount":"70.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"swords","name":"Swords"}],"virtual_item_type":"non_consumable","limits":null,"vp_rewards":[]},{"item_id":259773,"sku":"com.xsolla.bow_1","type":"virtual_good","name":"Bow","description":"Bow","image_url":"https://cdn3.xsolla.com/img/misc/images/3bb3b0a5254ad15134c891108898363f.png","price":{"amount":"4.99","amount_without_discount":"4.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_4","name":"Gold","type":"virtual_currency","amount":5,"amount_without_discount":5,"calculated_price":{"amount":"5.00","amount_without_discount":"5.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_4","name":"Silver","type":"virtual_currency","amount":10,"amount_without_discount":10,"calculated_price":{"amount":"10.00","amount_without_discount":"10.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_4","name":"Bronze","type":"virtual_currency","amount":100,"amount_without_discount":100,"calculated_price":{"amount":"100.00","amount_without_discount":"100.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"bows","name":"Bows"}],"virtual_item_type":"non_consumable","limits":null,"vp_rewards":[]},{"item_id":259774,"sku":"com.xsolla.electric_shield_1","type":"virtual_good","name":"Electric shield","description":"Electric shield","image_url":"https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png","price":{"amount":"9.99","amount_without_discount":"9.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_5","name":"Gold","type":"virtual_currency","amount":10,"amount_without_discount":10,"calculated_price":{"amount":"10.00","amount_without_discount":"10.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_5","name":"Silver","type":"virtual_currency","amount":20,"amount_without_discount":20,"calculated_price":{"amount":"20.00","amount_without_discount":"20.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_5","name":"Bronze","type":"virtual_currency","amount":200,"amount_without_discount":200,"calculated_price":{"amount":"200.00","amount_without_discount":"200.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"armour","name":"Armour"}],"virtual_item_type":"non_consumable","vp_rewards":[]},{"item_id":259775,"sku":"com.xsolla.royal_shield_1","type":"virtual_good","name":"Royal shield","description":"Royal shield","image_url":"https://cdn3.xsolla.com/img/misc/images/ed417975312a52efeeab8b039ff25cb1.png","price":{"amount":"19.99","amount_without_discount":"19.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_6","name":"Gold","type":"virtual_currency","amount":20,"amount_without_discount":20,"calculated_price":{"amount":"20.00","amount_without_discount":"20.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_6","name":"Silver","type":"virtual_currency","amount":40,"amount_without_discount":40,"calculated_price":{"amount":"40.00","amount_without_discount":"40.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_6","name":"Bronze","type":"virtual_currency","amount":400,"amount_without_discount":400,"calculated_price":{"amount":"400.00","amount_without_discount":"400.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"armour","name":"Armour"}],"virtual_item_type":"non_consumable","vp_rewards":[]},{"item_id":259776,"sku":"com.xsolla.ancient_helmet_1","type":"virtual_good","name":"Ancient helmet","description":"Ancient helmet","image_url":"https://cdn3.xsolla.com/img/misc/images/e70e16d9626f435e519fc8e1cc1e7176.png","price":{"amount":"1.99","amount_without_discount":"1.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_7","name":"Gold","type":"virtual_currency","amount":2,"amount_without_discount":2,"calculated_price":{"amount":"2.00","amount_without_discount":"2.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_7","name":"Silver","type":"virtual_currency","amount":4,"amount_without_discount":4,"calculated_price":{"amount":"4.00","amount_without_discount":"4.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_7","name":"Bronze","type":"virtual_currency","amount":40,"amount_without_discount":40,"calculated_price":{"amount":"40.00","amount_without_discount":"40.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"armour","name":"Armour"}],"virtual_item_type":"non_consumable","vp_rewards":[]},{"item_id":259777,"sku":"com.xsolla.wooden_helmet_1","type":"virtual_good","name":"Wooden helmet","description":"Wooden helmet","image_url":"https://cdn3.xsolla.com/img/misc/images/40d2812e52ad9d988ac20fc842fc66f0.png","price":{"amount":"0.99","amount_without_discount":"0.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_8","name":"Gold","type":"virtual_currency","amount":1,"amount_without_discount":1,"calculated_price":{"amount":"1.00","amount_without_discount":"1.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_8","name":"Silver","type":"virtual_currency","amount":2,"amount_without_discount":2,"calculated_price":{"amount":"2.00","amount_without_discount":"2.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_8","name":"Bronze","type":"virtual_currency","amount":20,"amount_without_discount":20,"calculated_price":{"amount":"20.00","amount_without_discount":"20.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"armour","name":"Armour"}],"virtual_item_type":"non_consumable","vp_rewards":[]},{"item_id":259778,"sku":"com.xsolla.armor_chest_1","type":"bundle","name":"Chest of armor","bundle_type":"standard","description":"Chest of armour","image_url":"https://cdn3.xsolla.com/img/misc/images/5212202f9b8c9dbd254652d6cbeba03e.png","price":{"amount":"19.99","amount_without_discount":"19.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_9","name":"Gold","type":"virtual_currency","amount":20,"amount_without_discount":20,"calculated_price":{"amount":"20.00","amount_without_discount":"20.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_9","name":"Silver","type":"virtual_currency","amount":40,"amount_without_discount":40,"calculated_price":{"amount":"40.00","amount_without_discount":"40.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_9","name":"Bronze","type":"virtual_currency","amount":400,"amount_without_discount":400,"calculated_price":{"amount":"400.00","amount_without_discount":"400.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"total_content_price":{"amount":"11.98","amount_without_discount":"11.98","currency":"USD"},"content":[{"item_id":259774,"sku":"com.xsolla.electric_shield_2","type":"virtual_good","name":"Electric shield","description":"Electric shield","image_url":"https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png","price":{"amount":"9.99","amount_without_discount":"9.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_10","name":"Gold","type":"virtual_currency","amount":10,"amount_without_discount":10,"calculated_price":{"amount":"10.00","amount_without_discount":"10.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_10","name":"Silver","type":"virtual_currency","amount":20,"amount_without_discount":20,"calculated_price":{"amount":"20.00","amount_without_discount":"20.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_10","name":"Bronze","type":"virtual_currency","amount":200,"amount_without_discount":200,"calculated_price":{"amount":"200.00","amount_without_discount":"200.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"armour","name":"Armour"}],"virtual_item_type":"non_consumable","quantity":1},{"item_id":259776,"sku":"com.xsolla.ancient_helmet_2","type":"virtual_good","name":"Ancient helmet","description":"Ancient helmet","image_url":"https://cdn3.xsolla.com/img/misc/images/e70e16d9626f435e519fc8e1cc1e7176.png","price":{"amount":"1.99","amount_without_discount":"1.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_11","name":"Gold","type":"virtual_currency","amount":2,"amount_without_discount":2,"calculated_price":{"amount":"2.00","amount_without_discount":"2.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_11","name":"Silver","type":"virtual_currency","amount":4,"amount_without_discount":4,"calculated_price":{"amount":"4.00","amount_without_discount":"4.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_11","name":"Bronze","type":"virtual_currency","amount":40,"amount_without_discount":40,"calculated_price":{"amount":"40.00","amount_without_discount":"40.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"armour","name":"Armour"}],"virtual_item_type":"non_consumable","quantity":1}],"vp_rewards":[]},{"item_id":259779,"sku":"com.xsolla.treasure_chest_1","type":"bundle","name":"Treasure Chest","bundle_type":"standard","description":"Treasure Chest","image_url":"https://cdn3.xsolla.com/img/misc/images/7b1c0136d91398f9ab17924deee5eeec.png","price":{"amount":"9.99","amount_without_discount":"9.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_12","name":"Gold","type":"virtual_currency","amount":10,"amount_without_discount":10,"calculated_price":{"amount":"10.00","amount_without_discount":"10.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_12","name":"Silver","type":"virtual_currency","amount":20,"amount_without_discount":20,"calculated_price":{"amount":"20.00","amount_without_discount":"20.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_12","name":"Bronze","type":"virtual_currency","amount":40,"amount_without_discount":40,"calculated_price":{"amount":"40.00","amount_without_discount":"40.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"total_content_price":{"amount":"802.89","amount_without_discount":"802.89","currency":"USD"},"content":[{"item_id":259772,"sku":"com.xsolla.saber_2","type":"virtual_good","name":"Saber","description":"Saber","image_url":"https://cdn3.xsolla.com/img/misc/images/edd914d60301d77b94926478d253fcb6.png","price":{"amount":"3.99","amount_without_discount":"3.99","currency":"USD"},"virtual_prices":[{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/e2e9ce8b00eb0190c161c4258b899101.png","item_id":259765,"sku":"com.xsolla.gold_13","name":"Gold","type":"virtual_currency","amount":3,"amount_without_discount":3,"calculated_price":{"amount":"3.00","amount_without_discount":"3.00"},"is_default":true},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","item_id":259766,"sku":"com.xsolla.silver_13","name":"Silver","type":"virtual_currency","amount":7,"amount_without_discount":7,"calculated_price":{"amount":"7.00","amount_without_discount":"7.00"},"is_default":false},{"description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","item_id":259767,"sku":"com.xsolla.bronze_13","name":"Bronze","type":"virtual_currency","amount":70,"amount_without_discount":70,"calculated_price":{"amount":"70.00","amount_without_discount":"70.00"},"is_default":false}],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[{"external_id":"swords","name":"Swords"}],"virtual_item_type":"non_consumable","quantity":1},{"item_id":259769,"sku":"com.xsolla.silver_chest_2","type":"bundle","name":"Chest of silver","bundle_type":"virtual_currency_package","description":"Chest of silver","image_url":"https://cdn3.xsolla.com/img/misc/images/f0b59a3370404e8881107249051b70bd.png","price":{"amount":"19.99","amount_without_discount":"19.99","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"content":[{"item_id":259766,"sku":"com.xsolla.silver_14","type":"virtual_currency","name":"Silver","description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/015e4f4ea4deb1e2c92d5c21a4d58309.png","quantity":50}],"quantity":10},{"item_id":259770,"sku":"com.xsolla.bronze_chest_2","type":"bundle","name":"Chest of bronze","bundle_type":"virtual_currency_package","description":"Chest of bronze","image_url":"https://cdn3.xsolla.com/img/misc/images/b32eb5b1f4f0c202ea6ac4e21c2eae18.png","price":{"amount":"5.99","amount_without_discount":"5.99","currency":"USD"},"virtual_prices":[],"can_be_bought":true,"attributes":[],"is_free":false,"groups":[],"content":[{"item_id":259767,"sku":"com.xsolla.bronze_11","type":"virtual_currency","name":"Bronze","description":"","image_url":"https://cdn3.xsolla.com/img/misc/images/b0beedd5763b612bd3a5631e6cb1d1ff.png","quantity":100}],"quantity":100}],"vp_rewards":[]}]
items[].​item_idinteger

아이템 생성 시 제공되는 내부의 고유 아이템 ID입니다.

예제: 259774
items[].​skustring

고유 아이템 ID입니다. SKU는 소문자 및 대문자 라틴 영숫자, 마침표, 대시 및 밑줄만 포함할 수 있습니다.

예제: "com.xsolla.electric_shield_1"
items[].​namestring

아이템 이름입니다.

예제: "Electric shield"
items[].​groupsArray of objects

아이템이 속한 그룹입니다.

items[].​groups[].​external_idstring

External item group ID specified during creation.

예제: "exclusive"
items[].​groups[].​namestring

그룹의 이름입니다.

예제: "Exclusive"
items[].​groups[].​item_order_in_groupinteger

아이템의 표시 순서를 결정하는 그룹 내 아이템 위치입니다. additional_fields[] 쿼리 매개 변수를 통해 요청된 경우에만 반환됩니다.

예제: 1
items[].​total_content_priceobject or null

번들 콘텐츠 가격의 합계입니다.

items[].​total_content_price.​amountstring

할인이 적용된 번들 콘텐츠 가격의 합계입니다.

예제: "100.99"
items[].​total_content_price.​amount_without_discountstring

번들 콘텐츠 가격의 합계입니다.

예제: "100.99"
items[].​total_content_price.​currencystring

아이템 가격 통화입니다. ISO 4217에 따른 3자리 코드입니다.

items[].​attributesArray of objects

아이템에 해당하는 특성 및 해당 값의 목록입니다. 카탈로그 필터링에 사용할 수 있습니다.

items[].​attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

고유 특성 ID입니다. external_id는 소문자 및 대문자 라틴 영숫자, 대시 및 밑줄만 포함할 수 있습니다.

items[].​attributes[].​nameobject

특성의 이름입니다.

예제: "Genre"
items[].​attributes[].​name.​property name*string or null추가 속성
items[].​attributes[].​valuesArray of objects
items[].​attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$

특성의 고유한 값 ID입니다. external_id에는 소문자 라틴어 영숫자, 대시, 밑줄만 사용할 수 있습니다.

items[].​attributes[].​values[].​valuestring

특성의 값입니다.

예제: "Strategy"
items[].​typestring

아이템 유형: virtual_good/virtual_currency/bundle/game_key/physical_good.

열거형"virtual_good""virtual_currency""bundle""game_key""physical_good"
예제: "virtual_good"
items[].​bundle_typestring

번들 유형입니다. 아이템 유형이 번들인 경우 반환됩니다.

열거형"standard""virtual_currency_package"
items[].​descriptionstring

아이템 설명입니다.

예제: "Electric shield"
items[].​image_urlstring

이미지 URL입니다.

예제: "https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png"
items[].​is_freeboolean

아이템이 무료인지 여부입니다.

items[].​priceobject

아이템 가격입니다.

items[].​price.​amountstring

할인된 아이템 가격입니다.

예제: "9.99"
items[].​price.​amount_without_discountstring

아이템 가격입니다.

예제: "9.99"
items[].​price.​currencystring

아이템 가격 통화입니다. ISO 4217에 따른 3자리 코드입니다.

예제: "USD"
items[].​virtual_pricesArray of objects

가상 가격입니다.

items[].​virtual_prices[].​amountinteger

인게임 재화로 표시된 아이템 가격입니다.

예제: 100
items[].​virtual_prices[].​amount_without_discountinteger

할인 없이 인게임 재화로 표시된 아이템 가격입니다. 인게임 재화 가격에는 할인이 적용되지 않으므로 항상 amount와 같습니다.

예제: 200
items[].​virtual_prices[].​calculated_priceobject
items[].​virtual_prices[].​calculated_price.​amountstring
items[].​virtual_prices[].​calculated_price.​amount_without_discountstring
items[].​virtual_prices[].​skustring

인게임 재화 SKU입니다.

예제: "vc_gold"
items[].​virtual_prices[].​is_defaultboolean

인게임 재화의 기본 가격인지 여부입니다.

예제: true
items[].​virtual_prices[].​image_urlstring or null

인게임 재화의 이미지 URL입니다.

예제: "http://image.png"
items[].​virtual_prices[].​item_idinteger

엑솔라가 할당한 고유 아이템 ID입니다.

예제: 259774
items[].​virtual_prices[].​namestring

인게임 재화의 이름입니다.

예제: "Gold"
items[].​virtual_prices[].​typestring

아이템 유형. 인게임 재화의 경우 `virtual_currency입니다.

예제: "virtual_currency"
items[].​virtual_prices[].​descriptionstring or null

Virtual currency description.

예제: "In-game currency used to purchase weapons and upgrades"
items[].​can_be_boughtboolean

true일 경우 사용자는 아이템을 구매할 수 있습니다.

예제: true
items[].​promotionsArray of objects

장바구니의 특정 아이템에 적용된 프로모션. 다음의 경우 배열이 반환됩니다.

  • 특정 아이템에 대한 할인 프로모션이 구성된 경우

  • 선택한 아이템 할인 설정이 있는 프로모션 코드가 적용된 경우

적용된 아이템 수준 프로모션이 없는 경우 빈 배열이 반환됩니다.

items[].​promotions[].​namestring
items[].​promotions[].​date_startstring or null(date-time)
items[].​promotions[].​date_endstring or null(date-time)
items[].​promotions[].​discountobject or null
items[].​promotions[].​discount.​percentstring or null
items[].​promotions[].​discount.​valuestring or null
items[].​promotions[].​bonusArray of objects
items[].​promotions[].​bonus[].​skustring
items[].​promotions[].​bonus[].​quantityinteger
items[].​promotions[].​bonus[].​typestring

보너스 아이템 유형입니다.

열거형"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
items[].​promotions[].​bonus[].​namestring

보너스 아이템 이름입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

items[].​promotions[].​bonus[].​image_urlstring

보너스 아이템 이미지 URL입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

items[].​promotions[].​bonus[].​bundle_typestring

보너스 번들 아이템 유형입니다. bundle 보너스 아이템 유형에서만 사용할 수 있습니다.

열거형"standard""virtual_currency_package"
items[].​promotions[].​limitsobject
items[].​promotions[].​limits.​per_userobject
items[].​promotions[].​limits.​per_user.​availableinteger
items[].​promotions[].​limits.​per_user.​totalinteger
items[].​virtual_item_typestring

가상 아이템의 유형입니다.

사용 가능한 값: - consumable - 사용 후 인벤토리에서 사라지는 아이템(예: 탄약). - non_consumable - 인벤토리에 무기한으로 남아 있는 아이템. - non_renewing_subscription - 일정 기간 동안 서비스나 콘텐츠에 대한 이용 권한을 나타낼 수 있는 기간 한정 아이템.

열거형"consumable""non_consumable""non_renewing_subscription"
예제: "non-consumable"
items[].​limitsobject or null

아이템 제한 사항입니다.

items[].​limits.​per_userobject or null

사용자 한 명에 대한 아이템 제한 사항입니다.

items[].​limits.​per_user.​totalinteger

사용자 한 명이 구매할 수 있는 최대 아이템 수량입니다.

예제: 5
items[].​limits.​per_user.​availableinteger

현재 사용자가 구매할 수 있는 남은 아이템 수량.

예제: 3
items[].​limits.​per_user.​recurrent_schedule(object or null)
One of:

아이템이 사용자의 반복 새로고침 기간을 제한합니다.

object or null
items[].​limits.​per_user.​limit_exceeded_visibilitystring

구매 한도에 도달한 후 다음 한도 재설정 때까지 카탈로그 내 아이템의 표시 여부를 결정합니다.

recurrent_schedule 배열에서 반복 한도 재설정이 구성된 아이템에 적용됩니다.

구매 한도에 도달한 후, 한도 초기화를 구성하지 않았다면limit_exceeded_visibility 값과 관계없이 해당 아이템은 카탈로그에 표시되지 않습니다.

사용 가능한 값: - show - 구매 한도에 도달한 이후에도 카탈로그 검색 API 호출 시 해당 아이템이 반환됩니다. 클라이언트 측 카탈로그 검색 API 호출에서 한도에 도달하면, 해당 아이템은 can_be_bought: false 플래그와 함께 반환됩니다. 다음 재설정 날짜는 reset_next_date에 반환됩니다. - hide - 구매 한도에 도달한 후, 한도가 재설정될 때까지 해당 아이템은 카탈로그 검색 API 호출에서 반환되지 않습니다.

열거형"show""hide"
items[].​limits.​per_itemobject or null

한 개 아이템에 대한 아이템 제한 사항입니다.

items[].​limits.​per_item.​totalinteger

모든 사용자가 구매할 수 있는 최대 아이템 수량.

예제: 5
items[].​limits.​per_item.​availableinteger

모든 사용자가 구매할 수 있는 남은 아이템 수량.

예제: 3
items[].​custom_attributesobject(json)

아이템 특성 및 값이 포함된 JSON 개체입니다.

items[].​vp_rewardsArray of objects

아이템의 가치 포인트 리워드 목록입니다.

items[].​vp_rewards[].​item_idinteger

내부 고유 아이템 ID입니다.

items[].​vp_rewards[].​skustring

고유 가치 포인트 ID입니다.

items[].​vp_rewards[].​amountinteger

가치 포인트의 금액입니다.

items[].​vp_rewards[].​namestring

가치 포인트 이름입니다.

items[].​vp_rewards[].​image_urlstring

이미지 URL입니다.

items[].​vp_rewards[].​is_clanboolean

값 포인트가 클랜 보상 체인에서 사용되는지 여부입니다.

items[].​contentArray of objects
응답
application/json
{
  "has_more": false,
  "items": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}

ID를 사용하여 판매 가능한 아이템 가져오기Client-side

요청

ID로 판매 가능한 아이템을 가져옵니다.

참고

이 API 호출은 인증 없이 사용될 때 일반적인 아이템 카탈로그 데이터를 반환합니다. 인증을 사용하여 아이템과 관련된 제한 및 프로모션과 같은 개인화된 사용자 데이터를 검색하세요. 이를 위해 Authorization 헤더에 사용자 JWT를 전달하십시오. 사용자 JWT에 대한 자세한 내용은 이 호출의 보안 블록을 참조하십시오.
보안
XsollaLoginUserJWT
경로
project_idinteger필수

프로젝트 ID입니다. 이 매개 변수는 관리자 페이지의 프로젝트 이름 옆에서 확인할 수 있습니다.

예제: 59080
item_idstring필수

아이템 ID입니다.

예제: 259774
쿼리
promo_codestring[ 1 .. 128 ] characters

고유한 대/소문자 구분 코드입니다. 문자와 숫자를 포함합니다.

예제: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

사용자가 사용할 수 없는 사용기간 제한 아이템을 표시합니다. 해당 아이템의 사용기간이 아직 시작되지 않았거나 이미 만료되었습니다.

기본값 0
예제: show_inactive_time_limited_items=1
additional_fields[]Array of strings

응답에 포함할 추가 필드입니다. 기본적으로 이러한 필드는 반환되지 않습니다. 포함하려면 필수 값을 전달해야 합니다.

항목 열거형"media_list""order""long_description""custom_attributes""item_order_in_group"
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/59080/items/id/259774?promo_code=WINTER2021&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

응답

판매할 수 있는 아이템을 성공적으로 수신했습니다.

본문application/json
item_idinteger

아이템 생성 시 제공되는 내부의 고유 아이템 ID입니다.

예제: 259774
skustring

고유 아이템 ID입니다. SKU는 소문자 및 대문자 라틴 영숫자, 마침표, 대시 및 밑줄만 포함할 수 있습니다.

예제: "electric_shield"
namestring

아이템 이름입니다.

예제: "Electric shield"
groupsArray of objects

아이템이 속한 그룹입니다.

groups[].​external_idstring

External item group ID specified during creation.

예제: "exclusive"
groups[].​namestring

그룹의 이름입니다.

예제: "Exclusive"
groups[].​item_order_in_groupinteger

아이템의 표시 순서를 결정하는 그룹 내 아이템 위치입니다. additional_fields[] 쿼리 매개 변수를 통해 요청된 경우에만 반환됩니다.

예제: 1
attributesArray of objects

아이템에 해당하는 특성 및 해당 값의 목록입니다. 카탈로그 필터링에 사용할 수 있습니다.

attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

고유 특성 ID입니다. external_id는 소문자 및 대문자 라틴 영숫자, 대시 및 밑줄만 포함할 수 있습니다.

attributes[].​nameobject

특성의 이름입니다.

예제: "Genre"
attributes[].​name.​property name*string or null추가 속성
attributes[].​valuesArray of objects
attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$

특성의 고유한 값 ID입니다. external_id에는 소문자 라틴어 영숫자, 대시, 밑줄만 사용할 수 있습니다.

attributes[].​values[].​valuestring

특성의 값입니다.

예제: "Strategy"
typestring

아이템 유형: virtual_good/virtual_currency/bundle/game_key/physical_good.

열거형"virtual_good""virtual_currency""bundle""game_key""physical_good"
예제: "virtual_good"
descriptionstring

아이템 설명입니다.

예제: "Electric shield"
image_urlstring

이미지 URL입니다.

예제: "https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png"
is_freeboolean

아이템이 무료인지 여부입니다.

priceobject

아이템 가격입니다.

price.​amountstring

할인된 아이템 가격입니다.

예제: "9.99"
price.​amount_without_discountstring

아이템 가격입니다.

예제: "9.99"
price.​currencystring

아이템 가격 통화입니다. ISO 4217에 따른 3자리 코드입니다.

예제: "USD"
virtual_pricesArray of objects

가상 가격입니다.

virtual_prices[].​amountinteger

인게임 재화로 표시된 아이템 가격입니다.

예제: 100
virtual_prices[].​amount_without_discountinteger

할인 없이 인게임 재화로 표시된 아이템 가격입니다. 인게임 재화 가격에는 할인이 적용되지 않으므로 항상 amount와 같습니다.

예제: 200
virtual_prices[].​calculated_priceobject
virtual_prices[].​calculated_price.​amountstring
virtual_prices[].​calculated_price.​amount_without_discountstring
virtual_prices[].​skustring

인게임 재화 SKU입니다.

예제: "vc_gold"
virtual_prices[].​is_defaultboolean

인게임 재화의 기본 가격인지 여부입니다.

예제: true
virtual_prices[].​image_urlstring or null

인게임 재화의 이미지 URL입니다.

예제: "http://image.png"
virtual_prices[].​item_idinteger

엑솔라가 할당한 고유 아이템 ID입니다.

예제: 259774
virtual_prices[].​namestring

인게임 재화의 이름입니다.

예제: "Gold"
virtual_prices[].​typestring

아이템 유형. 인게임 재화의 경우 `virtual_currency입니다.

예제: "virtual_currency"
virtual_prices[].​descriptionstring or null

Virtual currency description.

예제: "In-game currency used to purchase weapons and upgrades"
can_be_boughtboolean

true일 경우 사용자는 아이템을 구매할 수 있습니다.

예제: true
promotionsArray of objects

장바구니의 특정 아이템에 적용된 프로모션. 다음의 경우 배열이 반환됩니다.

  • 특정 아이템에 대한 할인 프로모션이 구성된 경우

  • 선택한 아이템 할인 설정이 있는 프로모션 코드가 적용된 경우

적용된 아이템 수준 프로모션이 없는 경우 빈 배열이 반환됩니다.

promotions[].​namestring
promotions[].​date_startstring or null(date-time)
promotions[].​date_endstring or null(date-time)
promotions[].​discountobject or null
promotions[].​discount.​percentstring or null
promotions[].​discount.​valuestring or null
promotions[].​bonusArray of objects
promotions[].​bonus[].​skustring
promotions[].​bonus[].​quantityinteger
promotions[].​bonus[].​typestring

보너스 아이템 유형입니다.

열거형"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
promotions[].​bonus[].​namestring

보너스 아이템 이름입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

promotions[].​bonus[].​image_urlstring

보너스 아이템 이미지 URL입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

promotions[].​bonus[].​bundle_typestring

보너스 번들 아이템 유형입니다. bundle 보너스 아이템 유형에서만 사용할 수 있습니다.

열거형"standard""virtual_currency_package"
promotions[].​limitsobject
promotions[].​limits.​per_userobject
promotions[].​limits.​per_user.​availableinteger
promotions[].​limits.​per_user.​totalinteger
virtual_item_typestring

가상 아이템의 유형입니다.

사용 가능한 값: - consumable - 사용 후 인벤토리에서 사라지는 아이템(예: 탄약). - non_consumable - 인벤토리에 무기한으로 남아 있는 아이템. - non_renewing_subscription - 일정 기간 동안 서비스나 콘텐츠에 대한 이용 권한을 나타낼 수 있는 기간 한정 아이템.

열거형"consumable""non_consumable""non_renewing_subscription"
예제: "non-consumable"
limitsobject or null

아이템 제한 사항입니다.

limits.​per_userobject or null

사용자 한 명에 대한 아이템 제한 사항입니다.

limits.​per_user.​totalinteger

사용자 한 명이 구매할 수 있는 최대 아이템 수량입니다.

예제: 5
limits.​per_user.​availableinteger

현재 사용자가 구매할 수 있는 남은 아이템 수량.

예제: 3
limits.​per_user.​recurrent_schedule(object or null)
One of:

아이템이 사용자의 반복 새로고침 기간을 제한합니다.

object or null
limits.​per_user.​limit_exceeded_visibilitystring

구매 한도에 도달한 후 다음 한도 재설정 때까지 카탈로그 내 아이템의 표시 여부를 결정합니다.

recurrent_schedule 배열에서 반복 한도 재설정이 구성된 아이템에 적용됩니다.

구매 한도에 도달한 후, 한도 초기화를 구성하지 않았다면limit_exceeded_visibility 값과 관계없이 해당 아이템은 카탈로그에 표시되지 않습니다.

사용 가능한 값: - show - 구매 한도에 도달한 이후에도 카탈로그 검색 API 호출 시 해당 아이템이 반환됩니다. 클라이언트 측 카탈로그 검색 API 호출에서 한도에 도달하면, 해당 아이템은 can_be_bought: false 플래그와 함께 반환됩니다. 다음 재설정 날짜는 reset_next_date에 반환됩니다. - hide - 구매 한도에 도달한 후, 한도가 재설정될 때까지 해당 아이템은 카탈로그 검색 API 호출에서 반환되지 않습니다.

열거형"show""hide"
limits.​per_itemobject or null

한 개 아이템에 대한 아이템 제한 사항입니다.

limits.​per_item.​totalinteger

모든 사용자가 구매할 수 있는 최대 아이템 수량.

예제: 5
limits.​per_item.​availableinteger

모든 사용자가 구매할 수 있는 남은 아이템 수량.

예제: 3
custom_attributesobject(json)

아이템 특성 및 값이 포함된 JSON 개체입니다.

vp_rewardsArray of objects

아이템의 가치 포인트 리워드 목록입니다.

vp_rewards[].​item_idinteger

내부 고유 아이템 ID입니다.

vp_rewards[].​skustring

고유 가치 포인트 ID입니다.

vp_rewards[].​amountinteger

가치 포인트의 금액입니다.

vp_rewards[].​namestring

가치 포인트 이름입니다.

vp_rewards[].​image_urlstring

이미지 URL입니다.

vp_rewards[].​is_clanboolean

값 포인트가 클랜 보상 체인에서 사용되는지 여부입니다.

응답
application/json
{
  "item_id": 259774,
  "sku": "com.xsolla.electric_shield_1",
  "type": "virtual_good",
  "name": "Electric shield",
  "description": "Electric shield",
  "image_url": "https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png",
  "price": {
    "amount": "9.99",
    "amount_without_discount": "9.99",
    "currency": "USD"
  },
  "virtual_prices": [
    { … },
    { … },
    { … }
  ],
  "can_be_bought": true,
  "promotions": [
    { … }
  ],
  "attributes": [],
  "is_free": false,
  "groups": [
    { … }
  ],
  "virtual_item_type": "non_consumable",
  "limits": {
    "per_user": { … }
  },
  "vp_rewards": [
    { … },
    { … }
  ],
  "custom_attributes": {
    "purchased": 0,
    "attr": "value"
  }
}

SKU로 판매할 수 있는 아이템 가져오기Client-side

요청

카탈로그를 작성하기 위해 SKU별로 판매 가능한 항목을 가져옵니다.

참고

이 API 호출은 인증 없이 사용될 때 일반적인 아이템 카탈로그 데이터를 반환합니다. 인증을 사용하여 아이템과 관련된 제한 및 프로모션과 같은 개인화된 사용자 데이터를 검색하세요. 이를 위해 Authorization 헤더에 사용자 JWT를 전달하십시오. 사용자 JWT에 대한 자세한 내용은 이 호출의 보안 블록을 참조하십시오.
보안
XsollaLoginUserJWT
경로
project_idinteger필수

프로젝트 ID입니다. 이 매개 변수는 관리자 페이지의 프로젝트 이름 옆에서 확인할 수 있습니다.

예제: 59080
skustring필수

아이템 SKU입니다.

예제: electric_shield
쿼리
promo_codestring[ 1 .. 128 ] characters

고유한 대/소문자 구분 코드입니다. 문자와 숫자를 포함합니다.

예제: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

사용자가 사용할 수 없는 사용기간 제한 아이템을 표시합니다. 해당 아이템의 사용기간이 아직 시작되지 않았거나 이미 만료되었습니다.

기본값 0
예제: show_inactive_time_limited_items=1
additional_fields[]Array of strings

응답에 포함할 추가 필드입니다. 기본적으로 이러한 필드는 반환되지 않습니다. 포함하려면 필수 값을 전달해야 합니다.

항목 열거형"media_list""order""long_description""custom_attributes""item_order_in_group"
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/59080/items/sku/electric_shield?promo_code=WINTER2021&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

응답

판매할 수 있는 아이템을 성공적으로 수신했습니다.

본문application/json
item_idinteger

아이템 생성 시 제공되는 내부의 고유 아이템 ID입니다.

예제: 259774
skustring

고유 아이템 ID입니다. SKU는 소문자 및 대문자 라틴 영숫자, 마침표, 대시 및 밑줄만 포함할 수 있습니다.

예제: "electric_shield"
namestring

아이템 이름입니다.

예제: "Electric shield"
groupsArray of objects

아이템이 속한 그룹입니다.

groups[].​external_idstring

External item group ID specified during creation.

예제: "exclusive"
groups[].​namestring

그룹의 이름입니다.

예제: "Exclusive"
groups[].​item_order_in_groupinteger

아이템의 표시 순서를 결정하는 그룹 내 아이템 위치입니다. additional_fields[] 쿼리 매개 변수를 통해 요청된 경우에만 반환됩니다.

예제: 1
attributesArray of objects

아이템에 해당하는 특성 및 해당 값의 목록입니다. 카탈로그 필터링에 사용할 수 있습니다.

attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

고유 특성 ID입니다. external_id는 소문자 및 대문자 라틴 영숫자, 대시 및 밑줄만 포함할 수 있습니다.

attributes[].​nameobject

특성의 이름입니다.

예제: "Genre"
attributes[].​name.​property name*string or null추가 속성
attributes[].​valuesArray of objects
attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$

특성의 고유한 값 ID입니다. external_id에는 소문자 라틴어 영숫자, 대시, 밑줄만 사용할 수 있습니다.

attributes[].​values[].​valuestring

특성의 값입니다.

예제: "Strategy"
typestring

아이템 유형: virtual_good/virtual_currency/bundle/game_key/physical_good.

열거형"virtual_good""virtual_currency""bundle""game_key""physical_good"
예제: "virtual_good"
descriptionstring

아이템 설명입니다.

예제: "Electric shield"
image_urlstring

이미지 URL입니다.

예제: "https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png"
is_freeboolean

아이템이 무료인지 여부입니다.

priceobject

아이템 가격입니다.

price.​amountstring

할인된 아이템 가격입니다.

예제: "9.99"
price.​amount_without_discountstring

아이템 가격입니다.

예제: "9.99"
price.​currencystring

아이템 가격 통화입니다. ISO 4217에 따른 3자리 코드입니다.

예제: "USD"
virtual_pricesArray of objects

가상 가격입니다.

virtual_prices[].​amountinteger

인게임 재화로 표시된 아이템 가격입니다.

예제: 100
virtual_prices[].​amount_without_discountinteger

할인 없이 인게임 재화로 표시된 아이템 가격입니다. 인게임 재화 가격에는 할인이 적용되지 않으므로 항상 amount와 같습니다.

예제: 200
virtual_prices[].​calculated_priceobject
virtual_prices[].​calculated_price.​amountstring
virtual_prices[].​calculated_price.​amount_without_discountstring
virtual_prices[].​skustring

인게임 재화 SKU입니다.

예제: "vc_gold"
virtual_prices[].​is_defaultboolean

인게임 재화의 기본 가격인지 여부입니다.

예제: true
virtual_prices[].​image_urlstring or null

인게임 재화의 이미지 URL입니다.

예제: "http://image.png"
virtual_prices[].​item_idinteger

엑솔라가 할당한 고유 아이템 ID입니다.

예제: 259774
virtual_prices[].​namestring

인게임 재화의 이름입니다.

예제: "Gold"
virtual_prices[].​typestring

아이템 유형. 인게임 재화의 경우 `virtual_currency입니다.

예제: "virtual_currency"
virtual_prices[].​descriptionstring or null

Virtual currency description.

예제: "In-game currency used to purchase weapons and upgrades"
can_be_boughtboolean

true일 경우 사용자는 아이템을 구매할 수 있습니다.

예제: true
promotionsArray of objects

장바구니의 특정 아이템에 적용된 프로모션. 다음의 경우 배열이 반환됩니다.

  • 특정 아이템에 대한 할인 프로모션이 구성된 경우

  • 선택한 아이템 할인 설정이 있는 프로모션 코드가 적용된 경우

적용된 아이템 수준 프로모션이 없는 경우 빈 배열이 반환됩니다.

promotions[].​namestring
promotions[].​date_startstring or null(date-time)
promotions[].​date_endstring or null(date-time)
promotions[].​discountobject or null
promotions[].​discount.​percentstring or null
promotions[].​discount.​valuestring or null
promotions[].​bonusArray of objects
promotions[].​bonus[].​skustring
promotions[].​bonus[].​quantityinteger
promotions[].​bonus[].​typestring

보너스 아이템 유형입니다.

열거형"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
promotions[].​bonus[].​namestring

보너스 아이템 이름입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

promotions[].​bonus[].​image_urlstring

보너스 아이템 이미지 URL입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

promotions[].​bonus[].​bundle_typestring

보너스 번들 아이템 유형입니다. bundle 보너스 아이템 유형에서만 사용할 수 있습니다.

열거형"standard""virtual_currency_package"
promotions[].​limitsobject
promotions[].​limits.​per_userobject
promotions[].​limits.​per_user.​availableinteger
promotions[].​limits.​per_user.​totalinteger
virtual_item_typestring

가상 아이템의 유형입니다.

사용 가능한 값: - consumable - 사용 후 인벤토리에서 사라지는 아이템(예: 탄약). - non_consumable - 인벤토리에 무기한으로 남아 있는 아이템. - non_renewing_subscription - 일정 기간 동안 서비스나 콘텐츠에 대한 이용 권한을 나타낼 수 있는 기간 한정 아이템.

열거형"consumable""non_consumable""non_renewing_subscription"
예제: "non-consumable"
limitsobject or null

아이템 제한 사항입니다.

limits.​per_userobject or null

사용자 한 명에 대한 아이템 제한 사항입니다.

limits.​per_user.​totalinteger

사용자 한 명이 구매할 수 있는 최대 아이템 수량입니다.

예제: 5
limits.​per_user.​availableinteger

현재 사용자가 구매할 수 있는 남은 아이템 수량.

예제: 3
limits.​per_user.​recurrent_schedule(object or null)
One of:

아이템이 사용자의 반복 새로고침 기간을 제한합니다.

object or null
limits.​per_user.​limit_exceeded_visibilitystring

구매 한도에 도달한 후 다음 한도 재설정 때까지 카탈로그 내 아이템의 표시 여부를 결정합니다.

recurrent_schedule 배열에서 반복 한도 재설정이 구성된 아이템에 적용됩니다.

구매 한도에 도달한 후, 한도 초기화를 구성하지 않았다면limit_exceeded_visibility 값과 관계없이 해당 아이템은 카탈로그에 표시되지 않습니다.

사용 가능한 값: - show - 구매 한도에 도달한 이후에도 카탈로그 검색 API 호출 시 해당 아이템이 반환됩니다. 클라이언트 측 카탈로그 검색 API 호출에서 한도에 도달하면, 해당 아이템은 can_be_bought: false 플래그와 함께 반환됩니다. 다음 재설정 날짜는 reset_next_date에 반환됩니다. - hide - 구매 한도에 도달한 후, 한도가 재설정될 때까지 해당 아이템은 카탈로그 검색 API 호출에서 반환되지 않습니다.

열거형"show""hide"
limits.​per_itemobject or null

한 개 아이템에 대한 아이템 제한 사항입니다.

limits.​per_item.​totalinteger

모든 사용자가 구매할 수 있는 최대 아이템 수량.

예제: 5
limits.​per_item.​availableinteger

모든 사용자가 구매할 수 있는 남은 아이템 수량.

예제: 3
custom_attributesobject(json)

아이템 특성 및 값이 포함된 JSON 개체입니다.

vp_rewardsArray of objects

아이템의 가치 포인트 리워드 목록입니다.

vp_rewards[].​item_idinteger

내부 고유 아이템 ID입니다.

vp_rewards[].​skustring

고유 가치 포인트 ID입니다.

vp_rewards[].​amountinteger

가치 포인트의 금액입니다.

vp_rewards[].​namestring

가치 포인트 이름입니다.

vp_rewards[].​image_urlstring

이미지 URL입니다.

vp_rewards[].​is_clanboolean

값 포인트가 클랜 보상 체인에서 사용되는지 여부입니다.

응답
application/json
{
  "item_id": 259774,
  "sku": "com.xsolla.electric_shield_1",
  "type": "virtual_good",
  "name": "Electric shield",
  "description": "Electric shield",
  "image_url": "https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png",
  "price": {
    "amount": "9.99",
    "amount_without_discount": "9.99",
    "currency": "USD"
  },
  "virtual_prices": [
    { … },
    { … },
    { … }
  ],
  "can_be_bought": true,
  "promotions": [
    { … }
  ],
  "attributes": [],
  "is_free": false,
  "groups": [
    { … }
  ],
  "virtual_item_type": "non_consumable",
  "limits": {
    "per_user": { … }
  },
  "vp_rewards": [
    { … },
    { … }
  ],
  "custom_attributes": {
    "purchased": 0,
    "attr": "value"
  }
}

공통 지역

작업

관리자

작업

관리자

작업

카탈로그

작업