跳转到内容
/
按SKU获取可售商品

Catalog API (2.0.0)

概述

  • 版本： 2.0.0
  • 服务器：https://store.xsolla.com/api
  • 通过邮件联系我们
  • 联系URL: https://xsolla.com/
  • 必需的TLS版本： 1.2

商品目录API支持在艾克索拉侧配置游戏内商品目录，并在您的商店中向用户展示目录内容。

通过该API可管理以下目录实体：

  • 虚拟物品 — 游戏内物品，例如武器、皮肤、增益道具。
  • 虚拟货币 — 用于购买虚拟商品的虚拟货币。
  • 虚拟货币套餐 — 预定义的虚拟货币捆绑包。
  • 捆绑包 — 虚拟物品、货币或游戏激活码的组合套餐，以单个SKU形式出售。
  • 游戏密钥 — 适用于Steam等平台或其他DRM提供商分发的游戏和DLC激活码。
  • 组 — 用于在目录中组织和排序商品的逻辑分组。

API调用

API分为以下组别：

  • Admin — 用于创建、更新、删除和配置目录商品及分组的调用。通过基本认证方式验证身份，需使用您的商户或项目凭据。不适用于商店前端调用。
  • Catalog — 用于检索商品并构建面向最终用户的自定义商店前端。专为高负载场景设计。支持可选的用户JWT授权，可返回个性化数据，例如用户特定限制和当前进行中的促销活动。
下载 OpenAPI 描述
index.json
index.yaml
语言
服务器
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/zh/api/catalog/

管理

操作

目录

操作

虚拟支付

操作

目录

操作

权利

操作

管理

操作

管理

操作

目录

操作

购物车（客户端侧）

操作

购物车（服务器侧）

操作

支付（客户端）

操作

支付（服务器端）

操作

订单

操作

免费商品

操作

管理

操作

管理

操作

Webhook

操作

预订

操作

商户

操作

目录

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

操作

按ID获取可售商品Client-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。 SKU只能包含大小写英文字母和数字字符、句点、破折号和下划线。

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

按SKU获取可售商品Client-side

请求

按SKU获取用于构建目录的可售商品。

注：

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

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

示例: 59080
skustring必需

物品 SKU。

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

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

通用区域

操作

管理

操作