# Catalog API

# Overview

* **Version:** 2.0.0
* **Servers**: `https://store.xsolla.com/api`
* **[Contact Us by Email](mailto:integration@xsolla.com)**
* **Contact URL:** https://xsolla.com/
* **Required TLS version:** 1.2

Catalog API提供端点，用于管理您的游戏内商店目录并处理购买。使用这些端点配置虚拟物品、虚拟货币、游戏密钥、捆绑包、购物车和支付流程、物品属性，以及从外部来源导入物品。

Version: 2.0.0

## Servers

```
https://store.xsolla.com/api
```

## Security

### AuthForCart

销售包含游戏的购物车时，您可以[在未授权状态下调用端点](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)。

具体方法：

* 向游戏标头中的`x-unauthorized-id`参数添加一个唯一标识符。
* 将用户的电子邮件添加到游戏标头中的`x-user`参数（根据Base64加密）。

默认情况下使用艾克索拉登录管理器用户JWT（持有者令牌）进行授权。您可以尝试使用艾克索拉登录管理器测试用户JWT令牌来调用此端点：`Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI`。

您也可以用[支付中心访问令牌](https://developers.xsolla.com/zh/api/pay-station/operation/create-token/)作为替代。

Type: http
Scheme: bearer

### XsollaLoginUserJWT

默认情况下使用艾克索拉登录管理器用户JWT（持有者令牌）进行授权。您可以尝试使用艾克索拉登录管理器测试用户JWT令牌来调用此端点：`Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI`。

您也可以使用[支付中心访问令牌](https://developers.xsolla.com/zh/api/pay-station/operation/create-token/)作为替代。

Type: http
Scheme: bearer
Bearer Format: JWT

### basicAuth

Xsolla API 使用基本访问身份验证。所有对 API 的请求都必须包含`Authorization: Basic <your_authorization_basic_key>`标题，其中`your_authorization_basic_key`是个`project_id:api_key`根据 Base64 标准进行编码。

您可以使用`merchant_id` 而不是`project_id` 如果需要的话。它不会影响功能。

去[发布商帐户](https://publisher.xsolla.com/)查找参数值：

* `merchant_id` 显示为：
  * 在 **公司设置 > 公司** 部分
  * 在任何发布商帐户页面的浏览器地址栏中的 URL 中。URL 的格式如下：`https://publisher.xsolla.com/<merchant_id>`。
* `api_key` 创建后仅在发布商帐户中显示一次，并且必须存储在您这边。您可以在以下部分创建新密钥：
  * **公司设置 > API 密钥**
  * **项目设置 > API 密钥**
* `project_id` 显示为：
  * 在发布者帐户中，项目名称旁边。
  * 在发布者帐户中处理项目时，浏览器地址栏中的 URL。URL 格式如下：`https://publisher.xsolla.com/<merchant_id>/projects/<project_id>`。

有关使用 API 密钥的更多信息，请参阅[API 参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。

Type: http
Scheme: basic

### basicMerchantAuth

艾克索拉API使用基本认证。所有发送到API的请求必须包含`Authorization: Basic <your_authorization_basic_key>`头，其中`your_authorization_basic_key`是根据Base64标准加密的`merchant_id:api_key`对。

去[发布商帐户](https://publisher.xsolla.com/)查找参数值：

* `merchant_id` 显示为：
  * 在 **公司设置 > 公司** 部分
  * 在任何发布商帐户页面的浏览器地址栏中的 URL 中。URL 的格式如下：`https://publisher.xsolla.com/<merchant_id>`
* `api_key` 创建后仅在发布商帐户中显示一次，并且必须存储在您这边。您可以在以下部分创建新密钥：
  * **公司设置 > API 密钥**
  * **项目设置 > API 密钥**

有关使用 API 密钥的更多信息，请参阅[API 参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。

Type: http
Scheme: basic

## Download OpenAPI description

[Catalog API](https://developers.xsolla.com/_bundle/@l10n/zh/api/catalog/index.yaml)

## 管理

### 获取虚拟货币列表

 - [GET /v2/project/{project_id}/admin/items/virtual_currency](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-currencies-list.md): 获取项目中的虚拟货币列表以进行管理。

注意不要使用此端点来构建商店目录。

### 创建虚拟货币

 - [POST /v2/project/{project_id}/admin/items/virtual_currency](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency.md): 创建虚拟货币。

### 获取虚拟货币套餐列表（管理）

 - [GET /v2/project/{project_id}/admin/items/virtual_currency/package](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-currency-packages-list.md): 获取项目中虚拟货币套餐的列表以进行管理。

注意不要使用此端点来构建商店目录。

### 创建虚拟货币套餐

 - [POST /v2/project/{project_id}/admin/items/virtual_currency/package](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency-package.md): 创建虚拟货币套餐。

### 删除虚拟货币套餐

 - [DELETE /v2/project/{project_id}/admin/items/virtual_currency/package/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-delete-virtual-currency-package.md): 删除虚拟货币套餐。

### 获取虚拟货币套餐

 - [GET /v2/project/{project_id}/admin/items/virtual_currency/package/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-currency-package.md): 获取项目中的虚拟货币套餐以进行管理。

注意不要使用此端点来构建商店目录。

### 更新虚拟货币套餐

 - [PUT /v2/project/{project_id}/admin/items/virtual_currency/package/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency-package.md): 更新虚拟货币套餐。

### 删除虚拟货币

 - [DELETE /v2/project/{project_id}/admin/items/virtual_currency/sku/{virtual_currency_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-delete-virtual-currency.md): 删除虚拟货币。

### 获取虚拟货币

 - [GET /v2/project/{project_id}/admin/items/virtual_currency/sku/{virtual_currency_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-currency.md): 获取项目中的虚拟货币以进行管理。

注意不要使用此端点来构建商店目录。

### 更新虚拟货币

 - [PUT /v2/project/{project_id}/admin/items/virtual_currency/sku/{virtual_currency_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency.md): 更新虚拟货币。

### 获取虚拟物品列表

 - [GET /v2/project/{project_id}/admin/items/virtual_items](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list.md): 获取项目中的虚拟物品列表以进行管理。

注意不要使用此端点来构建商店目录。

### 创建虚拟物品

 - [POST /v2/project/{project_id}/admin/items/virtual_items](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-item.md): 创建虚拟物品。

### 按照指定组的外部ID获取虚拟物品列表

 - [GET /v2/project/{project_id}/admin/items/virtual_items/group/external_id/{external_id}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list-by-group-external-id.md): 获取组中的虚拟物品列表以进行管理。

注意不要使用此端点来构建商店目录。

### 按照指定组ID获取虚拟物品列表

 - [GET /v2/project/{project_id}/admin/items/virtual_items/group/id/{group_id}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list-by-group-id.md): 获取组中的虚拟物品列表以进行管理。

注意不要使用此端点来构建商店目录。

### 删除虚拟物品

 - [DELETE /v2/project/{project_id}/admin/items/virtual_items/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-delete-virtual-item.md): 删除虚拟物品。

### 获取虚拟物品

 - [GET /v2/project/{project_id}/admin/items/virtual_items/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-item.md): 获取项目中的虚拟物品以进行管理。

注意不要使用此端点来构建商店目录。

### 更新虚拟物品

 - [PUT /v2/project/{project_id}/admin/items/virtual_items/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-update-virtual-item.md): 更新虚拟物品。

## 目录

### 获取商品组列表

 - [GET /v2/project/{project_id}/items/groups](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-item-groups.md): 获取用于构建目录的商品组列表。

### 获取虚拟货币列表

 - [GET /v2/project/{project_id}/items/virtual_currency](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency.md): 获取用于构建目录的虚拟货币列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 获取虚拟货币套餐列表

 - [GET /v2/project/{project_id}/items/virtual_currency/package](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package.md): 获取用于构建目录的虚拟货币套餐列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 按SKU获取虚拟币套餐

 - [GET /v2/project/{project_id}/items/virtual_currency/package/sku/{virtual_currency_package_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package-sku.md): 按SKU获取用于构建目录的虚拟货币套餐。
注：此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。

### 按SKU获取虚拟货币

 - [GET /v2/project/{project_id}/items/virtual_currency/sku/{virtual_currency_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-sku.md): 按SKU获取用于构建目录的虚拟货币。
注：此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。

### 获取虚拟物品列表

 - [GET /v2/project/{project_id}/items/virtual_items](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items.md): 获取用于构建目录的虚拟物品列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 获取所有虚拟物品列表

 - [GET /v2/project/{project_id}/items/virtual_items/all](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-all-virtual-items.md): 获取用于客户端搜索的所有虚拟物品的列表。

注意：仅返回物品SKU、名称、组和描述  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 按指定组获取商品列表

 - [GET /v2/project/{project_id}/items/virtual_items/group/{external_id}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items-group.md): 从指定组获取商品列表以构建目录。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。

### 按SKU获取虚拟物品

 - [GET /v2/project/{project_id}/items/virtual_items/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items-sku.md): 按SKU获取用于构建目录的虚拟物品。
注：此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。

## 虚拟支付

### 使用以虚拟货币购买的指定商品创建订单

 - [POST /v2/project/{project_id}/payment/item/{item_sku}/virtual/{virtual_currency_sku}](https://developers.xsolla.com/zh/api/catalog/virtual-payment/create-order-with-item-for-virtual-currency.md): 使用虚拟货币创建商品购买。

## 目录

### 获取游戏列表

 - [GET /v2/project/{project_id}/items/game](https://developers.xsolla.com/zh/api/catalog/game-keys-catalog/get-games-list.md): 获取用于构建目录的游戏列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 获取DRM列表

 - [GET /v2/project/{project_id}/items/game/drm](https://developers.xsolla.com/zh/api/catalog/game-keys-catalog/get-drm-list.md): 获取可用DRM的列表。

### 按指定组获取游戏列表

 - [GET /v2/project/{project_id}/items/game/group/{external_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-catalog/get-games-group.md): 从指定组中获取游戏列表以构建目录。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 按指定组获取游戏密钥列表

 - [GET /v2/project/{project_id}/items/game/key/group/{external_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-catalog/get-game-keys-group.md): 从指定组获取用于构建目录的游戏密钥列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 获取用于目录的游戏密钥

 - [GET /v2/project/{project_id}/items/game/key/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-catalog/get-game-key-by-sku.md): 获取用于目录的游戏密钥。

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

### 将游戏加入到目录

 - [GET /v2/project/{project_id}/items/game/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-catalog/get-game-by-sku.md): 获取用于目录的游戏。

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

## 权利

### 授予权利（管理员）

 - [POST /v2/project/{project_id}/admin/entitlement/grant](https://developers.xsolla.com/zh/api/catalog/game-keys-entitlement/grant-entitlement-admin.md): 授予用户权利。

注意：只能授予DRM free平台的游戏代码或游戏。

### 撤销授权（管理员）

 - [POST /v2/project/{project_id}/admin/entitlement/revoke](https://developers.xsolla.com/zh/api/catalog/game-keys-entitlement/revoke-entitlement-admin.md): 撤销用户的权利。

注意：只能撤销DRM free平台的游戏密钥或游戏。

### 获取用户拥有的游戏列表

 - [GET /v2/project/{project_id}/entitlement](https://developers.xsolla.com/zh/api/catalog/game-keys-entitlement/get-user-games.md): 获取用户拥有的游戏列表。响应将包含指定用户拥有的一组游戏。

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

### 通过客户端兑换游戏密钥

 - [POST /v2/project/{project_id}/entitlement/redeem](https://developers.xsolla.com/zh/api/catalog/game-keys-entitlement/redeem-game-pin-code.md): 通过提供的游戏密钥授予权利。

注意：只能兑换DRM free的密钥。

## 管理

### 获取游戏列表（管理）

 - [GET /v2/project/{project_id}/admin/items/game](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-get-game-list.md): 获取项目中的游戏列表以进行管理。
游戏由用户可以购买的游戏密钥组成。

注意不要使用此端点来构建商店目录。

### 创建游戏

 - [POST /v2/project/{project_id}/admin/items/game](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-create-game.md): 在项目中创建游戏。

### 通过ID删除游戏

 - [DELETE /v2/project/{project_id}/admin/items/game/id/{item_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-delete-game-by-id.md): 根据ID删除项目中的游戏。

### 通过ID获取游戏（管理）

 - [GET /v2/project/{project_id}/admin/items/game/id/{item_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-get-game-by-id.md): 获取游戏以进行管理。
游戏由用户可以购买的游戏密钥组成。

注意不要使用此端点来构建商店目录。

### 通过ID更新游戏

 - [PUT /v2/project/{project_id}/admin/items/game/id/{item_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-update-game-by-id.md): 通过ID更新项目中的游戏。

### 按ID删除密钥

 - [DELETE /v2/project/{project_id}/admin/items/game/key/delete/id/{item_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-delete-codes-by-id.md): 按游戏密钥ID删除所有密钥。

### 删除密钥

 - [DELETE /v2/project/{project_id}/admin/items/game/key/delete/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-delete-codes-by-sku.md): 按游戏密钥SKU删除所有密钥。

### 通过ID获取密钥

 - [GET /v2/project/{project_id}/admin/items/game/key/request/id/{item_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-get-codes-by-id.md): 通过游戏密钥ID获取指定数量的密钥。

### 获取密钥

 - [GET /v2/project/{project_id}/admin/items/game/key/request/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-get-codes-by-sku.md): 通过游戏密钥SKU获取指定数量的密钥。

### 通过ID上传密钥

 - [POST /v2/project/{project_id}/admin/items/game/key/upload/id/{item_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-upload-codes-by-id.md): 按游戏密钥ID上传密钥。

### 获取密钥加载会话信息

 - [GET /v2/project/{project_id}/admin/items/game/key/upload/session/{session_id}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-get-codes-session.md): 获取密钥加载会话信息。

### 上传密钥

 - [POST /v2/project/{project_id}/admin/items/game/key/upload/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-upload-codes-by-sku.md): 按游戏密钥SKU上传密钥。

### 按SKU删除游戏

 - [DELETE /v2/project/{project_id}/admin/items/game/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-delete-game-by-sku.md): 根据SKU删除项目中的游戏。

### 获取游戏（管理）

 - [GET /v2/project/{project_id}/admin/items/game/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-get-game-by-sku.md): 获取游戏以进行管理。
游戏由用户可以购买的游戏密钥组成。

注意不要使用此端点来构建商店目录。

### 按SKU更新游戏

 - [PUT /v2/project/{project_id}/admin/items/game/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/game-keys-admin/admin-update-game-by-sku.md): 根据SKU更新项目中的游戏。

## 管理

### 获取捆绑包列表

 - [GET /v2/project/{project_id}/admin/items/bundle](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-get-bundle-list.md): 获取项目中的捆绑包列表以进行管理。

注意不要使用此端点来构建商店目录。

### 创建捆绑包

 - [POST /v2/project/{project_id}/admin/items/bundle](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-create-bundle.md): 创建捆绑包。

### 按指定组的外部ID获取捆绑包列表

 - [GET /v2/project/{project_id}/admin/items/bundle/group/external_id/{external_id}](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-get-bundle-list-in-group-by-external-id.md): 获取组中的捆绑包列表以进行管理。

注意不要使用此端点来构建商店目录。

### 按指定组ID获取捆绑包列表

 - [GET /v2/project/{project_id}/admin/items/bundle/group/id/{group_id}](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-get-bundle-list-in-group-by-id.md): 获取组中的捆绑包列表以进行管理。

注意不要使用此端点来构建商店目录。

### 删除捆绑包

 - [DELETE /v2/project/{project_id}/admin/items/bundle/sku/{sku}](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-delete-bundle.md): 删除捆绑包。

### 获取捆绑包

 - [GET /v2/project/{project_id}/admin/items/bundle/sku/{sku}](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-get-bundle.md): 获取项目中的捆绑包以进行管理。

注意不要使用此端点来构建商店目录。

### 更新捆绑包

 - [PUT /v2/project/{project_id}/admin/items/bundle/sku/{sku}](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-update-bundle.md): 更新捆绑包。

### 在目录中隐藏捆绑包

 - [PUT /v2/project/{project_id}/admin/items/bundle/sku/{sku}/hide](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-hide-bundle.md): 在目录中隐藏捆绑包。

### 在目录中显示捆绑包

 - [PUT /v2/project/{project_id}/admin/items/bundle/sku/{sku}/show](https://developers.xsolla.com/zh/api/catalog/bundles-admin/admin-show-bundle.md): 在目录中显示捆绑包。

## 目录

### 获取捆绑包列表

 - [GET /v2/project/{project_id}/items/bundle](https://developers.xsolla.com/zh/api/catalog/bundles-catalog/get-bundle-list.md): 获取用于构建目录的捆绑包列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 获取指定组的捆绑包列表

 - [GET /v2/project/{project_id}/items/bundle/group/{external_id}](https://developers.xsolla.com/zh/api/catalog/bundles-catalog/get-bundle-list-in-group.md): 获取组内的捆绑包列表以构建目录。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 获取指定的捆绑包

 - [GET /v2/project/{project_id}/items/bundle/sku/{sku}](https://developers.xsolla.com/zh/api/catalog/bundles-catalog/get-bundle.md): 获取指定的捆绑包。

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

## 购物车（客户端侧）

### 获取当前用户的购物车

 - [GET /v2/project/{project_id}/cart](https://developers.xsolla.com/zh/api/catalog/cart-client-side/get-user-cart.md): 返回当前用户的购物车。

### 从当前购物车中删除所有购物车商品

 - [PUT /v2/project/{project_id}/cart/clear](https://developers.xsolla.com/zh/api/catalog/cart-client-side/cart-clear.md): 删除所有购物车商品。

### 在购物车里添加商品

 - [PUT /v2/project/{project_id}/cart/fill](https://developers.xsolla.com/zh/api/catalog/cart-client-side/cart-fill.md): 在购物车里添加商品。如果购物车中已有具有相同SKU的商品，则现有商品将被传入的值替换。

### 从当前购物车中删除购物车商品

 - [DELETE /v2/project/{project_id}/cart/item/{item_sku}](https://developers.xsolla.com/zh/api/catalog/cart-client-side/delete-item.md): 从购物车中删除一个商品。

### 更新当前购物车的商品

 - [PUT /v2/project/{project_id}/cart/item/{item_sku}](https://developers.xsolla.com/zh/api/catalog/cart-client-side/put-item.md): 更新现有的购物车商品或在购物车中创建商品。

### 按购物车ID获取购物车

 - [GET /v2/project/{project_id}/cart/{cart_id}](https://developers.xsolla.com/zh/api/catalog/cart-client-side/get-cart-by-id.md): 按购物车ID返回用户的购物车。

### 按购物车ID删除所有购物车商品

 - [PUT /v2/project/{project_id}/cart/{cart_id}/clear](https://developers.xsolla.com/zh/api/catalog/cart-client-side/cart-clear-by-id.md): 删除所有购物车商品。

### 在指定购物车里添加商品

 - [PUT /v2/project/{project_id}/cart/{cart_id}/fill](https://developers.xsolla.com/zh/api/catalog/cart-client-side/cart-fill-by-id.md): 在指定购物车里添加商品。如果购物车中已有具有相同SKU的商品，则现有商品位置将被传入的值替换。

### 按购物车ID删除购物车商品

 - [DELETE /v2/project/{project_id}/cart/{cart_id}/item/{item_sku}](https://developers.xsolla.com/zh/api/catalog/cart-client-side/delete-item-by-cart-id.md): 从购物车中删除一个商品。

### 按购物车ID更新购物车商品

 - [PUT /v2/project/{project_id}/cart/{cart_id}/item/{item_sku}](https://developers.xsolla.com/zh/api/catalog/cart-client-side/put-item-by-cart-id.md): 更新现有的购物车商品或在购物车中创建商品。

## 购物车（服务器侧）

### 在购物车里添加商品

 - [PUT /v2/admin/project/{project_id}/cart/fill](https://developers.xsolla.com/zh/api/catalog/cart-server-side/admin-cart-fill.md): 在当前购物车里添加商品。如果购物车中已有具有相同SKU的商品，则现有商品将被传入的值替换。

### 按购物车ID在购物车里添加商品

 - [PUT /v2/admin/project/{project_id}/cart/{cart_id}/fill](https://developers.xsolla.com/zh/api/catalog/cart-server-side/admin-fill-cart-by-id.md): 通过购物车ID在购物车里添加商品。如果购物车中已有具有相同SKU的商品，则现有商品将被传入的值替换。

## 支付（客户端）

### 使用当前购物车中的所有商品创建订单

 - [POST /v2/project/{project_id}/payment/cart](https://developers.xsolla.com/zh/api/catalog/payment-client-side/create-order.md): 用于客户端到服务器的集成。使用购物车中的所有商品创建订单并为其生成支付令牌。创建的订单得到new订单状态。

客户端IP用于确定用户所在的国家/地区，然后用于为订单应用相应的货币和可用的支付方式。

要在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token} ，其中{token}是收到的令牌。

如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token={token}。

注：由于此方法使用IP来确定用户所在的国家/地区并为订单选择货币，因此必须从客户端而不是从服务器端使用此方法。从服务器端使用此方法可能会导致货币判断错误并影响支付中心中可用的支付方式。

### 使用特定购物车中的所有商品创建订单

 - [POST /v2/project/{project_id}/payment/cart/{cart_id}](https://developers.xsolla.com/zh/api/catalog/payment-client-side/create-order-by-cart-id.md): 用于客户端到服务器的集成。使用指定购物车中的所有商品创建订单并为其生成支付令牌。创建的订单得到new订单状态。

客户端IP用于确定用户所在的国家/地区，然后用于为订单应用相应的货币和可用的支付方式。

要在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token} ，其中{token}是收到的令牌。

如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token={token}。

注：由于此方法使用IP来确定用户所在的国家/地区并为订单选择货币，因此必须从客户端而不是从服务器端使用此方法。从服务器端使用此方法可能会导致货币判断错误并影响支付中心中可用的支付方式。

### 使用指定商品创建订单

 - [POST /v2/project/{project_id}/payment/item/{item_sku}](https://developers.xsolla.com/zh/api/catalog/payment-client-side/create-order-with-item.md): 用于客户端到服务器的集成。使用指定商品创建订单并为其生成支付令牌。创建的订单得到new订单状态。

客户端IP用于确定用户所在的国家/地区，然后用于为订单应用相应的货币和可用的支付方式。

要在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token} ，其中{token}是收到的令牌。

如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token={token}。

注：由于此方法使用IP来确定用户所在的国家/地区并为订单选择货币，因此必须从客户端而不是从服务器端使用此方法。从服务器端使用此方法可能会导致货币判断错误并影响支付中心中可用的支付方式。

## 支付（服务器端）

### 为购买创建支付令牌

 - [POST /v3/project/{project_id}/admin/payment/token](https://developers.xsolla.com/zh/api/catalog/payment-server-side/admin-create-payment-token.md): 为其生成订单和支付令牌。订单根据请求正文中传递的商品生成。

要在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token}，其中{token}是收到的令牌。

如仅进行测试，请使用此URL：https://sandbox-secure.xsolla.com/paystation4/?token={token}。

注意

user.country.value参数用于选择订单的货币。如果用户的国家/地区未知，
请在X-User-Ip头中提供用户的IP作为替代方案。必须至少提供两者中的一个此方法才能正常工作。所选货币用于支付中心中的付款方式。

## 订单

### 获取订单

 - [GET /v2/project/{project_id}/order/{order_id}](https://developers.xsolla.com/zh/api/catalog/order/get-order.md): 检索指定的订单。

### 获取指定时间段的订单列表

 - [POST /v3/project/{project_id}/admin/order/search](https://developers.xsolla.com/zh/api/catalog/order/admin-order-search.md): 检索订单列表，按最早到最晚创建日期排列。

## 免费商品

### 使用免费购物车创建订单

 - [POST /v2/project/{project_id}/free/cart](https://developers.xsolla.com/zh/api/catalog/free-item/create-free-order.md): 使用免费购物车中的所有商品创建一个订单。创建的订单将具有done的订单状态。

### 使用指定免费购物车创建订单

 - [POST /v2/project/{project_id}/free/cart/{cart_id}](https://developers.xsolla.com/zh/api/catalog/free-item/create-free-order-by-cart-id.md): 使用指定免费购物车中的所有商品创建一个订单。创建的订单将具有done的订单状态。

### 使用指定免费商品创建订单

 - [POST /v2/project/{project_id}/free/item/{item_sku}](https://developers.xsolla.com/zh/api/catalog/free-item/create-free-order-with-item.md): 使用指定免费商品创建订单。创建的订单将具有done的订单状态。

## 管理

### 刷新指定用户的所有购买限制

 - [DELETE /v2/project/{project_id}/admin/user/limit/item/all](https://developers.xsolla.com/zh/api/catalog/user-limits-admin/reset-all-user-items-limit.md): 刷新指定用户所有商品的所有购买次数限制，以便他们可以再次购买这些商品。

用户限制API允许您限量销售商品。要配置购买限制，请前往所需商品类型模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

### 减少指定用户可购的商品数量

 - [DELETE /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/user-limits-admin/remove-user-item-limit.md): 减少指定用户在应用的限制范围内可购的剩余商品数量。

用户限制API允许您限量销售商品。要配置购买限制，请前往所需商品类型模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

### 获取指定用户可购的商品数量

 - [GET /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/user-limits-admin/get-user-item-limit.md): 获取指定用户在应用的限制范围内可购的剩余商品数量。

用户限制API允许您限量销售商品。要配置购买限制，请前往所需商品类型模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

### 增加指定用户可购的商品数量

 - [POST /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/user-limits-admin/add-user-item-limit.md): 增加指定用户在应用的限制范围内可购的剩余商品数量。

用户限制API允许您限量销售商品。要配置购买限制，请前往所需商品类型模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

### 设置指定用户可购的商品数量

 - [PUT /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/user-limits-admin/set-user-item-limit.md): 在增加或减少次数后设置指定用户在应用的限制范围内可购的商品数量

用户限制API允许您限量销售商品。要配置购买限制，请前往所需商品类型模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

### 刷新购买限制

 - [DELETE /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}/all](https://developers.xsolla.com/zh/api/catalog/user-limits-admin/reset-user-item-limit.md): 刷新商品的购买限制，以便用户可以再次购买。如果user参数为null，此调用会为所有用户刷新此限制。

用户限制API允许您限量销售商品。要配置购买限制，请前往所需商品类型模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

## 管理

### 获取商品导入状态

 - [GET /v1/admin/projects/{project_id}/connectors/import_items/import/status](https://developers.xsolla.com/zh/api/catalog/connector-admin/get-items-import-status.md): 检索将商品导入项目的进度信息。此API调用检索通过API或发布商帐户执行的最后一次导入的数据。

### 通过JSON文件导入商品

 - [POST /v1/projects/{project_id}/import/from_external_file](https://developers.xsolla.com/zh/api/catalog/connector-admin/import-items-from-external-file.md): 通过指定的URL从JSON文件将商品导入商店。关于从JSON文件导入的更多信息，请参阅文档。

## Webhook

### 获取Webhook设置信息

 - [GET /v2/project/{project_id}/admin/webhook](https://developers.xsolla.com/zh/api/catalog/common-webhooks/get-webhook.md): 获取商店中的Webhook设置信息。
要了解详细信息，请参阅Webhook文档。

### 更新Webhook设置信息

 - [PUT /v2/project/{project_id}/admin/webhook](https://developers.xsolla.com/zh/api/catalog/common-webhooks/update-webhook.md): 更新商店中的Webhook设置信息。
要了解详细信息，请参阅Webhook文档。

## 预订

### 移除商品预订数量限制

 - [DELETE /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/common-pre-orders/remove-pre-order-limit.md): 取消商品的预订数量限制。

预订限制API允许限量销售商品。如要配置预订本身，请前往所需商品模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

此端点的别名：
* /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}

### 获取商品预订限制的信息

 - [GET /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/common-pre-orders/get-pre-order-limit.md): 获取商品的预订数量限制。

预订限制API允许限量销售商品。如要配置预订本身，请前往所需商品模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

此端点的别名：
* /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}

### 添加商品预订数量限制

 - [POST /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/common-pre-orders/add-pre-order-limit.md): 添加商品的预订数量限制。

预订限制API允许限量销售商品。如要配置预订本身，请前往所需商品模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

此端点的别名：
* /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}

### 设置商品预订数量限制

 - [PUT /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}](https://developers.xsolla.com/zh/api/catalog/common-pre-orders/set-pre-order-limit.md): 设置商品的预订数量限制。

预订限制API允许限量销售商品。如要配置预订本身，请前往所需商品模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

此端点的别名：
* /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}

### 移除所有商品预订数量限制

 - [DELETE /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}/all](https://developers.xsolla.com/zh/api/catalog/common-pre-orders/remove-all-pre-order-limit.md): 取消商品的所有预订数量限制。

预订限制API允许限量销售商品。如要配置预订本身，请前往所需商品模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

此端点的别名：
* /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}/all

### 切换商品的预订限制

 - [PUT /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}/toggle](https://developers.xsolla.com/zh/api/catalog/common-pre-orders/toggle-pre-order-limit.md): 启用/禁用商品的预订数量限制。

预订限制API允许限量销售商品。如要配置预订本身，请前往所需商品模块的管理部分：
* 游戏密钥
* 虚拟物品和货币
* 捆绑包

此端点的别名：
* /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}/toggle

## 商户

### 获取项目

 - [GET /v2/merchant/{merchant_id}/projects](https://developers.xsolla.com/zh/api/catalog/common-merchant/get-projects.md): 获取商户项目列表。


  注意此API调用不包含project_id路径参数，所以需要使用在公司所有项目中都有效的API密钥来设置授权。

## 目录

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

### 获取可售商品列表

 - [GET /v2/project/{project_id}/items](https://developers.xsolla.com/zh/api/catalog/common-catalog/get-sellable-items.md): 获取用于构建目录的可售商品列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 按指定组获取可售商品列表

 - [GET /v2/project/{project_id}/items/group/{external_id}](https://developers.xsolla.com/zh/api/catalog/common-catalog/get-sellable-items-group.md): 从指定组获取用于构建目录的可售商品列表。

注意：所有项目对于可以在响应中获得的商品数量均都限制。默认值和最大值是每个响应50项。要逐页获取更多数据，请使用limit和offset字段。  注：使用商品目录API调用无需授权，但若需获取个性化目录，必须在Authorization头中传入用户JWT。

### 按ID获取可售商品

 - [GET /v2/project/{project_id}/items/id/{item_id}](https://developers.xsolla.com/zh/api/catalog/common-catalog/get-sellable-item-by-id.md): 按ID获取可售商品。
注：此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。

### 按SKU获取可售商品

 - [GET /v2/project/{project_id}/items/sku/{sku}](https://developers.xsolla.com/zh/api/catalog/common-catalog/get-sellable-item-by-sku.md): 按SKU获取用于构建目录的可售商品。
注：此端点无需授权即可访问，返回通用数据。但是授权后可以通过用户详细信息来丰富响应，获得个性化结果，例如适用的用户限制和促销活动等。

## 通用区域

### 获取区域列表

 - [GET /v2/project/{project_id}/admin/region](https://developers.xsolla.com/zh/api/catalog/common-regions/admin-get-regions.md): 获取区域列表。

可使用区域来管理区域限制。

### 创建区域

 - [POST /v2/project/{project_id}/admin/region](https://developers.xsolla.com/zh/api/catalog/common-regions/admin-create-region.md): 创建区域。

可使用区域来管理区域限制。

### 删除区域

 - [DELETE /v2/project/{project_id}/admin/region/{region_id}](https://developers.xsolla.com/zh/api/catalog/common-regions/admin-delete-region.md): 删除特定区域。

### 获取区域

 - [GET /v2/project/{project_id}/admin/region/{region_id}](https://developers.xsolla.com/zh/api/catalog/common-regions/admin-get-region.md): 获取特定区域。

可使用区域来管理区域限制。

### 更新区域

 - [PUT /v2/project/{project_id}/admin/region/{region_id}](https://developers.xsolla.com/zh/api/catalog/common-regions/admin-update-region.md): 更新特定区域。

可使用区域来管理区域限制。

## 管理

### 获取属性列表（管理）

 - [GET /v2/project/{project_id}/admin/attribute](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-get-attribute-list.md): 从项目中获取用于管理的属性列表。

### 创建属性

 - [POST /v2/project/{project_id}/admin/attribute](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-create-attribute.md): 创建一个属性。

### 删除属性

 - [DELETE /v2/project/{project_id}/admin/attribute/{external_id}](https://developers.xsolla.com/zh/api/catalog/attribute-admin/delete-attribute.md): 删除属性。
注意删除属性后，其所有数据及与商品的关联关系将被移除。

### 获取指定属性

 - [GET /v2/project/{project_id}/admin/attribute/{external_id}](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-get-attribute.md): 获取指定的属性。

### 更新属性

 - [PUT /v2/project/{project_id}/admin/attribute/{external_id}](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-update-attribute.md): 更新属性。

### 删除属性的所有值

 - [DELETE /v2/project/{project_id}/admin/attribute/{external_id}/value](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-delete-all-attribute-value.md): 删除该属性的所有值。
注意删除属性值后，该属性与商品之间的所有关联关系将被移除。如需更改商品的属性值，请使用更新属性值API调用，而不是删除该值再创建新值。

### 创建属性值

 - [POST /v2/project/{project_id}/admin/attribute/{external_id}/value](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-create-attribute-value.md): 创建一个属性值。

注意：所有项目对属性值的数量都有限制。默认值和最大值为 每个属性20个值。

### 删除属性值

 - [DELETE /v2/project/{project_id}/admin/attribute/{external_id}/value/{value_external_id}](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-delete-attribute-value.md): 删除属性值。
注意删除属性值后，该属性与商品之间的所有关联关系将被移除。如需更改商品的属性值，请使用更新属性值API调用，而不是删除该值再创建新值。

### 更新属性值

 - [PUT /v2/project/{project_id}/admin/attribute/{external_id}/value/{value_external_id}](https://developers.xsolla.com/zh/api/catalog/attribute-admin/admin-update-attribute-value.md): 更新属性值。