跳转到内容
/
获取用户拥有的游戏列表

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/

管理

操作

目录

操作

虚拟支付

操作

目录

操作

权利

操作

撤销授权（管理员）Server-sideAdmin

请求

撤销用户的权利。

注意：

只能撤销DRM free平台的游戏密钥或游戏。
安全
basicAuth
路径
project_idinteger必需

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

示例: 44056
正文application/json必需
drmobject必需

包含DRM属性的对象。

示例: {"sku":"com.xsolla.key_1"}
drm.​skustring(Game-Keys_drm_sku)必需

唯一DRM ID。

枚举"steam""playstation""xbox""uplay""origin""drmfree""gog""epicgames""nintendo_eshop""discord_game_store"
示例: "steam"
gameobject必需

包含游戏属性的对象。

示例: {"sku":"com.xsolla.game_1"}
game.​skustring(Game-Keys_game_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$必需

唯一密钥套餐ID。

示例: "theGreatestGameSku"
modestring必需

应该撤销什么类型的权利。如果该参数设置为sandbox，则将在沙盒模式下撤销用户权利。如果该参数设置为default，则在实时模式下撤销用户权利。

枚举"default""sandbox"
示例: "default"
user_external_idstring必需

唯一用户标识符。

示例: "user-external-id"
curl -i -X POST \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/entitlement/revoke \
  -H 'Content-Type: application/json' \
  -d '{
    "drm": {
      "sku": "com.xsolla.key_1"
    },
    "game": {
      "sku": "com.xsolla.game_1"
    },
    "mode": "default",
    "user_external_id": "user-external-id"
  }'

响应

成功撤销。

响应
无内容

获取用户拥有的游戏列表Client-side

请求

获取用户拥有的游戏列表。响应将包含指定用户拥有的一组游戏。

注意：

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

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

示例: 44056
查询
limitinteger>= 1

页面上元素数量的限制。

示例: limit=50
offsetinteger>= 0

元素编号，从该元素开始生成列表（从0开始数）。

示例: offset=0
sandboxinteger

应返回何种类型的权利。如果该参数设置为1，则仅返回用户在沙盒模式下收到的权限。如果未传递该参数或设置为0，则仅返回用户在实时模式下收到的权利。

默认值 0
additional_fields[]Array of strings

附加字段列表。如果在请求中发送这些字段，则它们将包含在响应中。可用字段attributes。

curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/entitlement?limit=50&offset=0&sandbox=0&additional_fields%5B%5D=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

响应

已成功接收用户拥有的游戏密钥的列表。

正文application/json
has_moreboolean(Pagination_has-more)

用作指示还有更多页面。

示例: true
itemsArray of objects(Game-Keys_entitlement_item)
total_items_countinteger(Pagination_total-items-count)

系统中的商品总数。

示例: 10
响应
application/json
{
  "has_more": false,
  "items": [
    { … }
  ],
  "total_items_count": 1
}

通过客户端兑换游戏密钥Client-side

请求

通过提供的游戏密钥授予权利。

注意：

只能兑换DRM free的密钥。
安全
XsollaLoginUserJWT
路径
project_idinteger必需

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

示例: 44056
正文application/json必需
codestring必需

游戏密钥。

示例: "AAAA-BBBB-CCCC-DDDD"
sandboxboolean

在沙盒模式下兑换游戏密钥。该选项适用于在公司用户列表中指定的那些用户。

默认值 false
示例: false
curl -i -X POST \
  https://store.xsolla.com/api/v2/project/44056/entitlement/redeem \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "AAAA-BBBB-CCCC-DDDD",
    "sandbox": false
  }'

响应

兑换成功。

响应
无内容

管理

操作

管理

操作

目录

操作

购物车（客户端侧）

操作

购物车（服务器侧）

操作

支付（客户端）

操作

支付（服务器端）

操作

订单

操作

免费商品

操作

管理

操作

管理

操作

Webhook

操作

预订

操作

商户

操作

目录

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

操作

通用区域

操作

管理

操作