跳转到内容
/
更新捆绑包

Shop Builder API (2.0.0)

Overview

  • Version: 2.0.0
  • Servers: https://store.xsolla.com/api
  • Contact Us by Email
  • Contact URL: https://xsolla.com/
  • Required TLS version: 1.2

Shop Builder API provides a third-party solution for implementing the server side for your store interface. Use the endpoints to manage in-game items, in-game currencies, cart, player inventory, promotions, game library, etc.

下载 OpenAPI 描述
index.json
index.yaml
语言
服务器
Mock server
https://xsolla.redocly.app/_mock/zh/api/shop-builder/
https://store.xsolla.com/api/

管理

操作

个性化目录

此API可让您针对用户属性指定规则。如果用户满足具体规则的所有条件，则会显示个性化商品。

有关个性化促销活动的信息，请参阅促销活动部分。

要在购买前传递属性，您可以使用艾克索拉Login API或在使Pay Station API生成令牌时将它们传入user.attributes属性。

操作

管理

操作

获取捆绑包Server-sideAdmin

请求

获取项目中的捆绑包以进行管理。

注意

不要使用此端点来构建商店目录。
安全
basicAuth
路径
project_idinteger必需

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

示例: 44056
skustring必需

捆绑包SKU。

示例: kg_1
curl -i -X GET \
  -u <username>:<password> \
  https://xsolla.redocly.app/_mock/zh/api/shop-builder/v2/project/44056/admin/items/bundle/sku/kg_1

响应

指定的捆绑包已成功接收。

正文application/json
attributesArray of objects(Bundles_admin-attributes)

属性列表。

示例: [{"external_id":"attribute_external_id","name":{"de":"Attributname","en":"Attribute name"},"values":[{"external_id":"value_1","name":{"de":"wert 1","en":"value 1"}},{"external_id":"value_2","name":{"de":"wert 2","en":"value 2"}}]}]
bundle_typestring(bundle_type)

捆绑类型。商品类型是捆绑包时返回。

枚举"standard""virtual_currency_package""partner_side_content"
contentArray of objects(Bundles_admin_content_response)
custom_attributesobject(json)(item-custom-attributes-response)

包含商品属性和值的JSON对象。

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

groupsArray of objects(Bundles_groups_response)

商品所属分组。

默认值 []
示例: [{"external_id":"horror","name":{"en":"Horror"}}]
image_urlstring or null(Bundles_image_url)

图像URL。

示例: "https://image.example.com"
is_enabledboolean(Bundles_is_enabled)

如果禁用，则无法找到和购买该商品。

默认值 true
示例: true
is_freeboolean(value-is_free)

如果为true，则该商品为免费。

默认值 false
示例: false
is_show_in_storeboolean(Bundles_is_show_in_store)

商品可供购买。

默认值 false
示例: true
item_idinteger(Bundles_item_id)[ 1 .. 255 ] characters

内部唯一物品ID。

示例: 1
limitsobject or null(admin-item-limit-response)

商品限制。

long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

Any of:

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

media_listArray of objects or null

捆绑包的附加资源。

示例: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

orderinteger(Bundles_order)

列表中的捆绑包顺序优先级。

默认值 1
示例: 1
periodsArray of objects(item-periods-response)

商品促销时间段。

pricesArray of objects(Bundles_prices)

以真实货币表示的价格。

regionsArray of objects(Bundles_admin-regions)
skustring(Bundles_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$

唯一商品ID。 SKU只能包含大小写英文字母和数字字符、句点、破折号和下划线。

示例: "bundle_1"
total_content_priceobject or null(Bundles_total_content_price)

捆绑包内容价格总和。

typestring(Bundles_type)

商品类型。

示例: "bundle"
virtual_pricesArray of objects(Bundles_admin-response-virtual_price)
响应
application/json
{
  "attributes": [],
  "bundle_type": "standard",
  "content": [
    { … },
    { … },
    { … }
  ],
  "custom_attributes": {
    "purchased": 0,
    "type": "lootbox"
  },
  "description": {
    "en": "Empire bundle with items"
  },
  "groups": [
    { … }
  ],
  "image_url": "https://cdn.xsolla.net/img/misc/images/685b21f9d9dca4aa0c953e8816b4eb4b.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "item_id": 610316,
  "limits": {
    "per_item": null,
    "per_user": { … },
    "recurrent_schedule": null
  },
  "long_description": {
    "en": "Empire bundle with some goods"
  },
  "media_list": [],
  "name": {
    "en": "Empire bundle"
  },
  "order": 1,
  "periods": [
    { … }
  ],
  "prices": [],
  "regions": [],
  "sku": "com.xsolla.EmpireBundle_1",
  "type": "bundle",
  "virtual_prices": [
    { … }
  ]
}

更新捆绑包Server-sideAdmin

请求

更新捆绑包。

安全
basicAuth
路径
project_idinteger必需

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

示例: 44056
skustring必需

捆绑包SKU。

示例: kg_1
正文application/json必需

包含捆绑包数据的对象。

attributesArray of objects(Bundles_admin-post-put-attributes)<= 20 items

属性列表。

注意：为每个商品指定的属性不能超过20个。任何超出限制的尝试都会导致错误。
bundle_typestring(Bundles_bundle_type)

捆绑包类型。使用standard创建包含商品的捆绑包，并指定捆绑包中所含商品的SKU。 使用partner_side_content创建一个空的捆绑包，并使用Webhook在己侧添加商品。此类型仅用于合作伙伴侧的目录个性化。

默认值 "standard"
枚举"standard""partner_side_content"
示例: "standard"
contentArray of objects(Bundles_admin_content_request)non-empty
示例: [{"quantity":1,"sku":"com.xsolla.kg_1"}]
custom_attributesobject(json)(item-custom-attributes)<= 500 characters

包含商品属性和值的JSON对象。属性允许您向商品添加更多信息，例如玩家使用该商品所需的等级。属性可丰富游戏的内部逻辑，并且可以通过专用的GET方法和webhook进行访问。

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)必需

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

description.​arstring or null

阿拉伯语

description.​bgstring or null

保加利亚语

description.​cnstring or null

中文（简体）

description.​csstring or null

捷克语

description.​destring or null

德语

description.​enstring or null

英语

description.​esstring or null

西班牙语（西班牙）

description.​frstring or null

法语

description.​hestring or null

希伯来语

description.​idstring or null

印度尼西亚语

description.​itstring or null

意大利语

description.​jastring or null

日语

description.​kmstring or null

高棉语

description.​kostring or null

韩语

description.​lostring or null

老挝语

description.​mystring or null

缅甸语

description.​nestring or null

尼泊尔语

description.​phstring or null

菲律宾语

description.​plstring or null

波兰语

description.​ptstring or null

葡萄牙语

description.​rostring or null

罗马尼亚语

description.​rustring or null

俄语

description.​thstring or null

泰语

description.​trstring or null

土耳其语

description.​twstring or null

中文（繁体）

description.​vistring or null

越南语

groupsArray of strings(Bundles_groups_request)

商品所属的组。

注：字符串值引用组`external_id`。
默认值 []
示例: ["honor"]
image_urlstring or null(Bundles_image_url)

图像URL。

示例: "https://image.example.com"
is_enabledboolean(Bundles_is_enabled)

如果禁用，则无法找到和购买该商品。

默认值 true
示例: true
is_freeboolean(value-is_free)

如果为true，则该商品为免费。

默认值 false
示例: false
is_show_in_storeboolean(Bundles_is_show_in_store)

商品可供购买。

默认值 false
示例: true
limitsobject(bundle-item-limit)

商品限制。

long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

Any of:

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

media_listArray of objects or null

捆绑包的附加资源。

示例: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)必需

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

name.​arstring or null

阿拉伯语

name.​bgstring or null

保加利亚语

name.​cnstring or null

中文（简体）

name.​csstring or null

捷克语

name.​destring or null

德语

name.​enstring or null

英语

name.​esstring or null

西班牙语（西班牙）

name.​frstring or null

法语

name.​hestring or null

希伯来语

name.​idstring or null

印度尼西亚语

name.​itstring or null

意大利语

name.​jastring or null

日语

name.​kmstring or null

高棉语

name.​kostring or null

韩语

name.​lostring or null

老挝语

name.​mystring or null

缅甸语

name.​nestring or null

尼泊尔语

name.​phstring or null

菲律宾语

name.​plstring or null

波兰语

name.​ptstring or null

葡萄牙语

name.​rostring or null

罗马尼亚语

name.​rustring or null

俄语

name.​thstring or null

泰语

name.​trstring or null

土耳其语

name.​twstring or null

中文（繁体）

name.​vistring or null

越南语

orderinteger(Bundles_order)

列表中的捆绑包顺序优先级。

默认值 1
示例: 1
periodsArray of objects or null(item-periods)

商品促销时间段。

pricesArray of objects(Bundles_prices)

以真实货币表示的价格。

regionsArray of objects(Bundles_admin-regions)
skustring(Bundles_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$必需

唯一商品ID。 SKU只能包含大小写英文字母和数字字符、句点、破折号和下划线。

示例: "bundle_1"
vc_pricesArray of objects or null
curl -i -X PUT \
  -u <username>:<password> \
  https://xsolla.redocly.app/_mock/zh/api/shop-builder/v2/project/44056/admin/items/bundle/sku/kg_1 \
  -H 'Content-Type: application/json' \
  -d '{
    "attributes": [
      {
        "external_id": "class",
        "name": {
          "en": "Class"
        },
        "values": [
          {
            "external_id": "soldier",
            "value": {
              "en": "Soldier"
            }
          },
          {
            "external_id": "officer",
            "value": {
              "en": "Officer"
            }
          }
        ]
      }
    ],
    "content": [
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_gloves_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_boots_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_shield_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_armour_1"
      },
      {
        "quantity": 1,
        "sku": "com.xsolla.iron_helmet_1"
      }
    ],
    "custom_attributes": {
      "purchased": 0,
      "type": "lootbox"
    },
    "description": {
      "de": "Brustpanzer für Soldaten",
      "en": "Chest of armour for soldiers"
    },
    "groups": [
      "chests"
    ],
    "image_url": "https://picture.bundle-with-many-stuff.png",
    "is_enabled": true,
    "is_free": true,
    "limits": {
      "per_item": null,
      "per_user": null
    },
    "long_description": {
      "de": "Brustpanzer für Soldaten",
      "en": "Chest of armour for soldiers"
    },
    "media_list": [
      {
        "type": "image",
        "url": "https://test.com/image0"
      },
      {
        "type": "image",
        "url": "https://test.com/image1"
      }
    ],
    "name": {
      "de": "Brustpanzer",
      "en": "Chest of armour"
    },
    "order": 1,
    "periods": [
      {
        "date_from": "2020-08-11T10:00:00+03:00",
        "date_until": "2020-08-11T20:00:00+03:00"
      }
    ],
    "prices": [
      {
        "amount": "9.99",
        "currency": "USD",
        "is_default": true,
        "is_enabled": true
      },
      {
        "amount": "9.99",
        "currency": "EUR",
        "is_default": false,
        "is_enabled": true
      }
    ],
    "sku": "com.xsolla.armour_chest_1",
    "vc_prices": []
  }'

响应

捆绑包已成功更新。

正文
响应
无内容

在目录中隐藏捆绑包Server-sideAdmin

请求

在目录中隐藏捆绑包。

安全
basicAuth
路径
project_idinteger必需

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

示例: 44056
skustring必需

捆绑包SKU。

示例: kg_1
curl -i -X PUT \
  -u <username>:<password> \
  https://xsolla.redocly.app/_mock/zh/api/shop-builder/v2/project/44056/admin/items/bundle/sku/kg_1/hide

响应

捆绑已成功隐藏。

正文
响应
无内容

目录

操作

购物车（客户端侧）

操作

购物车（服务器侧）

操作

支付（客户端）

操作

支付（服务器端）

操作

订单

操作

免费商品

操作

Webhook

操作

预订

操作

商户

操作

目录

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

操作

通用区域

操作

目录

操作

权利

操作

管理

操作

通用

操作

优惠券

此API让您可以管理优惠券。

操作

促销码

此API让您可以管理促销码。

操作

特别目录优惠

此API让您可以管理特别目录优惠活动。

操作

折扣

此API让您可以管理折扣促销活动。

操作

奖励

此API让您可以管理奖励促销活动。

操作

管理

操作

目录

操作

虚拟支付

操作

管理

操作

管理

操作

客户端

操作

公会客户端

操作

管理

操作

客户端

操作

管理

操作

客户端

操作

管理

操作

客户端

操作

管理

操作