콘텐츠로 건너뛰기
/
번들 가져오기

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/

관리자

작업

카탈로그

작업

가상 결제

작업

카탈로그

작업

권한

작업

관리자

작업

관리자

작업

번들 삭제Server-sideAdmin

요청

번들을 삭제합니다.

보안
basicAuth
경로
project_idinteger필수

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

예제: 44056
skustring필수

번들 SKU입니다.

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

응답

번들을 성공적으로 삭제했습니다.

본문
응답
콘텐츠 없음

번들 가져오기Server-sideAdmin

요청

관리를 위해 프로젝트 내부의 번들을 가져옵니다.

참고

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

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

예제: 44056
skustring필수

번들 SKU입니다.

예제: kg_1
curl -i -X GET \
  -u <username>:<password> \
  https://xsolla.redocly.app/_mock/ko/api/catalog/v2/project/44056/admin/items/bundle/sku/kg_1

응답

지정한 번들을 성공적으로 수신했습니다.

본문application/json
attributesArray of objects(Bundles_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"}}]}]
bundle_typestring(bundle_type)

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

열거형"standard""virtual_currency_package""partner_side_content"
contentArray of objects(Bundles_admin_content_response)
custom_attributesobject(json)(item-custom-attributes-response)

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

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(Bundles_groups_response)

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

기본값 []
예제: [{"external_id":"horror","name":{"en":"Horror"}}]
image_urlstring or null(Bundles_image_url)

이미지 URL입니다.

예제: "https://image.example.com"
is_enabledboolean(Bundles_is_enabled)

비활성화된 경우 아이템을 검색하거나 구매할 수 없습니다.

기본값 true
예제: true
is_freeboolean(value-is_free)

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

기본값 false
예제: false
is_show_in_storeboolean(Bundles_is_show_in_store)

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

기본값 false
예제: true
item_idinteger(Bundles_item_id)[ 1 .. 255 ] characters

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

예제: 1
limitsobject or null(admin-item-limit-response)

아이템 제한 사항입니다.

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 or null

번들의 추가 자산입니다.

예제: [{"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(Bundles_order)

목록에서 번들의 주문 우선 순위입니다.

기본값 1
예제: 1
periodsArray of objects(item-periods-response)

아이템 판매 기간입니다.

pricesArray of objects(Bundles_prices)

실제 통화 가격입니다.

regionsArray of objects(Bundles_admin-regions)
skustring(Bundles_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$

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

예제: "bundle_1"
total_content_priceobject or null(Bundles_total_content_price)

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

typestring(Bundles_type)

아이템 유형입니다.

예제: "bundle"
virtual_pricesArray of objects(Bundles_admin-response-virtual_price)
응답
application/json
{
  "attributes": [],
  "bundle_type": "standard",
  "content": [
    { … },
    { … },
    { … }
  ],
  "custom_attributes": {
    "purchased": 0,
    "type": "lootbox"
  },
  "description": {
    "en": "Empire bundle with items"
  },
  "groups": [
    { … }
  ],
  "image_url": "https://cdn.xsolla.net/img/misc/images/685b21f9d9dca4aa0c953e8816b4eb4b.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "item_id": 610316,
  "limits": {
    "per_item": null,
    "per_user": { … },
    "recurrent_schedule": null
  },
  "long_description": {
    "en": "Empire bundle with some goods"
  },
  "media_list": [],
  "name": {
    "en": "Empire bundle"
  },
  "order": 1,
  "periods": [
    { … }
  ],
  "prices": [],
  "regions": [],
  "sku": "com.xsolla.EmpireBundle_1",
  "type": "bundle",
  "virtual_prices": [
    { … }
  ]
}

번들 업데이트Server-sideAdmin

요청

번들을 업데이트합니다.

보안
basicAuth
경로
project_idinteger필수

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

예제: 44056
skustring필수

번들 SKU입니다.

예제: kg_1
본문application/json필수

번들 데이터가 있는 개체입니다.

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

특성 목록입니다.

주의. 아이템에 20개 이상의 특성을 지정할 수 없습니다. 제한을 초과하려고 하면 오류가 발생합니다.
bundle_typestring(Bundles_bundle_type)

번들 유형입니다. standard를 사용하여 아이템이 포함된 번들을 생성하고 번들에 포함된 아이템의 SKU를 지정합니다. partner_side_content를 사용하여 빈 번들을 생성하고 웹훅을 사용하여 직접 아이템을 추가합니다. 이 유형은 파트너 측의 카탈로그 개인 설정에만 사용됩니다.

기본값 "standard"
열거형"standard""partner_side_content"
예제: "standard"
contentArray of objects(Bundles_admin_content_request)non-empty
예제: [{"quantity":1,"sku":"com.xsolla.kg_1"}]
custom_attributesobject(json)(item-custom-attributes)<= 500 characters

아이템 특성과 값이 포함된 JSON 개체입니다. 특성을 사용하면 아이템을 사용할 수 있는 플레이어의 레벨과 같은 추가 정보를 아이템에 추가할 수 있습니다. 특성은 게임의 내부 논리를 강화하며 전용 GET 메소드와 웹훅을 통해 이용할 수 있습니다.

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)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

description.​arstring or null

아랍어

description.​bgstring or null

불가리아어

description.​cnstring or null

중국어(간체)

description.​csstring or null

체코어

description.​destring or null

독일어

description.​enstring or null

영어

description.​esstring or null

스페인어(스페인)

description.​frstring or null

프랑스어

description.​hestring or null

히브리어

description.​idstring or null

인도네시아어

description.​itstring or null

이탈리아어

description.​jastring or null

일본어

description.​kmstring or null

크메르어

description.​kostring or null

한국어

description.​lostring or null

라오스어

description.​mystring or null

버마어

description.​nestring or null

네팔어

description.​phstring or null

필리핀어

description.​plstring or null

폴란드어

description.​ptstring or null

포르투칼어

description.​rostring or null

로마니아어

description.​rustring or null

러시아어

description.​thstring or null

태국어

description.​trstring or null

터키어

description.​twstring or null

중국어(번체)

description.​vistring or null

베트남어

groupsArray of strings(Bundles_groups_request)

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

메모. 문자열 값은 그룹 `external_id`을 참조합니다.
기본값 []
예제: ["honor"]
image_urlstring or null(Bundles_image_url)

이미지 URL입니다.

예제: "https://image.example.com"
is_enabledboolean(Bundles_is_enabled)

비활성화된 경우 아이템을 검색하거나 구매할 수 없습니다.

기본값 true
예제: true
is_freeboolean(value-is_free)

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

기본값 false
예제: false
is_show_in_storeboolean(Bundles_is_show_in_store)

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

기본값 false
예제: true
limitsobject(bundle-item-limit)

아이템 제한 사항입니다.

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 or null

번들의 추가 자산입니다.

예제: [{"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)이 모두 제공되면 마지막으로 제공된 값이 저장됩니다. 지원되는 언어의 전체 목록은 문서에서 확인할 수 있습니다.

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(Bundles_order)

목록에서 번들의 주문 우선 순위입니다.

기본값 1
예제: 1
periodsArray of objects or null(item-periods)

아이템 판매 기간입니다.

pricesArray of objects(Bundles_prices)

실제 통화 가격입니다.

regionsArray of objects(Bundles_admin-regions)
skustring(Bundles_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$필수

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

예제: "bundle_1"
vc_pricesArray of objects or null
curl -i -X PUT \
  -u <username>:<password> \
  https://xsolla.redocly.app/_mock/ko/api/catalog/v2/project/44056/admin/items/bundle/sku/kg_1 \
  -H 'Content-Type: application/json' \
  -d '{
    "attributes": [
      {
        "external_id": "class",
        "name": {
          "en": "Class"
        },
        "values": [
          {
            "external_id": "soldier",
            "value": {
              "en": "Soldier"
            }
          },
          {
            "external_id": "officer",
            "value": {
              "en": "Officer"
            }
          }
        ]
      }
    ],
    "content": [
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_gloves_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_boots_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_shield_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_armour_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_helmet_1"
      }
    ],
    "custom_attributes": {
      "purchased": 0,
      "type": "lootbox"
    },
    "description": {
      "de": "Brustpanzer für Soldaten",
      "en": "Chest of armour for soldiers"
    },
    "groups": [
      "chests"
    ],
    "image_url": "https://picture.bundle-with-many-stuff.png",
    "is_enabled": true,
    "is_free": true,
    "limits": {
      "per_item": null,
      "per_user": null
    },
    "long_description": {
      "de": "Brustpanzer für Soldaten",
      "en": "Chest of armour for soldiers"
    },
    "media_list": [
      {
        "type": "image",
        "url": "https://test.com/image0"
      },
      {
        "type": "image",
        "url": "https://test.com/image1"
      }
    ],
    "name": {
      "de": "Brustpanzer",
      "en": "Chest of armour"
    },
    "order": 1,
    "periods": [
      {
        "date_from": "2020-08-11T10:00:00+03:00",
        "date_until": "2020-08-11T20:00:00+03:00"
      }
    ],
    "prices": [
      {
        "amount": "9.99",
        "currency": "USD",
        "is_default": true,
        "is_enabled": true
      },
      {
        "amount": "9.99",
        "currency": "EUR",
        "is_default": false,
        "is_enabled": true
      }
    ],
    "sku": "com.xsolla.armour_chest_1",
    "vc_prices": []
  }'

응답

번들을 성공적으로 업데이트했습니다.

본문
응답
콘텐츠 없음

카탈로그

작업

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

작업

장바구니(서버 측)

작업

결제(클라이언트 측)

작업

결제(서버 측)

작업

주문

작업

무료 아이템

작업

관리

작업

관리자

작업

웹훅

작업

선주문

작업

판매자

작업

카탈로그

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

작업

공통 지역

작업

관리자

작업