Перейти к содержимому

Введение

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

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

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

Методы API

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

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

Создание виртуальной валютыServer-sideAdmin

Запрос

Создает виртуальную валюту.

Безопасность
basicAuth
Путь
project_idintegerобязательный

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

Пример: 44056
Телоapplication/json
attributesArray of objects(Virtual-Items-Currency_admin-post-put-attributes)<= 20 items

Список атрибутов.

Внимание. Для товара невозможно указать более 20 атрибутов. Любые попытки превысить данное ограничение вызовут ошибку.
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), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

groupsArray of objects(Virtual-Items-Currency_admin-groups-response)

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

По умолчанию []
Пример: [{"external_id":"horror","name":{"en":"Horror"}}]
image_urlstring(Virtual-Items-Currency_admin-image_url)
is_deletedboolean(Virtual-Items-Currency_is_deleted)
is_enabledboolean(Virtual-Items-Currency_is_enabled)
is_freeboolean(value-is_free)

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

По умолчанию false
Пример: false
is_hardboolean(Virtual-Items-Currency_is_hard)
is_paid_randomized_rewardboolean(value-is_paid_randomized_reward)

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

По умолчанию false
Пример: false
is_show_in_storeboolean(Virtual-Items-Currency_is_show_in_store)
limitsobject(Virtual-Currency-item-limit)

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

long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

Any of:

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

media_listArray of objects(Virtual-Items-Currency_admin-media_list)

Дополнительные ассеты предмета, такие как скриншоты, видео игрового процесса и так далее.

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

Spanish (Spain)

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(Virtual-Items-Currency_order)

Определяет порядок расположения.

Пример: 1
periodsArray of objects or null(item-periods)

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

pre_orderobject(Virtual-Items-Currency_admin-pre_order)
pricesArray of objects(Virtual-Items-Currency_admin-prices)
Пример: [{"amount":10.5,"country_iso":"US","currency":"USD","is_default":true,"is_enabled":true}]
regionsArray of objects(Virtual-Items-Currency_admin-regions)
skustring(Virtual-Items-Currency_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$обязательный

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

Пример: "booster_mega_1"
vc_pricesArray of objects(Virtual-Items-Currency_admin-create-vc_prices)
Пример: [{"amount":10,"is_default":true,"is_enabled":true,"sku":"com.xsolla.gold_1"}]
curl -i -X POST \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_currency \
  -H 'Content-Type: application/json' \
  -d '{
    "attributes": [
      {
        "external_id": "material",
        "name": {
          "en-US": "Material"
        },
        "values": [
          {
            "external_id": "gold",
            "value": {
              "en-US": "Gold"
            }
          }
        ]
      }
    ],
    "custom_attributes": {
      "attr": "value",
      "purchased": 0
    },
    "description": {
      "de-DE": "Die Hauptwährung deines Königreichs",
      "en-US": "The main currency of your kingdom"
    },
    "groups": [
      "gold"
    ],
    "is_enabled": true,
    "is_free": false,
    "is_paid_randomized_reward": false,
    "limits": {
      "per_item": 10000,
      "per_user": 5
    },
    "name": {
      "de-DE": "Goldmünze",
      "en-US": "Gold coin"
    },
    "order": 1,
    "periods": [
      {
        "date_from": "2020-08-11T10:00:00+03:00",
        "date_until": "2020-08-11T20:00:00+03:00"
      }
    ],
    "prices": [
      {
        "amount": 100,
        "currency": "USD",
        "is_default": true,
        "is_enabled": true
      }
    ],
    "sku": "com.xsolla.coin_1"
  }'

Ответы

Виртуальный предмет успешно создан.

Телоapplication/json
skustring
Пример: "com.xsolla.item_1"
Ответ
application/json
{ "sku": "com.xsolla.item_1" }

Получение списка пакетов виртуальной валюты (admin)Server-sideAdmin

Запрос

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

Примечание

Не используйте данный метод для построения каталога магазина.
Безопасность
basicAuth
Путь
project_idintegerобязательный

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

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

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

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

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

Пример: offset=0
curl -i -X GET \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_currency/package?limit=50&offset=0'

Ответы

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

Телоapplication/json
itemsArray of objects(Virtual-Items-Currency_admin-virtual-currency-package)
Ответ
application/json
{ "items": [ {}, {}, {}, {}, {}, {} ] }

Создание пакета виртуальной валютыServer-sideAdmin

Запрос

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

Безопасность
basicAuth
Путь
project_idintegerобязательный

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

Пример: 44056
Телоapplication/json
Any of:
attributesArray of objects(Virtual-Items-Currency_admin-post-put-attributes)<= 20 items

Список атрибутов.

Внимание. Для товара невозможно указать более 20 атрибутов. Любые попытки превысить данное ограничение вызовут ошибку.
contentArray of objects= 1 charactersобязательный

Пакет виртуальной валюты должен содержать только 1 позицию виртуальной валюты.

content[].​quantityinteger
content[].​skustring(Virtual-Items-Currency_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$

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

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

Spanish (Spain)

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(Virtual-Items-Currency_admin-groups-create)

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

Примечание. Строковое значение относится к группе `external_id`.
image_urlstring(Virtual-Items-Currency_admin-image_url)
is_deletedboolean(Virtual-Items-Currency_is_deleted)
is_enabledboolean(Virtual-Items-Currency_is_enabled)
is_freeboolean(value-is_free)

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

По умолчанию false
Пример: false
is_paid_randomized_rewardboolean(value-is_paid_randomized_reward)

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

По умолчанию false
Пример: false
is_show_in_storeboolean(Virtual-Items-Currency_is_show_in_store)
limitsobject(Virtual-Currency-Package-item-limit)

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

long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

Any of:

Объект с локализованными длинными описаниями товара. Принимает значения в одном из двух форматов: двухбуквенный код языка в нижнем регистре (например, en) или код локали из пяти символов (например, en-US). Оба формата допустимы при отправке запроса, но в ответе всегда используется код из двух символов. Если для одного языка указаны оба варианта (например, en и en-US), будет сохранено последнее переданное значение. Полный список поддерживаемых языков приведен в документации.

media_listArray of objects(Virtual-Items-Currency_admin-media_list)

Дополнительные ассеты предмета, такие как скриншоты, видео игрового процесса и так далее.

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

Spanish (Spain)

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(Virtual-Items-Currency_order)

Определяет порядок расположения.

Пример: 1
periodsArray of objects or null(item-periods)

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

pre_orderobject(Virtual-Items-Currency_admin-pre_order)
pricesArray of objects(Virtual-Items-Currency_admin-prices)обязательный
Пример: [{"amount":10.5,"country_iso":"US","currency":"USD","is_default":true,"is_enabled":true}]
prices[].​amountnumber> 0обязательный

Сумма.

Пример: 10.5
prices[].​country_isostring or null

Страна, где доступна эта цена. Двухбуквенный код в соответствии с ISO 3166-1 alpha 2.

Пример: "US"
prices[].​currencystringобязательный

Валюта, в которой указана цена товара. Трехбуквенный код в соответствии с ISO 4217. Подробную информацию о валютах, поддерживаемых Xsolla, смотрите в документации.

Пример: "USD"
prices[].​is_defaultboolean
По умолчанию false
Пример: true
prices[].​is_enabledboolean
По умолчанию true
Пример: true
regionsArray of objects(Virtual-Items-Currency_admin-regions)
skustring(Virtual-Items-Currency_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$обязательный

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

Пример: "booster_mega_1"
vc_pricesArray of objects(Virtual-Items-Currency_admin-create-vc_prices)
Пример: [{"amount":10,"is_default":true,"is_enabled":true,"sku":"com.xsolla.gold_1"}]
curl -i -X POST \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_currency/package \
  -H 'Content-Type: application/json' \
  -d '{
    "attributes": [
      {
        "external_id": "event",
        "name": {
          "en-US": "Event"
        },
        "values": [
          {
            "external_id": "10-anniversary",
            "value": {
              "en-US": "10th anniversary"
            }
          },
          {
            "external_id": "christmas",
            "value": {
              "en-US": "Christmas"
            }
          }
        ]
      }
    ],
    "content": [
      {
        "quantity": 500,
        "sku": "com.xsolla.novigrad_crown"
      }
    ],
    "custom_attributes": {
      "attr": "value",
      "purchased": 0
    },
    "description": {
      "en-US": "The Crown (also known as the Novigradian crown) is a monetary unit which is used in some Northern Kingdoms",
      "ru-RU": "Крона (Также известна как Новиградская крона) - платежная единица, используемая в северных королевствах"
    },
    "groups": [
      "witcher"
    ],
    "image_url": "https://vignette.wikia.nocookie.net/witcher/images/7/7c/Items_Orens.png/revision/latest?cb=20081113120917",
    "is_enabled": true,
    "is_free": false,
    "is_paid_randomized_reward": true,
    "limits": {
      "per_item": null,
      "per_user": null
    },
    "long_description": {
      "en-US": "Long Test new",
      "ru-RU": "Длинное описание"
    },
    "media_list": [
      {
        "type": "image",
        "url": "https://test.com/image0"
      },
      {
        "type": "image",
        "url": "https://test.com/image1"
      }
    ],
    "name": {
      "en-US": "500x Novigradian crown",
      "ru-RU": "500x Новиградских крон"
    },
    "order": 1,
    "periods": [
      {
        "date_from": "2020-08-11T10:00:00+03:00",
        "date_until": "2020-08-11T20:00:00+03:00"
      }
    ],
    "prices": [
      {
        "amount": 99.99,
        "currency": "USD",
        "is_default": true
      },
      {
        "amount": 80.03,
        "currency": "EUR",
        "is_enabled": false
      }
    ],
    "sku": "com.xsolla.novigrad_crown_500",
    "vc_prices": null
  }'

Ответы

Виртуальный предмет успешно создан.

Телоapplication/json
skustring
Пример: "com.xsolla.item_1"
Ответ
application/json
{ "sku": "com.xsolla.item_1" }
Операции
Операции
Операции
Операции
Операции
Операции
Операции

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

Операции

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

Операции

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

Операции

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

Операции
Операции
Операции
Операции
Операции
Операции
Операции
Операции

Catalog

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

Операции
Операции
Операции