Перейти к содержимому
/
Получение виртуальной вал...

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/ru/api/catalog/
https://store.xsolla.com/api/

Admin

Операции

Catalog

Операции

Получение пакета виртуальной валюты по артикулуClient-side

Запрос

Получает пакет виртуальной валюты по артикулу для построения каталога.

Примечание

Без авторизации метод возвращает общие данные. Используйте авторизацию, чтобы получить персонализированные данные пользователя, такие как лимиты и акции.
Безопасность
XsollaLoginUserJWT
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

Пример: 44056
virtual_currency_package_skustringобязательный

Артикул пакета виртуальной валюты.

Пример: crystal-pack
Запрос
localestring

Язык ответа. Двухбуквенный код языка в нижнем регистре в соответствии с ISO 639-1.

По умолчанию "en"
countrystring

Двухбуквенное обозначение страны в верхнем регистре согласно стандарту ISO 3166-1 alpha-2. Ознакомьтесь со списком стран, поддерживаемых Xsolla, а также с процессом определения страны.

Пример: country=US
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://xsolla.redocly.app/_mock/ru/api/catalog/v2/project/44056/items/virtual_currency/package/sku/crystal-pack?locale=en&country=US&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Ответы

Пакет виртуальной валюты был успешно получен.

Телоapplication/json
attributesArray of objects(Virtual-Items-Currency_client-attributes)

Список атрибутов и их значений, соответствующих товару. Может использоваться для фильтрации каталога.

По умолчанию []
Пример: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
bundle_typestring

Тип бандла: standard/virtual_currency_package.

Пример: "virtual_currency_package"
can_be_boughtboolean(Can_be_bought)

Если true, пользователь может купить товар.

Пример: true
contentArray of objects

Содержимое пакета виртуальной валюты.

Пример: [{"description":"Crystal Pack - short description","image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","name":"Crystal Pack","quantity":100,"sku":"com.xsolla.crystal_pack_1","type":"virtual_currency"}]
custom_attributesobject(json)(item-custom-attributes-response)

JSON-объект, содержащий атрибуты товара и их значения.

descriptionstring

Описание товара.

Пример: "Crystal Pack Description"
groupsArray of objects(items_client_groups_response)

Группы, к которым принадлежит товар.

По умолчанию []
Пример: [{"external_id":"exclusive","name":"Exclusive"}]
image_urlstring

URL-адрес изображения.

Пример: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
is_freeboolean(value-is_free)

Если true, товар бесплатный.

По умолчанию false
Пример: false
item_idinteger
limitsobject or null(Catalog_item_limits)

Ограничения на продажу товара.

namestring

Название товара.

Пример: "Crystal Pack"
periodsArray of objects(item-periods-response)

Период продажи товара.

priceobject

Цены на товар.

promotionsArray of objects(Catalog_item_promotions)

Примененные акции для отдельных товаров в корзине. Массив возвращается, если:

  • Скидочная акция настроена для отдельного товара.

  • Используется промокод с настройкой Скидка на выбранные товары.

Если акции на уровне отдельных товаров не применялись, возвращается пустой массив.

skustring

Уникальный ID товара. Артикул может содержать только строчные и заглавные латинские буквы, цифры, точки, тире и подчеркивания.

Пример: "crystal-pack"
typestring

Тип товара: virtual_good/virtual_currency/bundle.

Пример: "bundle"
virtual_pricesArray of objects

Виртуальные цены.

vp_rewardsArray of arrays
Ответ
application/json
{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "can_be_bought": true,
  "content": [
    { … }
  ],
  "custom_attributes": {
    "attr": "value",
    "purchased": 0
  },
  "description": "Crystal Pack Short Description",
  "groups": [],
  "image_url": "http://vc_package_image.png",
  "is_free": false,
  "item_id": 488832,
  "limits": {
    "per_item": null,
    "per_user": { … }
  },
  "name": "Crystal Pack",
  "periods": [
    { … }
  ],
  "price": {
    "amount": "100",
    "amount_without_discount": "100",
    "currency": "USD"
  },
  "promotions": [],
  "sku": "com.xsolla.crystal_pack_1",
  "type": "bundle",
  "virtual_prices": [],
  "vp_rewards": []
}

Получение виртуальной валюты по артукулуClient-side

Запрос

Получает виртуальную валюту по артикулу для построения каталога.

Примечание

Без авторизации метод возвращает общие данные. Используйте авторизацию, чтобы получить персонализированные данные пользователя, такие как лимиты и акции.
Безопасность
XsollaLoginUserJWT
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

Пример: 44056
virtual_currency_skustringобязательный

Артикул виртуальной валюты.

Пример: crystal
Запрос
localestring

Язык ответа. Двухбуквенный код языка в нижнем регистре в соответствии с ISO 639-1.

По умолчанию "en"
countrystring

Двухбуквенное обозначение страны в верхнем регистре согласно стандарту ISO 3166-1 alpha-2. Ознакомьтесь со списком стран, поддерживаемых Xsolla, а также с процессом определения страны.

Пример: country=US
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://xsolla.redocly.app/_mock/ru/api/catalog/v2/project/44056/items/virtual_currency/sku/crystal?locale=en&country=US&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Ответы

Виртуальная валюта была успешно получена.

Телоapplication/json
attributesArray of objects(Virtual-Items-Currency_client-attributes)

Список атрибутов и их значений, соответствующих товару. Может использоваться для фильтрации каталога.

По умолчанию []
Пример: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
can_be_boughtboolean(Can_be_bought)

Если true, пользователь может купить товар.

Пример: true
custom_attributesobject(json)(item-custom-attributes-response)

JSON-объект, содержащий атрибуты товара и их значения.

descriptionstring

Описание товара.

Пример: "Crystals - description"
groupsArray of objects(items_client_groups_response)

Группы, к которым принадлежит товар.

По умолчанию []
Пример: [{"external_id":"exclusive","name":"Exclusive"}]
image_urlstring

URL-адрес изображения.

Пример: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
is_freeboolean(value-is_free)

Если true, товар бесплатный.

По умолчанию false
Пример: false
item_idinteger
limitsobject or null(Catalog_item_limits)

Ограничения на продажу товара.

namestring

Название товара.

Пример: "Big Rocket"
periodsArray of objects(item-periods-response)

Период продажи товара.

priceobject or null

Цены на товар.

promotionsArray of objects(Catalog_item_promotions)

Примененные акции для отдельных товаров в корзине. Массив возвращается, если:

  • Скидочная акция настроена для отдельного товара.

  • Используется промокод с настройкой Скидка на выбранные товары.

Если акции на уровне отдельных товаров не применялись, возвращается пустой массив.

skustring

Уникальный ID товара. Артикул может содержать только строчные и заглавные латинские буквы, цифры, точки, тире и подчеркивания.

Пример: "big_rocket"
typestring

Тип товара: virtual_good/virtual_currency/bundle.

Пример: "virtual_currency"
virtual_pricesArray of objects

Виртуальные цены.

Пример: [{"amount":100,"amount_without_discount":100,"image_url":"http://image.png","is_default":true,"sku":"com.xsolla.crystals_1"}]
vp_rewardsArray of arrays
Ответ
application/json
{
  "attributes": [
    { … }
  ],
  "can_be_bought": true,
  "custom_attributes": {
    "attr": "value",
    "purchased": 0
  },
  "description": "Crystals - short description",
  "groups": [],
  "image_url": "https://cdn3.xsolla.com/img/misc/images/da33ab6cc1d7e5899cfdc5b6b6180fad.png",
  "is_free": false,
  "item_id": 451414,
  "limits": null,
  "name": "Crystals",
  "periods": [
    { … }
  ],
  "price": {
    "amount": "100",
    "amount_without_discount": "100",
    "currency": "USD"
  },
  "promotions": [],
  "sku": "com.xsolla.crystal_1",
  "type": "virtual_currency",
  "virtual_prices": []
}

Получение списка виртуальных предметовClient-side

Запрос

Получает список виртуальных предметов для построения каталога.

Внимание

Все проекты имеют ограничение на количество товаров, которые вы можете получить в ответе. Значение по умолчанию и максимальное значение — 50 товаров на ответ. Чтобы получить больше данных постранично, используйте поля limit и offset.

Примечание

Использование каталога товаров доступно без авторизации, но для получения персонализированного каталога необходимо передать JWT пользователя в заголовке Authorization.
Безопасность
XsollaLoginUserJWT
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта.

Пример: 44056
Запрос
limitinteger>= 1

Лимит количества элементов на странице.

Пример: limit=50
offsetinteger>= 0

Номер элемента, с которого выполняется вывод на странице (нумерация ведется с 0).

Пример: offset=0
localestring

Язык ответа. Двухбуквенный код языка в нижнем регистре в соответствии с ISO 639-1.

По умолчанию "en"
additional_fields[]Array of strings

Список дополнительных полей. Эти поля будут указаны в ответе, если вы отправите их в своем запросе.

Элементы Перечисление"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Двухбуквенное обозначение страны в верхнем регистре согласно стандарту ISO 3166-1 alpha-2. Ознакомьтесь со списком стран, поддерживаемых Xsolla, а также с процессом определения страны.

Пример: 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://xsolla.redocly.app/_mock/ru/api/catalog/v2/project/44056/items/virtual_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(Pagination_has-more)

Используется как индикатор того, что остались еще страницы.

Пример: true
itemsArray of objects(Virtual-Items-Currency_item)
Ответ
application/json
{
  "has_more": true,
  "items": [
    { … },
    { … },
    { … }
  ]
}

Виртуальная оплата

Операции

Catalog

Операции

Владение играми

Операции

Admin

Операции

Admin

Операции

Catalog

Операции

Корзина (на стороне клиента)

Операции

Корзина (на стороне сервера)

Операции

Оплата (на стороне клиента)

Операции

Оплата (на стороне сервера)

Операции

Заказ

Операции

Бесплатные товары

Операции

Управление

Операции

Admin

Операции

Вебхуки

Операции

Предзаказы

Операции

Продавец

Операции

Catalog

Данный API позволяет получать продаваемые товары любого вида или конкретный товар.

Операции

Общие регионы

Операции

Admin

Операции