概述

• 版本： 2.0.0
• 服务器： https://store.xsolla.com/api
• 通过电子邮件联系我们
• 联系网址： https://xsolla.com/
• 所需TLS版本： 1.2

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

该API可用于管理以下商品目录实体：

• 虚拟物品 — 武器、皮肤、加成道具等游戏内物品。
• 虚拟货币 — 用于购买虚拟物品的虚拟资金。
• 虚拟货币套餐 — 预定义的虚拟货币捆绑包。
• 捆绑包 — 将虚拟物品、货币或游戏Key组合后作为单个SKU销售的组合包。
• 游戏Key — 通过Steam等平台或其他DRM提供商分发的游戏和DLC密钥。
• 组 — 用于在商品目录中组织和排序商品的逻辑分组。

API调用

该API分为以下组别：

• Admin — 用于创建、更新、删除和配置商品目录中的商品及分组的调用。通过基本访问身份认证方式进行身份认证，需使用您的商户或项目凭据。不适用于商店前端调用。
• Catalog — 用于检索商品并构建面向最终用户的自定义商店前端。专为高负载场景设计。支持可选的用户JWT授权，可返回个性化数据，例如用户限购额度和当前进行中的促销活动。

身份认证

API调用需要以用户身份或项目身份进行身份认证。使用的身份认证方案见各调用描述中的安全性部分。

使用用户JWT进行身份认证

当请求从浏览器、移动应用或游戏发送时，使用用户JWT身份认证。默认情况下，应用XsollaLoginUserJWT方案。有关如何创建令牌的详细信息，请参阅艾克索拉登录管理器API文档。

令牌通过Authorization请求头按以下格式传递：Authorization: Bearer <user_JWT>，其中<user_JWT>为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。

或者，您也可以使用用于打开支付UI的令牌。

基本HTTP身份认证

基本HTTP身份认证用于服务器到服务器交互，即API调用直接从您的服务器发送，而不是从用户的浏览器或移动应用发送。通常使用带有API密钥的HTTP Basic身份认证。

使用基本服务器侧身份认证时，所有API请求都必须包含以下请求头：

• 对于basicAuth — Authorization: Basic <your_authorization_basic_key>，其中your_authorization_basic_key是以Base64编码的project_id:api_key对
• 对于basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>，其中your_authorization_basic_key是以Base64编码的merchant_id:api_key对

您可以在发布商帐户中找到参数值：

• merchant_id显示在：
  • 公司设置 > 公司中。
  • 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：https://publisher.xsolla.com/<merchant_id>。
• project_id显示在：
  • 发布商帐户中项目名称旁边。
  • 发布商帐户中项目页面的浏览器地址栏URL中。URL格式为：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
• api_key仅在创建时在发布商帐户中显示，必须在己侧安全存储。您可以在以下部分创建API密钥：
  • 公司设置 > API密钥
  • 项目设置 > API密钥

有关使用API密钥的更多信息，请参阅API参考。

支持访客访问的身份认证

AuthForCart身份认证方案用于购物车购买，支持两种模式：

1. 使用用户JWT进行身份认证。 令牌通过Authorization请求头按以下格式传递：Authorization: Bearer <user_JWT>，其中<user_JWT>是用户令牌。该令牌用于识别用户，并提供对个性化数据的访问权限。 或者，您也可以使用用于打开支付UI的令牌。

2. 不带Authorization请求头的简化模式。 此模式仅适用于未完成身份认证的用户，且仅可用于游戏Key销售请求中不使用令牌，而必须包含以下请求头：

   • x-unauthorized-id，值为请求ID
   • x-user，值为使用Base64编码的用户电子邮件地址

实用链接

• 按交互模型划分的API调用
• 接口类型
• 错误处理
• API密钥

核心实体结构

所有类型的商品（虚拟物品、捆绑包、虚拟货币和密钥）都使用类似的数据结构。了解基本结构有助于简化API使用，并帮助您更轻松地查阅文档。

标识信息

• merchant_id — 发布商帐户中的公司ID
• project_id — 发布商帐户中的项目ID
• sku — 商品SKU，在项目内唯一

商店显示

• name — 商品名称
• description — 商品描述
• image_url — 图片URL
• is_enabled — 商品可用性
• is_show_in_store — 商品是否显示在商品目录中

有关在商品目录中管理商品可用性的更多信息，请参阅文档。

组织方式

• type — 商品类型，例如虚拟物品（virtual_item）或捆绑包（bundle）
• groups — 商品所属的组
• order — 在商品目录中的显示顺序

Sale conditions

• prices — 以真实货币或虚拟货币表示的价格
• limits — 购买限制
• periods — 可用时间段
• regions — 区域限制

核心实体结构示例：

基本购买流程

艾克索拉API可用于实现游戏内购商店逻辑，包括获取商品目录、管理购物车、创建订单以及跟踪订单状态。根据集成场景，API调用分为管理和商品目录子部分，使用不同的身份认证方案。

以下示例展示了从创建商品到完成购买的商店设置和运营基本流程。

创建商品和组（管理）

为您的商店创建商品目录，例如虚拟物品、捆绑包或虚拟货币。

API调用示例：

• 创建虚拟物品
• 创建捆绑包
• 创建虚拟货币

设置促销、奖励链和限制（管理）

配置用户拉新和赢利工具，例如折扣、赠品、每日奖励或优惠链。

API调用示例：

• 创建买赠促销活动
• 创建每日奖励
• 创建唯一商品目录优惠促销活动

获取商品信息（客户端）

在您的应用程序中配置商品显示。

API调用示例：

• 获取虚拟物品列表
• 获取商品组列表
• 获取捆绑包列表
• 获取可售商品列表

销售商品

您可以使用以下方法销售商品：

• 快速购买 — 多次销售同一SKU。
• 购物车购买 — 用户可在同一订单中向购物车添加商品、移除商品并更新数量。

如果商品使用虚拟货币而非真实货币购买，请使用创建包含指定商品的订单 API调用。由于扣款会在执行API调用时处理，因此无需支付UI。

如需购买免费商品，请使用使用指定商品创建订单 API调用或使用免费购物车创建订单 API调用。无需支付UI — 订单会立即设置为done状态。

快速购买

使用客户端API调用使用指定商品创建订单。该调用会返回用于打开支付UI的令牌。

购物车购买

可以在客户端或服务器侧设置购物车并完成购买。

在客户端设置和购买购物车商品

您需要自行实现添加和移除商品的逻辑。在调用用于设置购物车的API之前，您无法获知哪些促销活动会应用于本次购买。这意味着您无法提前获知总费用以及添加的赠品的详细信息。

实现以下购物车逻辑：

1. 玩家在购物车加购后，使用向购物车添加商品 API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
2. 根据用户操作更新购物车内容：
   • 如需添加商品或更改商品数量，请使用按购物车ID更新购物车商品 API调用。
   • 如需移除商品，请使用按购物车ID删除购物车商品 API调用。

3. 使用创建包含当前购物车中所有商品的订单 API调用。该调用返回订单ID和支付令牌。新创建的订单默认设置为new状态。

在服务器侧设置和购买购物车商品

这种设置方式可能需要更长的购物车设置时间，因为每次更改购物车都必须伴随API调用。

实现以下购物车逻辑：

1. 玩家在购物车加购后，使用向购物车添加商品 API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
2. 使用创建包含当前购物车中所有商品的订单 API调用。该调用会返回订单ID和支付令牌。新创建的订单默认设置为new状态。

打开支付UI

使用返回的令牌在新窗口中打开支付UI。有关打开支付UI的其他方式，请参阅文档。

如需启用或禁用沙盒模式，请在快速购买和购物车购买请求中更改sandbox参数的值。沙盒模式默认关闭。

可能的订单状态：

• new — 订单已创建
• paid — 已收到付款
• done — 商品已交付
• canceled — 订单已取消
• expired — 订单已过期

使用以下任一方式跟踪订单状态：

• 您服务器上配置的Webhook
• 短轮询
• WebSocket API

实用链接

• 身份认证
• 按交互模型划分的API调用
• 支付测试
• 设置订单状态跟踪
• Webhook
• 速率限制
• 错误处理
• API密钥

分页

返回大量记录的API调用（例如构建商品目录时）会按页返回数据。分页是一种限制单个API响应中返回商品数量的机制，并允许您按顺序获取后续页面。

使用以下参数控制返回的商品数量：

• limit — 每页商品数量
• offset — 页面中第一个商品的索引（从0开始编号）
• has_more — 指示是否还有下一页
• total_items_count — 商品总数

请求示例：

响应示例：

建议发送后续请求，直到响应返回has_more = false。

日期和时间格式

日期和时间值以ISO 8601格式传递。

支持以下内容：

• UTC偏移量
• 当商品显示没有时间限制时使用null值
• 部分字段使用的Unix时间戳（以秒为单位）

格式：YYYY-MM-DDTHH:MM:SS±HH:MM

示例：2026-03-16T10:00:00+03:00

本地化

艾克索拉支持对商品名称、描述等面向用户的字段进行本地化。本地化值以对象形式传递，其中语言代码作为键。支持的完整语言列表，请参阅文档。

支持的字段

可为以下参数指定本地化内容：

• name
• description
• long_description

区域格式

语言区域键可使用以下任一格式指定：

• 两字母语言代码：en、ru
• 五字母语言代码：en-US、ru-RU、de-DE

示例

两字母语言代码示例：

五字母语言代码示例：

错误响应格式

如果发生错误，API会返回HTTP状态和JSON响应正文。商店相关错误的完整列表，请参阅文档。

响应示例：

• errorCode — 错误代码。
• errorMessage — 简短的错误描述。
• statusCode — HTTP响应状态。
• transactionId — 请求ID。仅在部分情况下返回。
• errorMessageExtended — 其他错误详情，例如请求参数。仅在某些情况下返回。

扩展响应示例：

常见HTTP状态代码

• 400 — 请求无效
• 401 — 身份认证错误
• 403 — 权限不足
• 404 — 资源未找到
• 422 — 验证错误
• 429 — 超出速率限制

建议

• 结合HTTP状态和响应正文一起处理。
• 使用errorCode处理与应用程序逻辑相关的错误。
• 分析错误时，使用transactionId更快定位请求。