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

Catalog API (2.0.0)

Введение

API каталога позволяет настраивать каталог внутриигровых товаров на стороне Xsolla и отображать каталог пользователям в вашем игровом магазине.

API позволяет вам управлять такими сущностями каталога, как:

  • Виртуальные предметы — внутриигровые предметы, например оружие, скины, бустеры.
  • Виртуальная валюта — виртуальные деньги, которые используются для приобретения виртуальных товаров. Пакеты виртуальной валюты — предустановленные наборы виртуальной валюты.
  • Бандлы — комбинированные наборы виртуальных предметов, валюты или игровых ключей, продаваемые как единый артикул.
  • Игровые ключи — ключи для игр и DLC, распространяемые через такие платформы, как Steam, или других DRM-провайдеров.
  • Группы — логические группировки для организации и сортировки товаров в каталоге.

Методы API

Методы API делятся на следующие группы:

  • Admin — методы для создания, обновления, удаления и настройки товаров и групп каталога. Для вызова требуется базовая HTTP-аутентификация с использованием учетных данных Личного кабинета. Не предназначены для построения витрин для конечных пользователей.
  • Catalog — методы для получения товаров и построения витрин для конечных пользователей. Поддерживают опциональную аутентификацию с использованием JWT пользователя для возврата персонализированных данных, таких как пользовательские лимиты и активные промоакции.
Скачать описание OpenAPI
index.json
index.yaml
Языки
Серверы
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ru/api/catalog/

Admin

Операции

Catalog

Операции

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

Операции

Catalog

Операции

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

Операции

Admin

Операции

Admin

Операции

Catalog

Операции

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

Операции

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

Операции

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

Операции

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

Операции

Заказ

Операции

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

Операции

Управление

Операции

Admin

Операции

Вебхуки

Операции

Предзаказы

Операции

Продавец

Операции

Catalog

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

Операции

Получение продаваемого товара по IDClient-side

Запрос

Получает продаваемый товар по его ID.

Примечание

Без авторизации метод возвращает общие данные. Используйте авторизацию, чтобы получить персонализированные данные пользователя, такие как лимиты и акции.
Безопасность
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
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

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

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

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

descriptionstring

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

Пример: "Electric shield"
groupsArray of objects(items_client_groups_response)

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

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

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

Пример: "https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png"
is_freeboolean(value-is_free)

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

По умолчанию false
Пример: false
item_idinteger

Внутренний уникальный ID товара, который задается при создании товара.

Пример: 259774
limitsobject or null(Catalog_item_limits)

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

namestring

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

Пример: "Electric shield"
priceobject

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

promotionsArray of objects(Catalog_item_promotions)

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

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

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

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

skustring

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

Пример: "electric_shield"
typestring

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

Перечисление"virtual_good""virtual_currency""bundle""game_key""physical_good"
Пример: "virtual_good"
virtual_item_typestring

Тип виртуального предмета.

Перечисление ЗначениеОписание
consumable

Предмет исчезает из инвентаря после использования (например, патроны).

non_consumable

Предмет остается в инвентаре в течение неограниченного времени.

non_renewing_subscription

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

Пример: "non-consumable"
virtual_pricesArray of objects

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

vp_rewardsArray of objects(client-item-value-point-reward)

Стоимость призовых баллов товара.

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

Получение продаваемого товара по артикулуClient-side

Запрос

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

Примечание

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

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

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

Артикул товара.

Пример: 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
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

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

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

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

descriptionstring

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

Пример: "Electric shield"
groupsArray of objects(items_client_groups_response)

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

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

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

Пример: "https://cdn3.xsolla.com/img/misc/images/d2d6b1b517e6a7f3765c3bb5a3cfb87d.png"
is_freeboolean(value-is_free)

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

По умолчанию false
Пример: false
item_idinteger

Внутренний уникальный ID товара, который задается при создании товара.

Пример: 259774
limitsobject or null(Catalog_item_limits)

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

namestring

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

Пример: "Electric shield"
priceobject

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

promotionsArray of objects(Catalog_item_promotions)

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

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

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

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

skustring

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

Пример: "electric_shield"
typestring

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

Перечисление"virtual_good""virtual_currency""bundle""game_key""physical_good"
Пример: "virtual_good"
virtual_item_typestring

Тип виртуального предмета.

Перечисление ЗначениеОписание
consumable

Предмет исчезает из инвентаря после использования (например, патроны).

non_consumable

Предмет остается в инвентаре в течение неограниченного времени.

non_renewing_subscription

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

Пример: "non-consumable"
virtual_pricesArray of objects

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

vp_rewardsArray of objects(client-item-value-point-reward)

Стоимость призовых баллов товара.

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

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

Операции

Admin

Операции