跳转到内容
/
按SKU获取虚拟币套餐

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

管理

操作

目录

操作

获取虚拟货币套餐列表Client-side

请求

获取用于构建目录的虚拟货币套餐列表。

注意：

所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。

注：

使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。
安全
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标准下的两个大写字母的国家/地区代码。 请查看文档详细了解艾克索拉支持的国家/地区和国家/地区的判断流程。

示例: 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/zh/api/catalog/v2/project/44056/items/virtual_currency/package?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_virtual-currency-package)
响应
application/json
{
  "has_more": false,
  "items": [
    { … },
    { … }
  ]
}

按SKU获取虚拟币套餐Client-side

请求

按SKU获取用于构建目录的虚拟货币套餐。

注：

此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。
安全
XsollaLoginUserJWT
路径
project_idinteger必需

项目ID。您可以在您的发布商帐户项目名称旁边找到。

示例: 44056
virtual_currency_package_skustring必需

虚拟货币套餐SKU。

示例: crystal-pack
查询
localestring

响应语言。按照ISO 639-1规定使用两个小写字母的语言代码。

默认值 "en"
countrystring

ISO 3166-1 alpha-2标准下的两个大写字母的国家/地区代码。 请查看文档详细了解艾克索拉支持的国家/地区和国家/地区的判断流程。

示例: 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/zh/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。 SKU只能包含大小写英文字母和数字字符、句点、破折号和下划线。

示例: "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": []
}

按SKU获取虚拟货币Client-side

请求

按SKU获取用于构建目录的虚拟货币。

注：

此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。
安全
XsollaLoginUserJWT
路径
project_idinteger必需

项目ID。您可以在您的发布商帐户项目名称旁边找到。

示例: 44056
virtual_currency_skustring必需

虚拟货币SKU。

示例: crystal
查询
localestring

响应语言。按照ISO 639-1规定使用两个小写字母的语言代码。

默认值 "en"
countrystring

ISO 3166-1 alpha-2标准下的两个大写字母的国家/地区代码。 请查看文档详细了解艾克索拉支持的国家/地区和国家/地区的判断流程。

示例: 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/zh/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。 SKU只能包含大小写英文字母和数字字符、句点、破折号和下划线。

示例: "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": []
}

虚拟支付

操作

目录

操作

权利

操作

管理

操作

管理

操作

目录

操作

购物车（客户端侧）

操作

购物车（服务器侧）

操作

支付（客户端）

操作

支付（服务器端）

操作

订单

操作

免费商品

操作

管理

操作

管理

操作

Webhook

操作

预订

操作

商户

操作

目录

本API允许获取任意类型的可售商品或指定商品。

操作

通用区域

操作

管理

操作