# 商品目录API # 概述 {% #overview %} - **版本：** 2.0.0 - **服务器：** `https://store.xsolla.com/api` - [通过电子邮件联系我们](mailto:integration@xsolla.com) - **联系网址：** https://xsolla.com/ - **所需TLS版本：** 1.2 商品目录API可用于在艾克索拉侧配置游戏内购商品目录，并在您的商店中向用户展示该商品目录。 该API可用于管理以下商品目录实体： * **虚拟物品** — 武器、皮肤、加成道具等游戏内物品。 * **虚拟货币** — 用于购买虚拟物品的虚拟资金。 * **虚拟货币套餐** — 预定义的虚拟货币捆绑包。 * **捆绑包** — 将虚拟物品、货币或游戏Key组合后作为单个SKU销售的组合包。 * **游戏Key** — 通过Steam等平台或其他DRM提供商分发的游戏和DLC密钥。 * **组** — 用于在商品目录中组织和排序商品的逻辑分组。 ## API调用 {% #api-calls %} 该API分为以下组别： * **Admin** — 用于创建、更新、删除和配置商品目录中的商品及分组的调用。通过[基本访问身份认证](https://developers.xsolla.com/zh/payment-ui-and-flow/payment-ui/how-to-get-payment-token/#payments_solution_get_user_auth_token_basic_auth)方式进行身份认证，需使用您的商户或项目凭据。不适用于商店前端调用。 * **Catalog** — 用于检索商品并构建面向最终用户的自定义商店前端。专为高负载场景设计。支持可选的用户JWT授权，可返回个性化数据，例如用户限购额度和当前进行中的促销活动。 # 身份认证 {% #authentication %} API调用需要以用户身份或项目身份进行身份认证。使用的身份认证方案见各调用描述中的**安全性**部分。 ## 使用用户JWT进行身份认证 {% #authentication-using-users-jwt %} 当请求从浏览器、移动应用或游戏发送时，使用用户JWT身份认证。默认情况下，应用`XsollaLoginUserJWT`方案。有关如何创建令牌的详细信息，请参阅[艾克索拉登录管理器API文档](/zh/api/login/authentication-schemes#getting-user-token)。 令牌通过`Authorization`请求头按以下格式传递：`Authorization: Bearer `，其中``为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。 或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。 ## 基本HTTP身份认证 {% #basic-http-authentication %} 基本HTTP身份认证用于服务器到服务器交互，即API调用直接从您的服务器发送，而不是从用户的浏览器或移动应用发送。通常使用带有[API密钥](/zh/api/getting-started/#api_keys_overview)的HTTP Basic身份认证。
注：

API密钥属于机密信息，不得在客户端应用中存储或使用。
使用基本服务器侧身份认证时，所有API请求都必须包含以下请求头： - 对于`basicAuth` — `Authorization: Basic `，其中`your_authorization_basic_key`是以Base64编码的`project_id:api_key`对 - 对于`basicMerchantAuth` — `Authorization: Basic `，其中`your_authorization_basic_key`是以Base64编码的`merchant_id:api_key`对 您可以在[发布商帐户](https://publisher.xsolla.com/)中找到参数值： - `merchant_id`显示在： - **公司设置 > 公司**中。 - 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。 - `project_id`显示在： - 发布商帐户中项目名称旁边。 - 发布商帐户中项目页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com//projects/`。 - `api_key`仅在创建时在发布商帐户中显示，必须在己侧安全存储。您可以在以下部分创建API密钥： - [公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key) - [项目设置 > API密钥](https://publisher.xsolla.com/0/projects/0/edit/api_key)
提示

如果所需的API调用不包含project_id路径参数，请使用对公司所有项目均有效的API密钥进行授权。
有关使用API密钥的更多信息，请参阅[API参考](/zh/api/getting-started/#api_keys_overview)。 ## 支持访客访问的身份认证 {% #authentication-with-guest-access-support %} `AuthForCart`身份认证方案用于购物车购买，支持两种模式： 1. **使用用户JWT进行身份认证。** 令牌通过`Authorization`请求头按以下格式传递：`Authorization: Bearer `，其中``是用户令牌。该令牌用于识别用户，并提供对个性化数据的访问权限。 或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。 2. **不带Authorization请求头的简化模式。** 此模式仅适用于未完成身份认证的用户，且仅可用于[游戏Key销售](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)请求中不使用令牌，而必须包含以下请求头： - `x-unauthorized-id`，值为请求ID - `x-user`，值为使用Base64编码的用户电子邮件地址 ## 实用链接 {% #authentication-useful-links %} - [按交互模型划分的API调用](/zh/api/getting-started/#api_interaction_model) - [接口类型](/zh/api/getting-started/#api_endpoint_types) - [错误处理](/zh/api/getting-started/#api_errors_handling) - [API密钥](/zh/api/getting-started/#api_keys_overview) - [Webhook](/zh/webhooks/overview) # 核心实体结构 {% #core-entity-structure %} 所有类型的商品（虚拟物品、捆绑包、虚拟货币和密钥）都使用类似的数据结构。了解基本结构有助于简化API使用，并帮助您更轻松地查阅文档。
注：

部分调用可能包含其他字段，但这些字段不会改变基本结构。
**标识信息** - `merchant_id` — [发布商帐户](https://publisher.xsolla.com/)中的公司ID - `project_id` — 发布商帐户中的项目ID - `sku` — 商品SKU，在项目内唯一 **商店显示** - `name` — 商品名称 - `description` — 商品描述 - `image_url` — 图片URL - `is_enabled` — 商品可用性 - `is_show_in_store` — 商品是否显示在商品目录中 有关在商品目录中管理商品可用性的更多信息，请参阅[文档](/zh/items-catalog/catalog-features/items-availability/)。 **组织方式** - `type` — 商品类型，例如虚拟物品（`virtual_item`）或捆绑包（`bundle`） - `groups` — 商品所属的组 - `order` — 在商品目录中的显示顺序 **销售条件** - `prices` — 以真实货币或虚拟货币表示的价格 - `limits` — 购买限制 - `periods` — 可用时间段 - `regions` — 区域限制 **核心实体结构示例：** ```json { "attributes": [], "bundle_type": "virtual_currency_package", "content": [ { "description": { "en": "Main in-game currency" }, "image_url": "https://.../image.png", "name": { "en": "Crystals", "de": "Kristalle" }, "quantity": 500, "sku": "com.xsolla.crystal_2", "type": "virtual_currency" } ], "description": { "en": "Crystals x500" }, "groups": [], "image_url": "https://.../image.png", "is_enabled": true, "is_free": false, "is_show_in_store": true, "limits": { "per_item": null, "per_user": null, "recurrent_schedule": null }, "long_description": null, "media_list": [], "name": { "en": "Medium crystal pack" }, "order": 1, "periods": [ { "date_from": null, "date_until": "2020-08-11T20:00:00+03:00" } ], "prices": [ { "amount": 20, "country_iso": "US", "currency": "USD", "is_default": true, "is_enabled": true } ], "regions": [], "sku": "com.xsolla.crystal_pack_2", "type": "bundle", "vc_prices": [] } ``` # 基本购买流程 {% #basic-purchase-flow %} 艾克索拉API可用于实现游戏内购商店逻辑，包括获取商品目录、管理购物车、创建订单以及跟踪订单状态。根据集成场景，API调用分为**管理**和**商品目录**子部分，使用不同的[身份认证方案](/zh/api/catalog/authentication)。 以下示例展示了从创建商品到完成购买的商店设置和运营基本流程。 ## 创建商品和组（管理） {% #create-items-and-groups-admin %} 为您的商店创建商品目录，例如虚拟物品、捆绑包或虚拟货币。 API调用示例： - [创建虚拟物品](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-item) - [创建捆绑包](/zh/api/catalog/bundles-admin/admin-create-bundle) - [创建虚拟货币](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency) ## 设置促销、奖励链和限制（管理） {% #set-up-promotions-chains-and-limits-admin %} 配置用户拉新和赢利工具，例如折扣、赠品、每日奖励或优惠链。 API调用示例： - [创建买赠促销活动](/zh/api/liveops/promotions-bonuses/create-bonus-promotion) - [创建每日奖励](/zh/api/liveops/daily-chain-admin/admin-create-daily-chain) - [创建唯一商品目录优惠促销活动](/zh/api/liveops/promotions-unique-catalog-offers/admin-create-unique-catalog-offer) ## 获取商品信息（客户端） {% #get-item-information-client %} 在您的应用程序中配置商品显示。
提示

请勿使用管理子部分中的API调用来构建用户商品目录。这些API调用存在速率限制，并不适用于用户流量。

API调用示例： - [获取虚拟物品列表](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items) - [获取商品组列表](/zh/api/catalog/virtual-items-currency-catalog/get-item-groups) - [获取捆绑包列表](/zh/api/catalog/bundles-catalog/get-bundle-list) - [获取可售商品列表](/zh/api/catalog/common-catalog/get-sellable-items)
注：

默认情况下，商品目录API调用会返回请求时商店中当前可用的商品。如需获取尚未可用或已不再可用的商品，请在商品目录请求中包含参数"show_inactive_time_limited_items": 1。
## 销售商品 {% #sell-items %} 您可以使用以下方法销售商品： - 快速购买 — 多次销售同一SKU。 - 购物车购买 — 用户可在同一订单中向购物车添加商品、移除商品并更新数量。 如果商品使用虚拟货币而非真实货币购买，请使用[创建包含指定商品的订单](/zh/api/catalog/virtual-payment/create-order-with-item-for-virtual-currency) API调用。由于扣款会在执行API调用时处理，因此无需支付UI。 如需购买免费商品，请使用[使用指定商品创建订单](/zh/api/catalog/free-item/create-free-order-with-item) API调用或[使用免费购物车创建订单](/zh/api/catalog/free-item/create-free-order) API调用。无需支付UI — 订单会立即设置为done状态。 ### 快速购买 {% #fast-purchase %} 使用客户端API调用[使用指定商品创建订单](/zh/api/catalog/payment-client-side/create-order-with-item)。该调用会返回用于打开支付UI的令牌。
注：

用户只能在支付UI中查看折扣信息。不支持兑换码。
### 购物车购买 {% #cart-purchase %} 可以在客户端或服务器侧设置购物车并完成购买。 **在客户端设置和购买购物车商品** 您需要自行实现添加和移除商品的逻辑。在调用用于设置购物车的API之前，您无法获知哪些促销活动会应用于本次购买。这意味着您无法提前获知总费用以及添加的赠品的详细信息。 实现以下购物车逻辑： 1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/shop-builder/operation/cart-fill/) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。 2. 根据用户操作更新购物车内容： - 如需添加商品或更改商品数量，请使用[按购物车ID更新购物车商品](/zh/api/shop-builder/operation/put-item-by-cart-id/) API调用。 - 如需移除商品，请使用[按购物车ID删除购物车商品](/zh/api/shop-builder/operation/delete-item-by-cart-id/) API调用。
注：

如需获取购物车的当前状态，请使用“获取当前用户的购物车”API调用。
3. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用返回订单ID和支付令牌。新创建的订单默认设置为new状态。 **在服务器侧设置和购买购物车商品** 这种设置方式可能需要更长的购物车设置时间，因为每次更改购物车都必须伴随API调用。 实现以下购物车逻辑： 1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/catalog/cart-server-side) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。 2. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用会返回订单ID和支付令牌。新创建的订单默认设置为new状态。 ## 打开支付UI {% #open-payment-ui %} 使用返回的令牌在新窗口中打开支付UI。有关打开支付UI的其他方式，请参阅[文档](/zh/payment-ui-and-flow/payment-ui/how-to-open-payment-ui/#open_payment_ui)。 | 操作 | 接口 | |:--------------------------------|:--------------------------------------------------------------------------| | 在生产环境中打开。 | https://secure.xsolla.com/paystation4/?token={token} | | 在沙盒模式中打开。 | https://sandbox-secure.xsolla.com/paystation4/?token={token} |
注：

请在开发和测试期间使用沙盒模式。测试购买不会对真实帐户扣款。您可以使用测试银行卡。 完成第一笔真实支付后，严格的沙盒支付策略将生效。沙盒模式下的支付仅对[发布商帐户 > 公司设置 > 用户](https://publisher.xsolla.com/0/settings/users)中指定的用户可用。 只有在与艾克索拉签署许可协议后，才能使用真实货币购买虚拟货币和商品。如需签署协议，请在[发布商帐户](https://publisher.xsolla.com/)中前往**协议与税务 > 合同与协议**，填写协议表单并等待确认。协议审核最多可能需要3个工作日。
如需启用或禁用沙盒模式，请在快速购买和购物车购买请求中更改`sandbox`参数的值。沙盒模式默认关闭。 可能的订单状态： - `new` — 订单已创建 - `paid` — 已收到付款 - `done` — 商品已交付 - `canceled` — 订单已取消 - `expired` — 订单已过期 使用以下任一方式跟踪订单状态： - [您服务器上配置的Webhook](/zh/virtual-goods/own-ui/server-side-token-generation/set-up-order-tracking/#payments_integration_order_tracking) - [短轮询](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/#guides_shop_builder_integrate_store_get_order_status_via_short_polling) - [WebSocket API](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/#guides_shop_builder_integrate_store_get_order_status_via_websocket_api) ## 实用链接 {% #basic-purchase-flow-useful-links %} - 身份认证 - [按交互模型划分的API调用](/zh/api/catalog/authentication) - [支付测试](/zh/dev-resources/testing/general-info/#general_overview) - [设置订单状态跟踪](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/?link=200-api#payments_integration_order_tracking) - [Webhook](/zh/webhooks/overview) - [速率限制](/zh/api/login/rate-limits) - [错误处理](/zh/api/getting-started/#api_errors_handling) - [API密钥](/zh/api/getting-started/#api_keys_overview) # 分页 {% #pagination %} 返回大量记录的API调用（例如构建商品目录时）会按页返回数据。分页是一种限制单个API响应中返回商品数量的机制，并允许您按顺序获取后续页面。 使用以下参数控制返回的商品数量： - `limit` — 每页商品数量 - `offset` — 页面中第一个商品的索引（从0开始编号） - `has_more` — 指示是否还有下一页 - `total_items_count` — 商品总数 请求示例： ``` GET /items?limit=20&offset=40 ``` 响应示例： ```json { "items": [...], "has_more": true, "total_items_count": 135 } ``` 建议发送后续请求，直到响应返回`has_more = false`。 # 日期和时间格式 {% #date-and-time-format %} 日期和时间值以[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)格式传递。 支持以下内容： - UTC偏移量 - 当商品显示没有时间限制时使用`null`值 - 部分字段使用的[Unix时间戳](https://www.unixtimestamp.com/)（以秒为单位） 格式：`YYYY-MM-DDTHH:MM:SS±HH:MM` 示例：`2026-03-16T10:00:00+03:00` # 本地化 {% #localization %} 艾克索拉支持对商品名称、描述等面向用户的字段进行本地化。本地化值以对象形式传递，其中语言代码作为键。支持的完整语言列表，请参阅[文档](/zh/doc/shop-builder/references/supported-languages/)。 **支持的字段** 可为以下参数指定本地化内容： - `name` - `description` - `long_description` **区域格式** 语言区域键可使用以下任一格式指定： - 两字母语言代码：`en`、`ru` - 五字母语言代码：`en-US`、`ru-RU`、`de-DE` **示例** 两字母语言代码示例： ```json { "name": { "en": "Starter Pack", "ru": "Стартовый набор" } } ``` 五字母语言代码示例： ```json { "description": { "en-US": "Premium bundle", "de-DE": "Premium-Paket" } } ``` # 国家/地区和货币确定 {% #country-and-currency-determination %} 用户所在国家/地区决定商品目录价格、支付货币以及支付界面中的可用支付方式。根据API调用的不同，国家/地区按以下方式确定：
  • 在客户端侧API调用中，国家/地区根据请求的IP地址确定。
  • 在服务器侧API调用中，国家/地区根据user.country.value参数的值或X-User-Ip标头中的用户IP地址确user.country.value参数为准。
注：

仅支持使用IPv4地址确定国家/地区。 传入IPv6地址可能会导致国家/地区和货币检测不正确。如果您使用服务器侧API调用且无法提供用户的IPv4地址，请在user.country.value参数中传入国家/地区。
# 错误响应格式 {% #error-response-format %} 如果发生错误，API会返回HTTP状态和JSON响应正文。商店相关错误的完整列表，请参阅[文档](/zh/dev-resources/references/errors/store-errors/)。 **响应示例：** ```json { "errorCode": 1102, "errorMessage": "Validation error", "statusCode": 422, "transactionId": "c9e1a..." } ``` - `errorCode` — 错误代码。 - `errorMessage` — 简短的错误描述。 - `statusCode` — HTTP响应状态。 - `transactionId` — 请求ID。仅在部分情况下返回。 - `errorMessageExtended` — 其他错误详情，例如请求参数。仅在某些情况下返回。 **扩展响应示例：** ```json { "errorCode": 7001, "errorMessage": "Chain not found", "errorMessageExtended": { "chain_id": "test_chain_id", "project_id": "test_project_id", "step_number": 2 }, "statusCode": 404 } ``` **常见HTTP状态代码** - `400` — 请求无效 - `401` — 身份认证错误 - `403` — 权限不足 - `404` — 资源未找到 - `422` — 验证错误 - `429` — 超出速率限制 **建议** - 结合HTTP状态和响应正文一起处理。 - 使用`errorCode`处理与应用程序逻辑相关的错误。 - 分析错误时，使用`transactionId`更快定位请求。 Version: 2.0.0 ## Servers ``` https://store.xsolla.com/api ``` ## Security ### basicAuth 服务器侧调用使用`basicAuth`身份认证方案。向API发送的所有请求都必须包含`Authorization: Basic `请求头，其中`your_authorization_basic_key`是根据Base64标准编码的`project_id:api_key`对。 如有需要，您可以使用`merchant_id`代替`project_id`。这不会影响功能。 前往[发布商帐户](https://publisher.xsolla.com/)查找参数值： * `merchant_id`显示在： * **公司设置 > 公司**部分 * 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。 * `api_key`仅会在创建时于发布商帐户中显示一次，必须由您在己侧保存。您可以在以下部分创建新密钥： * [公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key) * [项目设置 > API密钥](https://publisher.xsolla.com/0/projects/0/edit/api_key) {% html name="div" attrs={"class": "notice"} %} **提示** 如果所需的API调用不包含`project_id`路径参数，请使用对公司所有项目均有效的API密钥进行授权。 {% /html %} * `project_id`显示在： * 发布商帐户中项目名称旁边。 * 发布商帐户中项目页浏览器地址栏中的URL中。URL格式为：`https://publisher.xsolla.com//projects/`。 有关使用API密钥的更多信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。 Type: http Scheme: basic ### XsollaLoginUserJWT 客户端侧调用使用`XsollaLoginUserJWT`身份认证方案。请求须在`Authorization`请求头中包含用户JWT，格式为：Bearer ``。令牌用于识别用户并提供个性化数据访问权限。有关令牌创建方法，请参阅[艾克索拉登录管理器API文档](/zh/api/login/authentication-schemes#getting-user-token)。 或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。 Type: http Scheme: bearer Bearer Format: JWT ### AuthForCart `AuthForCart`身份认证方案用于购物车购买，支持两种模式： 1. 使用用户JWT进行身份认证。 令牌通过Authorization请求头按以下格式传递：`Authorization: Bearer `，其中``是用户令牌。该令牌用于识别用户，并提供对个性化数据的访问权限。 或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。 2. 不带`Authorization`请求头的简化模式。此模式仅适用于未完成身份认证的用户，且仅可用于[游戏Key销售](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)请求中不使用令牌，而必须包含以下请求头： * `x-unauthorized-id`，值为请求ID * `x-user`，值为使用Base64编码的用户电子邮件地址。 Type: http Scheme: bearer ### basicMerchantAuth 服务器侧调用使用`basicMerchantAuth`身份认证方案。向API发送的所有请求都必须包含`Authorization: Basic `请求头，其中`your_authorization_basic_key`是根据Base64标准编码的`merchant_id:api_key`对。 前往[发布商帐户](https://publisher.xsolla.com/)查找参数值： * `merchant_id`显示在： * **公司设置 > 公司**部分 * 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。 * `api_key`仅会在创建时于发布商帐户中显示一次，必须由您在己侧保存。您可以在[公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key)部分创建新密钥。 有关使用API密钥的更多信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。 Type: http Scheme: basic ## Download OpenAPI description [商品目录API](https://xsolla.redocly.app/_bundle/@l10n/zh/api/catalog/index.yaml) ## 管理 ### 获取虚拟物品列表 - [GET /v2/project/{project_id}/admin/items/virtual_items](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list.md): 获取项目中的虚拟物品列表以进行管理。 注：请勿使用此接口来构建商店商品目录。 ### 创建虚拟物品 - [POST /v2/project/{project_id}/admin/items/virtual_items](https://xsolla.redocly.app/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://xsolla.redocly.app/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://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list-by-group-id.md): 获取组中的虚拟物品列表以进行管理。 注：请勿使用此接口来构建商店商品目录。 ### 获取虚拟物品 - [GET /v2/project/{project_id}/admin/items/virtual_items/sku/{item_sku}](https://xsolla.redocly.app/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://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-update-virtual-item.md): 更新虚拟物品。 ### 删除虚拟物品 - [DELETE /v2/project/{project_id}/admin/items/virtual_items/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-delete-virtual-item.md): 删除虚拟物品。 ### 获取虚拟货币列表 - [GET /v2/project/{project_id}/admin/items/virtual_currency](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-currencies-list.md): 获取项目中的虚拟货币列表以进行管理。 注：请勿使用此接口来构建商店商品目录。 ### 创建虚拟货币 - [POST /v2/project/{project_id}/admin/items/virtual_currency](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency.md): 创建虚拟货币。 ### 获取虚拟货币 - [GET /v2/project/{project_id}/admin/items/virtual_currency/sku/{virtual_currency_sku}](https://xsolla.redocly.app/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://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency.md): 更新虚拟货币。 ### 删除虚拟货币 - [DELETE /v2/project/{project_id}/admin/items/virtual_currency/sku/{virtual_currency_sku}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-delete-virtual-currency.md): 删除虚拟货币。 ### 获取虚拟货币套餐列表（管理） - [GET /v2/project/{project_id}/admin/items/virtual_currency/package](https://xsolla.redocly.app/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://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency-package.md): 创建虚拟货币套餐。 ### 更新虚拟货币套餐 - [PUT /v2/project/{project_id}/admin/items/virtual_currency/package/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-update-virtual-currency-package.md): 更新虚拟货币套餐。 ### 删除虚拟货币套餐 - [DELETE /v2/project/{project_id}/admin/items/virtual_currency/package/sku/{item_sku}](https://xsolla.redocly.app/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://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-currency-package.md): 获取项目中的虚拟货币套餐以进行管理。 注：请勿使用此接口来构建商店商品目录。 ## 商品目录 ### 获取虚拟物品列表 - [GET /v2/project/{project_id}/items/virtual_items](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items.md): 获取用于构建商品目录的虚拟物品列表。 提示 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 另请参阅：用于客户端侧搜索或索引的 获取所有虚拟物品列表API调用。 ### 按SKU获取虚拟物品 - [GET /v2/project/{project_id}/items/virtual_items/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items-sku.md): 按SKU获取用于构建商品目录的虚拟物品。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 获取所有虚拟物品列表 - [GET /v2/project/{project_id}/items/virtual_items/all](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-all-virtual-items.md): 获取所有虚拟物品列表，用于客户端侧搜索。 提示 仅返回商品SKU、名称、组和描述。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 另请参阅：用于分页获取详细商品数据的获取虚拟物品列表API调用。 ### 获取虚拟货币列表 - [GET /v2/project/{project_id}/items/virtual_currency](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency.md): 获取用于构建商品目录的虚拟货币列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按SKU获取虚拟货币 - [GET /v2/project/{project_id}/items/virtual_currency/sku/{virtual_currency_sku}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-sku.md): 按SKU获取用于构建商品目录的虚拟货币。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 获取虚拟货币套餐列表 - [GET /v2/project/{project_id}/items/virtual_currency/package](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package.md): 获取用于构建商品目录的虚拟货币套餐列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按SKU获取虚拟货币套餐 - [GET /v2/project/{project_id}/items/virtual_currency/package/sku/{virtual_currency_package_sku}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package-sku.md): 按SKU获取用于构建商品目录的虚拟货币套餐。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按指定组获取商品列表 - [GET /v2/project/{project_id}/items/virtual_items/group/{external_id}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items-group.md): 从指定组获取商品列表以构建商品目录。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按指定组获取虚拟货币列表 - [GET /v2/project/{project_id}/items/virtual_currency/group/{external_id}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-group.md): 获取指定组中的虚拟货币列表，用于构建商品目录。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按指定组获取虚拟货币套餐列表 - [GET /v2/project/{project_id}/items/virtual_currency/package/group/{external_id}](https://xsolla.redocly.app/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package-group.md): 获取指定组中的虚拟货币套餐列表，用于构建商品目录。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ## 虚拟支付 ### 使用以虚拟货币购买的指定商品创建订单 - [POST /v2/project/{project_id}/payment/item/{item_sku}/virtual/{virtual_currency_sku}](https://xsolla.redocly.app/zh/api/catalog/virtual-payment/create-order-with-item-for-virtual-currency.md): 创建使用虚拟货币购买的商品订单。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ## 商品目录 ### 获取游戏列表 - [GET /v2/project/{project_id}/items/game](https://xsolla.redocly.app/zh/api/catalog/game-keys-catalog/get-games-list.md): 获取用于构建商品目录的游戏列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按指定组获取游戏列表 - [GET /v2/project/{project_id}/items/game/group/{external_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-catalog/get-games-group.md): 从指定组获取用于构建商品目录的游戏列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 获取商品目录中的游戏 - [GET /v2/project/{project_id}/items/game/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-catalog/get-game-by-sku.md): 获取用于商品目录的游戏。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 获取商品目录中的游戏Key - [GET /v2/project/{project_id}/items/game/key/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-catalog/get-game-key-by-sku.md): 获取用于商品目录的游戏Key。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按指定组获取游戏Key列表 - [GET /v2/project/{project_id}/items/game/key/group/{external_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-catalog/get-game-keys-group.md): 从指定组获取用于构建商品目录的游戏Key列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 获取DRM列表 - [GET /v2/project/{project_id}/items/game/drm](https://xsolla.redocly.app/zh/api/catalog/game-keys-catalog/get-drm-list.md): 获取可用DRM的列表。 ## 权益 ### 获取用户拥有的游戏列表 - [GET /v2/project/{project_id}/entitlement](https://xsolla.redocly.app/zh/api/catalog/game-keys-entitlement/get-user-games.md): 获取用户拥有的游戏列表。响应将包含指定用户拥有的一组游戏。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 通过客户端兑换游戏Key - [POST /v2/project/{project_id}/entitlement/redeem](https://xsolla.redocly.app/zh/api/catalog/game-keys-entitlement/redeem-game-pin-code.md): 根据提供的游戏Key授予权益。 提示 仅可为DRM free平台兑换游戏Key。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 授予权益（管理） - [POST /v2/project/{project_id}/admin/entitlement/grant](https://xsolla.redocly.app/zh/api/catalog/game-keys-entitlement/grant-entitlement-admin.md): 向用户授予权益。 注意：仅可授予DRM free平台的游戏Key或游戏。 ### 撤销权益（管理） - [POST /v2/project/{project_id}/admin/entitlement/revoke](https://xsolla.redocly.app/zh/api/catalog/game-keys-entitlement/revoke-entitlement-admin.md): 撤销用户的权益。 注意：仅可撤销DRM free平台的游戏Key或游戏。 ## 管理 ### 创建游戏 - [POST /v2/project/{project_id}/admin/items/game](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-create-game.md): 在项目中创建游戏。 ### 获取游戏列表（管理） - [GET /v2/project/{project_id}/admin/items/game](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-get-game-list.md): 获取项目中的游戏列表以进行管理。 游戏由可供用户购买的游戏Key组成。 注：请勿使用此接口来构建商店商品目录。 ### 获取游戏（管理） - [GET /v2/project/{project_id}/admin/items/game/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-get-game-by-sku.md): 获取游戏以进行管理。 游戏由可供用户购买的游戏Key组成。 注：请勿使用此接口来构建商店商品目录。 ### 按SKU更新游戏 - [PUT /v2/project/{project_id}/admin/items/game/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-update-game-by-sku.md): 根据SKU更新项目中的游戏。 ### 按SKU删除游戏 - [DELETE /v2/project/{project_id}/admin/items/game/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-delete-game-by-sku.md): 根据SKU删除项目中的游戏。 ### 通过ID获取游戏（管理） - [GET /v2/project/{project_id}/admin/items/game/id/{item_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-get-game-by-id.md): 获取游戏以进行管理。 游戏由可供用户购买的游戏Key组成。 注：请勿使用此接口来构建商店商品目录。 ### 通过ID更新游戏 - [PUT /v2/project/{project_id}/admin/items/game/id/{item_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-update-game-by-id.md): 通过ID更新项目中的游戏。 ### 通过ID删除游戏 - [DELETE /v2/project/{project_id}/admin/items/game/id/{item_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-delete-game-by-id.md): 根据ID删除项目中的游戏。 ### 上传游戏Key - [POST /v2/project/{project_id}/admin/items/game/key/upload/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-upload-codes-by-sku.md): 按游戏Key SKU上传游戏Key。 ### 按ID上传游戏Key - [POST /v2/project/{project_id}/admin/items/game/key/upload/id/{item_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-upload-codes-by-id.md): 按游戏Key ID上传游戏Key。 ### 获取游戏Key加载会话信息 - [GET /v2/project/{project_id}/admin/items/game/key/upload/session/{session_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-get-codes-session.md): 获取游戏Key加载会话信息。 ### 获取游戏Key - [GET /v2/project/{project_id}/admin/items/game/key/request/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-get-codes-by-sku.md): 按游戏Key SKU获取指定数量的游戏Key。 ### 按ID获取游戏Key - [GET /v2/project/{project_id}/admin/items/game/key/request/id/{item_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-get-codes-by-id.md): 按游戏Key ID获取指定数量的游戏Key。 ### 删除游戏Key - [DELETE /v2/project/{project_id}/admin/items/game/key/delete/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-delete-codes-by-sku.md): 按游戏Key SKU删除所有游戏Key。 ### 按ID删除游戏Key - [DELETE /v2/project/{project_id}/admin/items/game/key/delete/id/{item_id}](https://xsolla.redocly.app/zh/api/catalog/game-keys-admin/admin-delete-codes-by-id.md): 按游戏Key ID删除所有游戏Key。 ## 管理 ### 获取捆绑包列表 - [GET /v2/project/{project_id}/admin/items/bundle](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-get-bundle-list.md): 获取项目中的捆绑包列表以进行管理。 注：请勿使用此接口来构建商店商品目录。 ### 创建捆绑包 - [POST /v2/project/{project_id}/admin/items/bundle](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-create-bundle.md): 创建捆绑包，即作为一个单位销售的一组商品。捆绑包可以包含虚拟物品、虚拟货币套餐、游戏Key以及其他捆绑包。有关更多信息，请参阅捆绑包部分。 提示content数组中的所有商品都必须提前在您的项目中创建。如果指定的SKU不存在，系统将返回错误。 ### 按指定组ID获取捆绑包列表 - [GET /v2/project/{project_id}/admin/items/bundle/group/id/{group_id}](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-get-bundle-list-in-group-by-id.md): 获取组内捆绑包的列表以进行管理。 注：请勿使用此接口来构建商店商品目录。 ### 按指定组的外部ID获取捆绑包列表 - [GET /v2/project/{project_id}/admin/items/bundle/group/external_id/{external_id}](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-get-bundle-list-in-group-by-external-id.md): 获取组内捆绑包的列表以进行管理。 注：请勿使用此接口来构建商店商品目录。 ### 更新捆绑包 - [PUT /v2/project/{project_id}/admin/items/bundle/sku/{sku}](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-update-bundle.md): 更新捆绑包。此调用会完整替换该捆绑包——请在请求体中传入所有必填字段，而不仅是要更改的字段。有关更多信息，请参阅捆绑包部分。 提示content数组中的所有商品都必须提前在您的项目中创建。如果指定的SKU不存在，系统将返回错误。 ### 删除捆绑包 - [DELETE /v2/project/{project_id}/admin/items/bundle/sku/{sku}](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-delete-bundle.md): 删除捆绑包。 ### 获取捆绑包 - [GET /v2/project/{project_id}/admin/items/bundle/sku/{sku}](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-get-bundle.md): 获取项目中的捆绑包以进行管理。 注：请勿使用此接口来构建商店商品目录。 ### 在商品目录中显示捆绑包 - [PUT /v2/project/{project_id}/admin/items/bundle/sku/{sku}/show](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-show-bundle.md): 在商品目录中显示捆绑包。 ### 在商品目录中隐藏捆绑包 - [PUT /v2/project/{project_id}/admin/items/bundle/sku/{sku}/hide](https://xsolla.redocly.app/zh/api/catalog/bundles-admin/admin-hide-bundle.md): 在商品目录中隐藏捆绑包。 ## 商品目录 ### 获取捆绑包列表 - [GET /v2/project/{project_id}/items/bundle](https://xsolla.redocly.app/zh/api/catalog/bundles-catalog/get-bundle-list.md): 获取用于构建商品目录的捆绑包列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 获取指定的捆绑包 - [GET /v2/project/{project_id}/items/bundle/sku/{sku}](https://xsolla.redocly.app/zh/api/catalog/bundles-catalog/get-bundle.md): 获取指定的捆绑包。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 获取指定组的捆绑包列表 - [GET /v2/project/{project_id}/items/bundle/group/{external_id}](https://xsolla.redocly.app/zh/api/catalog/bundles-catalog/get-bundle-list-in-group.md): 获取组内的捆绑包列表以构建商品目录。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ## 购物车（客户端侧） 使用本部分中的调用在客户端侧管理购物车。 ### 按购物车ID获取购物车 - [GET /v2/project/{project_id}/cart/{cart_id}](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/get-cart-by-id.md): 按购物车ID返回用户的购物车。 ### 获取当前用户的购物车 - [GET /v2/project/{project_id}/cart](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/get-user-cart.md): 返回当前用户的购物车。 ### 按购物车ID删除所有购物车商品 - [PUT /v2/project/{project_id}/cart/{cart_id}/clear](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/cart-clear-by-id.md): 删除所有购物车商品。 ### 删除当前购物车中的所有商品 - [PUT /v2/project/{project_id}/cart/clear](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/cart-clear.md): 删除所有购物车商品。 ### 向购物车添加商品 - [PUT /v2/project/{project_id}/cart/fill](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/cart-fill.md): 向购物车添加商品。如果购物车中已有具有相同SKU的商品，则现有商品将被传入的值替换。 ### 向指定购物车添加商品 - [PUT /v2/project/{project_id}/cart/{cart_id}/fill](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/cart-fill-by-id.md): 向指定购物车添加商品。如果购物车中已有具有相同SKU的商品，则现有商品位置将被传入的值替换。 ### 按购物车ID更新购物车商品 - [PUT /v2/project/{project_id}/cart/{cart_id}/item/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/put-item-by-cart-id.md): 更新现有的购物车商品或在购物车中创建商品。 ### 按购物车ID删除购物车商品 - [DELETE /v2/project/{project_id}/cart/{cart_id}/item/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/delete-item-by-cart-id.md): 从购物车中移除商品。 ### 更新当前购物车的商品 - [PUT /v2/project/{project_id}/cart/item/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/put-item.md): 更新现有的购物车商品或在购物车中创建商品。 ### 删除当前购物车中的商品 - [DELETE /v2/project/{project_id}/cart/item/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/cart-client-side/delete-item.md): 从购物车中移除商品。 ## 购物车（服务器侧） 使用本部分中的调用在服务器侧管理购物车。 ### 向购物车添加商品 - [PUT /v2/admin/project/{project_id}/cart/fill](https://xsolla.redocly.app/zh/api/catalog/cart-server-side/admin-cart-fill.md): 向当前购物车添加商品。如果购物车中已有具有相同SKU的商品，则现有商品将被传入的值替换。 ### 按购物车ID向购物车添加商品 - [PUT /v2/admin/project/{project_id}/cart/{cart_id}/fill](https://xsolla.redocly.app/zh/api/catalog/cart-server-side/admin-fill-cart-by-id.md): 按购物车ID向购物车添加商品。如果购物车中已有具有相同SKU的商品，则现有商品将被传入的值替换。 ## 支付（客户端侧） 使用本部分中的调用在客户端侧创建支付令牌。 ### 创建包含指定购物车中所有商品的订单 - [POST /v2/project/{project_id}/payment/cart/{cart_id}](https://xsolla.redocly.app/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/cart](https://xsolla.redocly.app/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/item/{item_sku}](https://xsolla.redocly.app/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确定用户所在国家/地区，并为订单选择货币，因此请务必仅在客户端侧使用此方法，不要在服务器侧使用。从服务器侧使用此方法可能导致货币判断不准确，并影响支付收银台中可用的支付方式。 提示 此API调用使用用户JWT进行授权。 请在Authorization请求头中包含令牌，格式为：Bearer <user_JWT>。有关用户JWT的更多信息，请参阅此调用的安全性部分。 ## 支付（服务器侧） 使用本部分中的调用在服务器侧创建支付令牌。 ### 创建购买支付令牌 - [POST /v3/project/{project_id}/admin/payment/token](https://xsolla.redocly.app/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标头（如果国家/地区未知，则传入用户的IPv4地址）。传入的数据将用于确定支付货币。 不支持IPv6地址。所选货币将用于艾克索拉支付UI中的支付方式。 ## 订单 使用本部分中的调用获取订单信息。 ### 获取订单 - [GET /v2/project/{project_id}/order/{order_id}](https://xsolla.redocly.app/zh/api/catalog/order/get-order.md): 获取指定订单。 ### 获取指定时间段内的订单列表 - [POST /v3/project/{project_id}/admin/order/search](https://xsolla.redocly.app/zh/api/catalog/order/admin-order-search.md): 获取订单列表，并按创建日期从早到晚排列。 ## 免费商品 使用本部分中的调用向用户发放免费商品。 ### 创建免费购物车订单 - [POST /v2/project/{project_id}/free/cart](https://xsolla.redocly.app/zh/api/catalog/free-item/create-free-order.md): 创建包含免费购物车中所有商品的订单。创建后的订单状态将为done。 ### 创建指定免费购物车订单 - [POST /v2/project/{project_id}/free/cart/{cart_id}](https://xsolla.redocly.app/zh/api/catalog/free-item/create-free-order-by-cart-id.md): 创建包含指定免费购物车中所有商品的订单。创建后的订单状态将为done。 ### 创建包含指定免费商品的订单 - [POST /v2/project/{project_id}/free/item/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/free-item/create-free-order-with-item.md): 创建包含指定免费商品的订单。创建后的订单状态将为done。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ## 管理 ### 刷新指定用户的所有购买限制 - [DELETE /v2/project/{project_id}/admin/user/limit/item/all](https://xsolla.redocly.app/zh/api/catalog/user-limits-admin/reset-all-user-items-limit.md): 刷新指定用户在所有商品上的全部购买次数限制，使其能够再次购买这些商品。 用户限制API允许您限量销售商品。如需配置购买限制，请前往所需商品类型模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 ### 刷新购买限制 - [DELETE /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}/all](https://xsolla.redocly.app/zh/api/catalog/user-limits-admin/reset-user-item-limit.md): 刷新商品的购买限制，以便用户可以再次购买。如果user参数为null，此调用会为所有用户刷新此限制。 用户限制API允许您限量销售商品。如需配置购买限制，请前往所需商品类型模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 ### 获取指定用户可购买的商品剩余数量 - [GET /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/user-limits-admin/get-user-item-limit.md): 获取在已应用的数量限制内，指定用户仍可购买的商品剩余数量。 用户限制API允许您限量销售商品。如需配置购买限制，请前往所需商品类型模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 ### 增加指定用户可购买的商品剩余数量 - [POST /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/user-limits-admin/add-user-item-limit.md): 在已应用的数量限制内，增加指定用户可购买的商品剩余数量。 用户限制API允许您限量销售商品。如需配置购买限制，请前往所需商品类型模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 ### 设置指定用户可购的商品数量 - [PUT /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/user-limits-admin/set-user-item-limit.md): 在已应用的数量限制经过增加或减少后，设置指定用户可购买的商品数量。 用户限制API允许您限量销售商品。如需配置购买限制，请前往所需商品类型模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 ### 减少指定用户可购买的商品剩余数量 - [DELETE /v2/project/{project_id}/admin/user/limit/item/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/user-limits-admin/remove-user-item-limit.md): 在已应用的数量限制内，减少指定用户可购买的商品剩余数量。 用户限制API允许您限量销售商品。如需配置购买限制，请前往所需商品类型模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 ## 管理 ### 通过JSON文件导入商品 - [POST /v1/projects/{project_id}/import/from_external_file](https://xsolla.redocly.app/zh/api/catalog/connector-admin/import-items-from-external-file.md): 通过指定的URL从JSON文件将商品导入商店。关于从JSON文件导入的更多信息，请参阅文档。 ### 获取商品导入状态 - [GET /v1/admin/projects/{project_id}/connectors/import_items/import/status](https://xsolla.redocly.app/zh/api/catalog/connector-admin/get-items-import-status.md): 检索将商品导入项目的进度信息。此API调用检索通过API或发布商帐户执行的最后一次导入的数据。 ## 预售 ### 获取商品预售限制信息 - [GET /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}](https://xsolla.redocly.app/zh/api/catalog/common-pre-orders/get-pre-order-limit.md): 获取商品的预售数量限制。 预售限制API允许限量销售商品。如需配置预售本身，请前往所需商品模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 此接口的别名： * /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://xsolla.redocly.app/zh/api/catalog/common-pre-orders/add-pre-order-limit.md): 添加商品的预售数量限制。 预售限制API允许限量销售商品。如需配置预售本身，请前往所需商品模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 此接口的别名： * /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://xsolla.redocly.app/zh/api/catalog/common-pre-orders/set-pre-order-limit.md): 设置商品的预售数量限制。 预售限制API允许限量销售商品。如需配置预售本身，请前往所需商品模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 此接口的别名： * /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}](https://xsolla.redocly.app/zh/api/catalog/common-pre-orders/remove-pre-order-limit.md): 取消商品的预售数量限制。 预售限制API允许限量销售商品。如需配置预售本身，请前往所需商品模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 此接口的别名： * /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}/toggle](https://xsolla.redocly.app/zh/api/catalog/common-pre-orders/toggle-pre-order-limit.md): 启用/禁用商品的预售限制。 预售限制API允许限量销售商品。如需配置预售本身，请前往所需商品模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 此接口的别名： * /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}/toggle ### 移除所有商品预售数量限制 - [DELETE /v2/project/{project_id}/admin/items/pre_order/limit/item/sku/{item_sku}/all](https://xsolla.redocly.app/zh/api/catalog/common-pre-orders/remove-all-pre-order-limit.md): 取消商品的所有预售数量限制。 预售限制API允许限量销售商品。如需配置预售本身，请前往所需商品模块的管理部分： * 游戏Key * 虚拟物品和货币 * 捆绑包 此接口的别名： * /v2/project/{project_id}/admin/items/pre_order/limit/item/id/{item_id}/all ## 商户 ### 获取项目 - [GET /v2/merchant/{merchant_id}/projects](https://xsolla.redocly.app/zh/api/catalog/common-merchant/get-projects.md): 获取商户项目列表。 提示此API调用不包含project_id路径参数，因此您需要使用在公司所有项目中均有效的API密钥来设置授权。 ## 商品目录 此API可用于获取任意类型的可售商品或特定商品。 ### 获取可售商品列表 - [GET /v2/project/{project_id}/items](https://xsolla.redocly.app/zh/api/catalog/common-catalog/get-sellable-items.md): 获取用于构建商品目录的可售商品列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按ID获取可售商品 - [GET /v2/project/{project_id}/items/id/{item_id}](https://xsolla.redocly.app/zh/api/catalog/common-catalog/get-sellable-item-by-id.md): 按ID获取可售商品。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按SKU获取可售商品 - [GET /v2/project/{project_id}/items/sku/{sku}](https://xsolla.redocly.app/zh/api/catalog/common-catalog/get-sellable-item-by-sku.md): 按SKU获取用于构建商品目录的可售商品。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ### 按指定组获取可售商品列表 - [GET /v2/project/{project_id}/items/group/{external_id}](https://xsolla.redocly.app/zh/api/catalog/common-catalog/get-sellable-items-group.md): 从指定组获取用于构建商品目录的可售商品列表。 注意 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。 注： 未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在Authorization请求头中传递用户JWT。 有关用户JWT的更多信息，请参阅此调用的Security部分。 ## 通用区域 区域销售限制用于控制商品可在哪些国家/地区或国家/地区组销售。例如，受授权许可限制时，您可以将某款游戏设置为仅在特定国家/地区销售。 销售限制通过区域进行配置。每个区域使用一个`region_id`标识符关联一个或多个国家/地区。您可以将一个商品关联到一个或多个区域。 商品是否可售按以下规则判断： * 如果未为商品指定区域，则该商品可在所有国家/地区购买。 * 如果为商品指定了区域，且用户所在国家/地区包含在其中任一区域内，则该商品对该用户可售。 * 如果为商品指定了区域，但用户所在国家/地区不包含在任何指定区域内，则该商品对该用户不可售。 通过**商品目录**子部分中的API调用请求商品目录时，可通过`country`参数传入用户所在国家/地区。如果未传入该参数，系统会根据用户的IP地址判断其所在国家/地区。 系统会在两个环节校验用户所在国家/地区是否符合商品的区域设置：请求商品目录时和创建订单时。不可售商品不会返回在商品目录响应中；包含不可售商品的订单也无法创建。 如需创建、更新或删除区域，请使用**通用区域**组中的API调用。 区域销售限制设置流程： 1. 使用[创建区域](https://developers.xsolla.com/zh/api/catalog/common-regions/admin-create-region/)API调用创建区域，并指定国家/地区列表。响应会返回下一步需要使用的`region_id`。 2. [创建](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-item/)或[更新](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-admin/admin-update-virtual-item/)虚拟物品时，在`regions`数组中传入该区域的`region_id`，将虚拟物品关联到该区域。 3. 使用**商品目录**子部分中的API调用向用户展示商品目录，例如[获取虚拟物品列表](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items)API调用。系统会根据`country`参数确定用户所在国家/地区；如果未提供该参数，则根据用户的IP地址判断。用户所在国家/地区不可售的商品不会包含在商品目录响应中。 4. 当用户继续支付商品或购物车时，创建订单： * 如果商品已添加到购物车，请使用[使用特定购物车中的所有商品创建订单](https://developers.xsolla.com/zh/api/catalog/payment-client-side/create-order)或[使用当前购物车中的所有商品创建订单](https://developers.xsolla.com/zh/api/catalog/payment-client-side/create-order)API调用。 * 如需快速购买单个商品，请使用[使用指定商品创建订单](https://developers.xsolla.com/zh/api/catalog/payment-client-side/create-order-with-item)API调用，并传入商品SKU。 响应中包含用于打开支付UI的令牌。
注：

艾克索拉会检查用户所在国家/地区是否包含在为商品指定的区域中。如果用户所在国家/地区不在该商品的区域范围内，则无法创建订单。

5. 实现支付UI的打开逻辑，以便用户支付订单。 ![通用区域](https://cdn.xsolla.net/developers/current/images/api_docs/api-regions.svg) ### 获取区域列表 - [GET /v2/project/{project_id}/admin/region](https://xsolla.redocly.app/zh/api/catalog/common-regions/admin-get-regions.md): 获取区域列表。 可使用区域来管理区域限制。 ### 创建区域 - [POST /v2/project/{project_id}/admin/region](https://xsolla.redocly.app/zh/api/catalog/common-regions/admin-create-region.md): 创建区域。 可使用区域来管理区域限制。 ### 获取区域 - [GET /v2/project/{project_id}/admin/region/{region_id}](https://xsolla.redocly.app/zh/api/catalog/common-regions/admin-get-region.md): 获取特定区域。 可使用区域来管理区域限制。 ### 更新区域 - [PUT /v2/project/{project_id}/admin/region/{region_id}](https://xsolla.redocly.app/zh/api/catalog/common-regions/admin-update-region.md): 更新特定区域。 可使用区域来管理区域限制。 ### 删除区域 - [DELETE /v2/project/{project_id}/admin/region/{region_id}](https://xsolla.redocly.app/zh/api/catalog/common-regions/admin-delete-region.md): 删除特定区域。 ## Webhook ### 更新Webhook版本 - [PUT /v2/project/{project_id}/admin/webhook/version](https://xsolla.redocly.app/zh/api/catalog/common-webhooks/update-webhook-version.md): 更新项目的Webhook版本。版本2会在items数组中包含额外参数。 有关Webhook的更多信息，请参阅设置订单状态跟踪。 ## 管理 ### 获取属性列表（管理） - [GET /v2/project/{project_id}/admin/attribute](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-get-attribute-list.md): 获取项目中的属性列表，以用于管理。 ### 创建属性 - [POST /v2/project/{project_id}/admin/attribute](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-create-attribute.md): 创建属性。 ### 更新属性 - [PUT /v2/project/{project_id}/admin/attribute/{external_id}](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-update-attribute.md): 更新属性。 ### 获取指定属性 - [GET /v2/project/{project_id}/admin/attribute/{external_id}](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-get-attribute.md): 获取指定的属性。 ### 删除属性 - [DELETE /v2/project/{project_id}/admin/attribute/{external_id}](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/delete-attribute.md): 删除属性。 提示如果删除商品属性，其所有数据及其与商品的关联都将丢失。 ### 创建属性值 - [POST /v2/project/{project_id}/admin/attribute/{external_id}/value](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-create-attribute-value.md): 创建一个属性值。 注意：所有项目对属性值数量均有限制。默认值和最大值均为每个属性20个值。 ### 删除属性的所有值 - [DELETE /v2/project/{project_id}/admin/attribute/{external_id}/value](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-delete-all-attribute-value.md): 删除该属性的所有值。 提示删除属性值后，该属性与商品之间的所有关联关系将被移除。如需更改商品的属性值，请使用更新属性值API调用，而不是删除该值再创建新值。 ### 更新属性值 - [PUT /v2/project/{project_id}/admin/attribute/{external_id}/value/{value_external_id}](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-update-attribute-value.md): 更新属性值。 ### 删除属性值 - [DELETE /v2/project/{project_id}/admin/attribute/{external_id}/value/{value_external_id}](https://xsolla.redocly.app/zh/api/catalog/attribute-admin/admin-delete-attribute-value.md): 删除属性值。 提示删除属性值后，该属性与商品之间的所有关联关系将被移除。如需更改商品的属性值，请使用更新属性值API调用，而不是删除该值再创建新值。 ## 管理 ### 获取商品组列表 - [GET /v2/project/{project_id}/admin/items/groups](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-get-item-group-list.md): 获取项目内完整商品组列表，不分页。用于管理目的。 注：请勿使用此接口来构建商店商品目录。请改用获取商品组列表客户端侧接口。 ### 创建商品组 - [POST /v2/project/{project_id}/admin/items/groups](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-create-item-group.md): 在项目内创建商品组。 如需获取用于构建商品目录的商品组，请使用获取商品组列表客户端侧接口。 ### 按外部ID获取商品组 - [GET /v2/project/{project_id}/admin/items/groups/{external_id}](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-get-item-group.md): 按外部ID获取商品组，用于管理目的。 注：请勿使用此接口来构建商店商品目录。请改用获取商品组列表客户端侧接口。 ### 更新商品组 - [PUT /v2/project/{project_id}/admin/items/groups/{external_id}](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-update-item-group.md): 按外部ID更新商品组。 ### 删除商品组 - [DELETE /v2/project/{project_id}/admin/items/groups/{external_id}](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-delete-item-group.md): 按外部ID删除商品组。 ### 获取按商品类型筛选的商品组列表 - [GET /v2/project/{project_id}/admin/items/{item_type}/groups](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-get-item-group-list-by-item-type.md): 获取按商品类型筛选后的商品组列表。仅将指定类型的商品计入对应组。此接口类似于获取商品组列表接口，但在统计商品数量时会额外按商品类型进行筛选。 ### 按外部ID获取按商品类型筛选的商品组 - [GET /v2/project/{project_id}/admin/items/{item_type}/groups/{external_id}](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-get-item-group-by-item-type.md): 按外部ID获取商品组。仅将指定类型的商品计入对应组。此接口类似于按外部ID获取商品组接口，但在统计商品数量时会额外按商品类型进行筛选。 ### 重新排列商品组 - [PUT /v2/project/{project_id}/admin/group/order](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-reorder-item-groups.md): 设置项目内商品组的显示顺序。传入包含新排序值的组数组。 ### 重新排列组内商品（按外部ID） - [PUT /v2/project/{project_id}/admin/group/{external_id}/order/item](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-reorder-items-in-group.md): 设置由外部ID标识的组内商品显示顺序。传入包含新排序值的商品数组。 ### 重新排列组内商品（按ID） - [PUT /v2/project/{project_id}/admin/group/id/{id}/order/item](https://xsolla.redocly.app/zh/api/catalog/item-groups-admin/admin-reorder-items-in-group-by-id.md): 设置由内部数字ID标识的组内商品显示顺序。传入包含新排序值的商品数组。 ## 商品目录 ### 获取商品组列表 - [GET /v2/project/{project_id}/items/groups](https://xsolla.redocly.app/zh/api/catalog/item-groups-catalog/get-item-groups.md): 获取用于构建商品目录的商品组列表，不分页。 注：商品目录API调用可在未授权情况下使用，但如需获取个性化商品目录，必须在Authorization请求头中传递用户JWT。