`是用户令牌。该令牌用于识别用户，并提供对个性化数据的访问权限。\n或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。\n\n2. **不带Authorization请求头的简化模式。** 此模式仅适用于未完成身份认证的用户，且仅可用于[游戏Key销售](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)请求中不使用令牌，而必须包含以下请求头：\n - `x-unauthorized-id`，值为请求ID\n - `x-user`，值为使用Base64编码的用户电子邮件地址\n\n## 实用链接\n\n- [按交互模型划分的API调用](https://developers.xsolla.com/zh/api/catalog/)\n- [接口类型](https://developers.xsolla.com/zh/api/catalog/)\n- [错误处理](https://developers.xsolla.com/zh/api/catalog/)\n- [API密钥](https://developers.xsolla.com/zh/api/catalog/)\n\n# 核心实体结构\n\n所有类型的商品（虚拟物品、捆绑包、虚拟货币和密钥）都使用类似的数据结构。了解基本结构有助于简化API使用，并帮助您更轻松地查阅文档。\n\n注：
部分调用可能包含其他字段，但这些字段不会改变基本结构。
\n\n**标识信息**\n\n- `merchant_id` — [发布商帐户](https://publisher.xsolla.com/)中的公司ID\n- `project_id` — 发布商帐户中的项目ID\n- `sku` — 商品SKU，在项目内唯一\n\n**商店显示**\n\n- `name` — 商品名称\n- `description` — 商品描述\n- `image_url` — 图片URL\n- `is_enabled` — 商品可用性\n- `is_show_in_store` — 商品是否显示在商品目录中\n\n有关在商品目录中管理商品可用性的更多信息，请参阅[文档](/zh/items-catalog/catalog-features/items-availability/)。\n\n**组织方式**\n\n- `type` — 商品类型，例如虚拟物品（`virtual_item`）或捆绑包（`bundle`）\n- `groups` — 商品所属的组\n- `order` — 在商品目录中的显示顺序\n\n**Sale conditions**\n\n- `prices` — 以真实货币或虚拟货币表示的价格\n- `limits` — 购买限制\n- `periods` — 可用时间段\n- `regions` — 区域限制\n\n**核心实体结构示例：**\n\n```json\n{\n \"attributes\": [],\n \"bundle_type\": \"virtual_currency_package\",\n \"content\": [\n {\n \"description\": {\n \"en\": \"Main in-game currency\"\n },\n \"image_url\": \"https://.../image.png\",\n \"name\": {\n \"en\": \"Crystals\",\n \"de\": \"Kristalle\"\n },\n \"quantity\": 500,\n \"sku\": \"com.xsolla.crystal_2\",\n \"type\": \"virtual_currency\"\n }\n ],\n \"description\": {\n \"en\": \"Crystals x500\"\n },\n \"groups\": [],\n \"image_url\": \"https://.../image.png\",\n \"is_enabled\": true,\n \"is_free\": false,\n \"is_show_in_store\": true,\n \"limits\": {\n \"per_item\": null,\n \"per_user\": null,\n \"recurrent_schedule\": null\n },\n \"long_description\": null,\n \"media_list\": [],\n \"name\": {\n \"en\": \"Medium crystal pack\"\n },\n \"order\": 1,\n \"periods\": [\n {\n \"date_from\": null,\n \"date_until\": \"2020-08-11T20:00:00+03:00\"\n }\n ],\n \"prices\": [\n {\n \"amount\": 20,\n \"country_iso\": \"US\",\n \"currency\": \"USD\",\n \"is_default\": true,\n \"is_enabled\": true\n }\n ],\n \"regions\": [],\n \"sku\": \"com.xsolla.crystal_pack_2\",\n \"type\": \"bundle\",\n \"vc_prices\": []\n}\n```\n\n# 基本购买流程\n\n艾克索拉API可用于实现游戏内购商店逻辑，包括获取商品目录、管理购物车、创建订单以及跟踪订单状态。根据集成场景，API调用分为**管理**和**商品目录**子部分，使用不同的[身份认证方案](/zh/api/catalog/section/authentication)。\n\n以下示例展示了从创建商品到完成购买的商店设置和运营基本流程。\n\n## 创建商品和组（管理）\n\n为您的商店创建商品目录，例如虚拟物品、捆绑包或虚拟货币。\n\nAPI调用示例：\n- [创建虚拟物品](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-item)\n- [创建捆绑包](/zh/api/catalog/bundles-admin/admin-create-bundle)\n- [创建虚拟货币](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency)\n\n## 设置促销、奖励链和限制（管理）\n\n配置用户拉新和赢利工具，例如折扣、赠品、每日奖励或优惠链。\n\nAPI调用示例：\n- [创建买赠促销活动](/zh/api/liveops/promotions-bonuses/create-bonus-promotion)\n- [创建每日奖励](/zh/api/liveops/daily-chain-admin/admin-create-daily-chain)\n- [创建唯一商品目录优惠促销活动](/zh/api/liveops/promotions-unique-catalog-offers/admin-create-unique-catalog-offer)\n\n## 获取商品信息（客户端）\n\n在您的应用程序中配置商品显示。\n\n\n
提示\n 请勿使用管理子部分中的API调用来构建用户商品目录。这些API调用存在
速率限制，并不适用于用户流量。\n
\n\nAPI调用示例：\n- [获取虚拟物品列表](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items)\n- [获取商品组列表](/zh/api/catalog/virtual-items-currency-catalog/get-item-groups)\n- [获取捆绑包列表](/zh/api/catalog/bundles-catalog/get-bundle-list)\n- [获取可售商品列表](/zh/api/catalog/common-catalog/get-sellable-items)\n\n\n 注：
\n 默认情况下，商品目录API调用会返回请求时商店中当前可用的商品。如需获取尚未可用或已不再可用的商品，请在商品目录请求中包含参数\"show_inactive_time_limited_items\": 1。\n
\n\n## 销售商品\n\n您可以使用以下方法销售商品：\n- 快速购买 — 多次销售同一SKU。\n- 购物车购买 — 用户可在同一订单中向购物车添加商品、移除商品并更新数量。\n\n如果商品使用虚拟货币而非真实货币购买，请使用[创建包含指定商品的订单](/zh/api/catalog/virtual-payment/create-order-with-item-for-virtual-currency) API调用。由于扣款会在执行API调用时处理，因此无需支付UI。\n\n如需购买免费商品，请使用[使用指定商品创建订单](/zh/api/catalog/free-item/create-free-order-with-item) API调用或[使用免费购物车创建订单](/zh/api/catalog/free-item/create-free-order) API调用。无需支付UI — 订单会立即设置为done状态。\n\n### 快速购买\n\n使用客户端API调用[使用指定商品创建订单](/zh/api/catalog/payment-client-side/create-order-with-item)。该调用会返回用于打开支付UI的令牌。\n\n\n 注：
\n 用户只能在支付UI中查看折扣信息。不支持兑换码。\n
\n\n### 购物车购买\n\n可以在客户端或服务器侧设置购物车并完成购买。\n\n**在客户端设置和购买购物车商品**\n\n您需要自行实现添加和移除商品的逻辑。在调用用于设置购物车的API之前，您无法获知哪些促销活动会应用于本次购买。这意味着您无法提前获知总费用以及添加的赠品的详细信息。\n\n实现以下购物车逻辑：\n1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/shop-builder/operation/cart-fill/) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。\n2. 根据用户操作更新购物车内容：\n - 如需添加商品或更改商品数量，请使用[按购物车ID更新购物车商品](/zh/api/shop-builder/operation/put-item-by-cart-id/) API调用。\n - 如需移除商品，请使用[按购物车ID删除购物车商品](/zh/api/shop-builder/operation/delete-item-by-cart-id/) API调用。\n\n\n 注：
\n 如需获取购物车的当前状态，请使用“获取当前用户的购物车”API调用。\n
\n\n3. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用返回订单ID和支付令牌。新创建的订单默认设置为new状态。\n\n**在服务器侧设置和购买购物车商品**\n\n这种设置方式可能需要更长的购物车设置时间，因为每次更改购物车都必须伴随API调用。\n\n实现以下购物车逻辑：\n1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/catalog/cart-server-side) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。\n2. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用会返回订单ID和支付令牌。新创建的订单默认设置为new状态。\n\n## 打开支付UI\n\n使用返回的令牌在新窗口中打开支付UI。有关打开支付UI的其他方式，请参阅[文档](/zh/payment-ui-and-flow/payment-ui/how-to-open-payment-ui/#open_payment_ui)。\n\n| 操作 | 接口 |\n|:--------------------------------|:--------------------------------------------------------------------------|\n| 在生产环境中打开。 | https://secure.xsolla.com/paystation4/?token={token} |\n| 在沙盒模式中打开。 | https://sandbox-secure.xsolla.com/paystation4/?token={token} |\n\n\n
注：\n 请在开发和测试期间使用沙盒模式。测试购买不会对真实帐户扣款。您可以使用
测试银行卡。\n\n 完成第一笔真实支付后，严格的沙盒支付策略将生效。沙盒模式下的支付仅对[发布商帐户 > 公司设置 > 用户](https://publisher.xsolla.com/0/settings/users)中指定的用户可用。\n\n 只有在与艾克索拉签署许可协议后，才能使用真实货币购买虚拟货币和商品。如需签署协议，请在[发布商帐户](https://publisher.xsolla.com/)中前往**协议与税务 > 合同与协议**，填写协议表单并等待确认。协议审核最多可能需要3个工作日。\n