콘텐츠로 건너뛰기
/
ID로 게임 가져오기(관리자)

Catalog API (2.0.0)

Overview

  • Version: 2.0.0
  • Servers: https://store.xsolla.com/api
  • Contact Us by Email
  • Contact URL: https://xsolla.com/
  • Required TLS version: 1.2

Catalog API는 인게임 스토어 카탈로그를 관리하고 구매를 처리하기 위한 엔드포인트를 제공합니다. 엔드포인트를 사용하여 가상 아이템, 인게임 재화, 게임 키, 번들, 장바구니 및 결제 플로우, 아이템 속성을 구성하고 외부 소스에서 아이템을 가져올 수 있습니다.

OpenAPI 설명 다운로드
index.json
index.yaml
언어
서버
Mock server
https://xsolla.redocly.app/_mock/ko/api/catalog/
https://store.xsolla.com/api/

관리자

작업

카탈로그

작업

가상 결제

작업

카탈로그

작업

권한

작업

관리자

작업

ID로 게임 삭제Server-sideAdmin

요청

ID로 프로젝트의 게임을 삭제합니다.

보안
basicAuth
경로
project_idinteger필수

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

예제: 44056
item_idstring필수

아이템 ID입니다.

예제: 656
curl -i -X DELETE \
  -u <username>:<password> \
  https://xsolla.redocly.app/_mock/ko/api/catalog/v2/project/44056/admin/items/game/id/656

응답

게임을 성공적으로 삭제했습니다.

응답
콘텐츠 없음

ID로 게임 가져오기(관리자)Server-sideAdmin

요청

관리를 위해 게임을 가져옵니다. 게임은 사용자가 구매할 수 있는 게임 키로 구성되어 있습니다.

참고

스토어 카탈로그를 빌드하기 위해 이 엔드포인트를 사용해선 안 됩니다.
보안
basicAuth
경로
project_idinteger필수

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

예제: 44056
item_idstring필수

아이템 ID입니다.

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

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

예제: promo_code=WINTER2021
curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/ko/api/catalog/v2/project/44056/admin/items/game/id/656?promo_code=WINTER2021'

응답

게임을 성공적으로 수신했습니다.

본문application/json
attributesArray of objects(Game-Keys_admin-attributes)

특성 목록입니다.

예제: [{"external_id":"attribute_external_id","name":{"de":"Attributname","en":"Attribute name"},"values":[{"external_id":"value_1","name":{"de":"wert 1","en":"value 1"}},{"external_id":"value_2","name":{"de":"wert 2","en":"value 2"}}]}]
description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

아이템 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 로케일 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

One of:

아이템 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 로케일 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

groupsArray of objects

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

예제: [{"external_id":"horror","name":{"en":"Horror"}}]
image_urlstring

이미지 URL입니다.

예제: "https://image.example.com"
is_enabledboolean
is_freeboolean(value-is_free)

true일 경우 아이템은 무료입니다.

기본값 false
예제: false
is_show_in_storeboolean
item_idinteger

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

예제: 1
long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

아이템의 긴 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 5자 로케일 코드(예 en-US: ) 두 가지 형식 중 하나로 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 변수(예: en 및 en-US)가 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

Any of:

아이템의 긴 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 5자 로케일 코드(예 en-US: ) 두 가지 형식 중 하나로 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 변수(예: en 및 en-US)가 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

media_listArray of objects

스크린샷, 게임 플레이 동영상 등과 같은 게임 추가 자산입니다.

예제: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)

아이템 이름에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 언어 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

One of:

아이템 이름에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 언어 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

orderinteger

목록에서 게임의 주문 우선 순위입니다.

예제: 1
skustring

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

예제: "game_1"
typestring

아이템 유형입니다. 이 경우 항상 unit입니다.

예제: "unit"
unit_itemsArray of objects

다른 DRM용 게임 키입니다.

응답
application/json
{
  "attributes": [
    { … }
  ],
  "description": {
    "en": "Example game 1"
  },
  "groups": [
    { … }
  ],
  "image_url": "https://image.example.com",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": false,
  "item_id": 1,
  "long_description": {
    "en": "Example game's long description"
  },
  "media_list": [
    { … }
  ],
  "name": {
    "en": "Game 1"
  },
  "order": 1,
  "sku": "com.xsolla.game_1",
  "type": "unit",
  "unit_items": [
    { … },
    { … }
  ]
}

ID로 게임 업데이트Server-sideAdmin

요청

프로젝트의 게임을 ID로 업데이트합니다.

보안
basicAuth
경로
project_idinteger필수

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

예제: 44056
item_idstring필수

아이템 ID입니다.

예제: 656
본문application/json필수

게임 데이터가 있는 개체입니다.

attributesArray of objects(Game-Keys_admin-post-put-attributes)<= 20 items

특성 목록입니다.

주의. 아이템에 20개 이상의 특성을 지정할 수 없습니다. 제한을 초과하려고 하면 오류가 발생합니다.
description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

아이템 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 로케일 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

One of:

아이템 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 로케일 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

groupsArray of objects

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

예제: ["new_games"]
image_urlstring

이미지 URL입니다.

예제: "http://image.png"
is_enabledboolean

비활성화된 경우 인벤토리를 통해 아이템을 구매하고 액세스할 수 없습니다.

예제: true
is_show_in_storeboolean

아이템을 구매할 수 있는 상태입니다.

예제: true
long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

아이템의 긴 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 5자 로케일 코드(예 en-US: ) 두 가지 형식 중 하나로 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 변수(예: en 및 en-US)가 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

Any of:

아이템의 긴 설명에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 5자 로케일 코드(예 en-US: ) 두 가지 형식 중 하나로 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 변수(예: en 및 en-US)가 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

media_listArray of objects

스크린샷, 게임 플레이 동영상 등과 같은 게임 추가 자산입니다.

예제: [{"type":"image","url":"http://image.png"},{"type":"video","url":"http://video.png"}]
name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)필수

아이템 이름에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 언어 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

One of:

아이템 이름에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 언어 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

name.​arstring or null

아랍어

name.​bgstring or null

불가리아어

name.​cnstring or null

중국어(간체)

name.​csstring or null

체코어

name.​destring or null

독일어

name.​enstring or null

영어

name.​esstring or null

스페인어(스페인)

name.​frstring or null

프랑스어

name.​hestring or null

히브리어

name.​idstring or null

인도네시아어

name.​itstring or null

이탈리아어

name.​jastring or null

일본어

name.​kmstring or null

크메르어

name.​kostring or null

한국어

name.​lostring or null

라오스어

name.​mystring or null

버마어

name.​nestring or null

네팔어

name.​phstring or null

필리핀어

name.​plstring or null

폴란드어

name.​ptstring or null

포르투칼어

name.​rostring or null

로마니아어

name.​rustring or null

러시아어

name.​thstring or null

태국어

name.​trstring or null

터키어

name.​twstring or null

중국어(번체)

name.​vistring or null

베트남어

orderinteger

목록에서 게임의 주문 우선 순위입니다.

예제: 1
skustring[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$필수

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

예제: "com.xsolla.game_1"
unit_itemsArray of objects필수

다른 DRM용 게임 키입니다.

예제: [{"drm_sku":"steam_key_1","is_enabled":true,"is_free":false,"is_show_in_store":true,"limits":{"per_item":{"available":5000,"reserved":500,"sold":4500,"total":10000},"per_user":{"total":5}},"name":{"en-US":"Game key name","ru-RU":"Название игрового ключа"},"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}],"pre_order":{"description":"Some description","is_enabled":true,"release_date":"2020-08-11T10:00:00+03:00"},"prices":[{"amount":35.5,"currency":"USD","is_default":true,"is_enabled":true}],"regions":[{"id":12},{"id":64}],"sku":"com.xsolla.game_key_1","vc_prices":[{"amount":35.5,"is_default":true,"is_enabled":true,"sku":"com.xsolla.gold_1"}]}]
unit_items[].​attributesArray of objects(Game-Keys_admin-attributes)

특성 목록입니다.

예제: [{"external_id":"attribute_external_id","name":{"de":"Attributname","en":"Attribute name"},"values":[{"external_id":"value_1","name":{"de":"wert 1","en":"value 1"}},{"external_id":"value_2","name":{"de":"wert 2","en":"value 2"}}]}]
unit_items[].​drm_skustring필수

DRM 고유 ID입니다.

예제: "steam"
unit_items[].​groupsArray of objects

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

unit_items[].​is_enabledboolean

비활성화된 경우 인벤토리를 통해 아이템을 구매하고 액세스할 수 없습니다.

unit_items[].​is_freeboolean(value-is_free)

true일 경우 아이템은 무료입니다.

기본값 false
예제: false
unit_items[].​is_show_in_storeboolean

아이템을 구매할 수 있는 상태입니다.

unit_items[].​limitsobject(Game-key-item-limit)

아이템 제한 사항입니다.

unit_items[].​name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)

아이템 이름에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 언어 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

One of:

아이템 이름에 대한 현지화가 있는 개체입니다. 두 글자 소문자 언어 코드(예: en) 또는 다섯 글자 언어 코드(예: en-US) 두 가지 형식 중 하나로 되어 있는 값을 허용합니다. 두 형식 모두 입력으로 허용되지만 응답은 두 글자 소문자 언어 코드를 반환합니다. 동일한 언어에 대한 두 옵션(예: en 및 en-US)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

unit_items[].​orderinteger

목록에서 게임의 주문 우선 순위입니다.

예제: 1
unit_items[].​periodsArray of objects or null(item-periods)

아이템 판매 기간입니다.

unit_items[].​pre_orderobject

사전 판매 설정입니다.

unit_items[].​pricesArray of objects필수

실제 통화 가격입니다.

unit_items[].​prices[].​amountnumber필수
예제: 1299.99
unit_items[].​prices[].​currencystring필수

아이템 가격 통화입니다. ISO 4217에 따른 3자리 코드입니다. 엑솔라에서 지원하는 통화에 대한 자세한 정보는 설명서를 확인하십시오.

예제: "RUB"
unit_items[].​prices[].​is_defaultboolean필수

기본 가격은 사용자 통화로 가격을 지정하지 않은 경우 카탈로그를 작성하는 데 사용됩니다.

unit_items[].​prices[].​is_enabledboolean필수
unit_items[].​regionsArray of objects(Game-Keys_regions)
unit_items[].​skustring[ 1 .. 255 ] characters필수

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

예제: "game_1"
unit_items[].​vc_pricesArray of objects
curl -i -X PUT \
  -u <username>:<password> \
  https://xsolla.redocly.app/_mock/ko/api/catalog/v2/project/44056/admin/items/game/id/656 \
  -H 'Content-Type: application/json' \
  -d '{
    "description": {
      "en-US": "Game description",
      "ru-RU": "Краткое описание игры"
    },
    "groups": [
      "new_games"
    ],
    "image_url": "http://image.png",
    "is_enabled": true,
    "is_show_in_store": true,
    "long_description": {
      "en-US": "Game long description",
      "ru-RU": "Полное описание игры"
    },
    "media_list": [
      {
        "type": "image",
        "url": "http://image.png"
      },
      {
        "type": "video",
        "url": "http://video.png"
      }
    ],
    "name": {
      "en-US": "Game name",
      "ru-RU": "Название игры"
    },
    "sku": "com.xsolla.game_1",
    "unit_items": [
      {
        "drm_sku": "steam_key_1",
        "is_enabled": true,
        "is_free": false,
        "is_show_in_store": true,
        "limits": {
          "per_item": {
            "available": 5000,
            "reserved": 500,
            "sold": 4500,
            "total": 10000
          },
          "per_user": {
            "total": 5
          }
        },
        "name": {
          "en-US": "Game key name",
          "ru-RU": "Название игрового ключа"
        },
        "periods": [
          {
            "date_from": "2020-08-11T10:00:00+03:00",
            "date_until": "2020-08-11T20:00:00+03:00"
          }
        ],
        "pre_order": {
          "description": "Some description",
          "is_enabled": true,
          "release_date": "2020-08-11T10:00:00+03:00"
        },
        "prices": [
          {
            "amount": 35.5,
            "currency": "USD",
            "is_default": true,
            "is_enabled": true
          }
        ],
        "regions": [
          {
            "id": 12
          },
          {
            "id": 64
          }
        ],
        "sku": "com.xsolla.game_key_1",
        "vc_prices": [
          {
            "amount": 35.5,
            "is_default": true,
            "is_enabled": true,
            "sku": "com.xsolla.gold_1"
          }
        ]
      }
    ]
  }'

응답

게임을 성공적으로 업데이트했습니다.

응답
콘텐츠 없음

관리자

작업

카탈로그

작업

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

작업

장바구니(서버 측)

작업

결제(클라이언트 측)

작업

결제(서버 측)

작업

주문

작업

무료 아이템

작업

관리

작업

관리자

작업

웹훅

작업

선주문

작업

판매자

작업

카탈로그

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

작업

공통 지역

작업

관리자

작업