Catalog API (2.0.0)
- 版本： 2.0.0
- 服务器：
https://store.xsolla.com/api - 通过邮件联系我们
- 联系URL: https://xsolla.com/
- 必需的TLS版本： 1.2
商品目录API支持在艾克索拉侧配置游戏内商品目录，并在您的商店中向用户展示目录内容。
通过该API可管理以下目录实体：
- 虚拟物品 — 游戏内物品，例如武器、皮肤、增益道具。
- 虚拟货币 — 用于购买虚拟商品的虚拟货币。
- 虚拟货币套餐 — 预定义的虚拟货币捆绑包。
- 捆绑包 — 虚拟物品、货币或游戏激活码的组合套餐，以单个SKU形式出售。
- 游戏密钥 — 适用于Steam等平台或其他DRM提供商分发的游戏和DLC激活码。
- 组 — 用于在目录中组织和排序商品的逻辑分组。
API分为以下组别：
Admin — 用于创建、更新、删除和配置目录商品及分组的调用。通过基本认证方式验证身份，需使用您的商户或项目凭据。不适用于商店前端调用。Catalog — 用于检索商品并构建面向最终用户的自定义商店前端。专为高负载场景设计。支持可选的用户JWT授权，可返回个性化数据，例如用户特定限制和当前进行中的促销活动。
下载 OpenAPI 描述
语言
服务器
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/zh/api/catalog/
- https://store.xsolla.com/api/v2/project/{project_id}/items/virtual_items/all
- Mock serverhttps://xsolla.redocly.app/_mock/zh/api/catalog/v2/project/{project_id}/items/virtual_items/all
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/all?locale=en&promo_code=WINTER2021' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'已成功接收所有虚拟物品列表。
示例: [{"description":"Big Rocket - description","groups":[{"external_id":"accessory","name":{"en":"accessory"}}],"name":"Big Rocket","sku":"com.xsolla.big_rocket_1"},{"description":"description","groups":[{"external_id":"hair","name":{"en":"Hair"}}],"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.shotgun_raider_1"},{"description":"description","groups":[],"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.shotgun_raider_2"}]
响应
application/json
{ "items": [ { … }, { … }, { … } ] }
- https://store.xsolla.com/api/v2/project/{project_id}/items/virtual_items/group/{external_id}
- Mock serverhttps://xsolla.redocly.app/_mock/zh/api/catalog/v2/project/{project_id}/items/virtual_items/group/{external_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/group/{external_id}?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'来自指定组的商品列表已成功接收。
示例: [{"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"value":"5"}]}],"can_be_bought":true,"description":"Big Rocket - description","groups":[{"external_id":"weapons","name":"weapons"}],"image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","is_free":false,"limits":{"per_item":null,"per_user":{"available":3,"limit_exceeded_visibility":"show","recurrent_schedule":{"interval_type":"weekly","reset_next_date":1746057600},"total":5}},"name":"Big Rocket","periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}],"price":{"amount":"100.99","amount_without_discount":"100.99","currency":"USD"},"promotions":[{"bonus":[{"image_url":"https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png","name":"Xsolla Minigun","quantity":1,"sku":"com.xsolla.minigun_1","type":"virtual_good"}],"date_end":"2026-04-15T16:16:00+03:00","date_start":"2020-04-15T16:16:00+03:00","discount":{"percent":"50.00"},"name":"Bonus promotion"}],"sku":"com.xsolla.big_rocket_1","type":"virtual_good","virtual_item_type":"non_renewing_subscription","virtual_prices":[{"amount":100,"amount_without_discount":100,"description":"description","image_url":"http://image.png","is_default":true,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_1","type":"virtual_currency"}]},{"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"value":"5"}]},{"external_id":"rating","name":"Rating","values":[{"value":"3.9"}]},{"external_id":"genre","name":"Genre","values":[{"value":"Strategy"},{"value":"Tactical"},"Turn-based"]}],"can_be_bought":true,"description":"description","groups":[{"external_id":"weapons","name":{"en":"weapons"}}],"image_url":"http://image.png","is_free":false,"limits":null,"name":"SHOTGUN FOR TRUE RAIDERS","periods":[],"price":{"amount":"101.0","amount_without_discount":"101.0","currency":"USD"},"promotions":[],"sku":"com.xsolla.shotgun_raider","type":"virtual_good","virtual_item_type":"non_renewing_subscription","virtual_prices":[{"amount":100,"amount_without_discount":100,"description":"description","image_url":"http://image.png","is_default":true,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_1","type":"virtual_currency"},{"amount":200,"amount_without_discount":200,"description":"description","image_url":"http://image.png","is_default":false,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_2","type":"virtual_currency"}]}]
响应
application/json
{ "has_more": false, "items": [ { … }, { … } ] }
- https://store.xsolla.com/api/v2/project/{project_id}/items/virtual_items/sku/{item_sku}
- Mock serverhttps://xsolla.redocly.app/_mock/zh/api/catalog/v2/project/{project_id}/items/virtual_items/sku/{item_sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/sku/booster_mega_1?locale=en&country=US&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'已成功接收虚拟物品。
与商品对应的属性及其值的列表。可用于目录筛选。
默认值 []
示例: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
商品所属分组。
默认值 []
示例: [{"external_id":"exclusive","name":"Exclusive"}]
图像URL。
示例: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
应用于购物车中指定商品的促销活动。仅在以下情况下返回该数组：
为某商品配置了折扣促销活动。
应用了对所选商品提供折扣设置的促销码。
如果未应用任何商品级促销活动，则返回空数组。
虚拟物品的类型。
| 枚举 值 | 描述 |
|---|---|
| consumable | 使用后从物品库中消失的物品（例如弹药）。 |
| non_consumable | 无限期地留在物品库中的物品。 |
| non_renewing_subscription | 时效性商品，代表在有限时间内对服务或内容的访问权限。 |
示例: "non-consumable"
响应
application/json
{ "attributes": [ { … } ], "can_be_bought": true, "custom_attributes": { "attr": "value", "purchased": 0 }, "description": { "en": "Honshu Boshin Wakizashi - Modern Tactical Samurai / Ninja Sword - Hand Forged 1060 Carbon Steel - Full Tang, Fully Functional, Battle Ready - Black TPR, Steel Guard and Pommel" }, "groups": [ { … } ], "image_url": "https://cdn.xsolla.net/img/misc/images/8ab44fe99038a56de01950ba4a971b77.png", "is_free": false, "item_id": 488833, "limits": { "per_item": null, "per_user": { … } }, "name": { "en": "Sword Xsolla Skin" }, "periods": [ { … } ], "price": { "amount": "4.99", "amount_without_discount": "4.99", "currency": "USD" }, "promotions": [], "sku": "com.xsolla.swords_1", "type": "virtual_good", "virtual_item_type": "non_consumable", "virtual_prices": [], "vp_rewards": [] }