商店
商店 API 允许服务器所有者设置商店，包括分类、商品、购物车、订单、评价和钱包系统。
获取 / 创建商店
GET /api/servers/:serverId/shop
返回服务器的商店，如果不存在则创建一个。
const shop = await client.getShop('server-id')
shop = client.get_shop("server-id")
更新商店
PUT /api/servers/:serverId/shop
await client.updateShop('server-id', { name: 'My Store' })
client.update_shop("server-id", name="My Store")
分类
列出分类
GET /api/servers/:serverId/shop/categories
const categories = await client.listCategories('server-id')
categories = client.list_categories("server-id")
创建分类
POST /api/servers/:serverId/shop/categories
const category = await client.createCategory('server-id', {
name: 'Merch',
description: 'Official merchandise',
})
category = client.create_category("server-id", name="Merch", description="Official merchandise")
更新分类
PUT /api/servers/:serverId/shop/categories/:categoryId
await client.updateCategory('server-id', 'category-id', { name: 'Accessories' })
client.update_category("server-id", "category-id", name="Accessories")
删除分类
DELETE /api/servers/:serverId/shop/categories/:categoryId
await client.deleteCategory('server-id', 'category-id')
client.delete_category("server-id", "category-id")
商品
列出商品
GET /api/servers/:serverId/shop/products
| 参数 | 类型 | 说明 |
|---|
status | string | 按状态筛选 |
categoryId | string | 按分类筛选 |
keyword | string | 搜索关键词 |
limit | number | 最大结果数 |
offset | number | 偏移量 |
const products = await client.listProducts('server-id', { keyword: 'shirt' })
products = client.list_products("server-id", keyword="shirt")
获取商品
GET /api/servers/:serverId/shop/products/:productId
const product = await client.getProduct('server-id', 'product-id')
product = client.get_product("server-id", "product-id")
创建商品
POST /api/servers/:serverId/shop/products
const product = await client.createProduct('server-id', {
name: 'T-Shirt',
categoryId: 'category-id',
price: 25.99,
})
product = client.create_product("server-id", name="T-Shirt", categoryId="category-id", price=25.99)
更新商品
PUT /api/servers/:serverId/shop/products/:productId
await client.updateProduct('server-id', 'product-id', { price: 19.99 })
client.update_product("server-id", "product-id", price=19.99)
删除商品
DELETE /api/servers/:serverId/shop/products/:productId
await client.deleteProduct('server-id', 'product-id')
client.delete_product("server-id", "product-id")
购物车
获取购物车
GET /api/servers/:serverId/shop/cart
const cart = await client.getCart('server-id')
cart = client.get_cart("server-id")
加入购物车
POST /api/servers/:serverId/shop/cart
| 字段 | 类型 | 必填 | 说明 |
|---|
productId | string | 是 | 商品 ID |
skuId | string | 否 | SKU 变体 |
quantity | number | 是 | 数量 |
await client.addToCart('server-id', {
productId: 'product-id',
quantity: 2,
})
client.add_to_cart("server-id", productId="product-id", quantity=2)
更新购物车商品
PUT /api/servers/:serverId/shop/cart/:itemId
await client.updateCartItem('server-id', 'item-id', 3)
client.update_cart_item("server-id", "item-id", quantity=3)
从购物车移除
DELETE /api/servers/:serverId/shop/cart/:itemId
await client.removeFromCart('server-id', 'item-id')
client.remove_from_cart("server-id", "item-id")
订单
下单
POST /api/servers/:serverId/shop/orders
| 字段 | 类型 | 必填 | 说明 |
|---|
items | array | 是 | 购物车商品 ID 或商品规格 |
buyerNote | string | 否 | 买家备注 |
const order = await client.placeOrder('server-id', {
items: [{ productId: 'pid', quantity: 1 }],
buyerNote: 'Please gift-wrap',
})
order = client.place_order("server-id", items=[{"productId": "pid", "quantity": 1}], buyerNote="Please gift-wrap")
列出我的订单
GET /api/servers/:serverId/shop/orders
const orders = await client.listOrders('server-id', { status: 'paid' })
orders = client.list_orders("server-id", status="paid")
管理员：管理订单
GET /api/servers/:serverId/shop/orders/manage
const orders = await client.manageOrders('server-id', { status: 'pending' })
orders = client.manage_orders("server-id", status="pending")
获取订单
GET /api/servers/:serverId/shop/orders/:orderId
const order = await client.getOrder('server-id', 'order-id')
order = client.get_order("server-id", "order-id")
更新订单状态
PUT /api/servers/:serverId/shop/orders/:orderId/status
| 字段 | 类型 | 必填 | 说明 |
|---|
status | string | 是 | 新状态 |
trackingNo | string | 否 | 物流单号 |
sellerNote | string | 否 | 卖家备注 |
await client.updateOrderStatus('server-id', 'order-id', {
status: 'shipped',
trackingNo: 'TRACK123',
})
client.update_order_status("server-id", "order-id", status="shipped", trackingNo="TRACK123")
取消订单
POST /api/servers/:serverId/shop/orders/:orderId/cancel
await client.cancelOrder('server-id', 'order-id')
client.cancel_order("server-id", "order-id")
评价
列出商品评价
GET /api/servers/:serverId/shop/products/:productId/reviews
const reviews = await client.listProductReviews('server-id', 'product-id')
reviews = client.list_product_reviews("server-id", "product-id")
提交评价
POST /api/servers/:serverId/shop/orders/:orderId/review
| 字段 | 类型 | 必填 | 说明 |
|---|
productId | string | 是 | 评价的商品 |
rating | number | 是 | 1 – 5 |
content | string | 否 | 评价内容 |
images | string[] | 否 | 图片 URL |
isAnonymous | boolean | 否 | 匿名发布 |
await client.submitReview('server-id', 'order-id', {
productId: 'product-id',
rating: 5,
content: 'Excellent quality!',
})
client.submit_review("server-id", "order-id", productId="product-id", rating=5, content="Excellent quality!")
回复评价（卖家）
PUT /api/servers/:serverId/shop/reviews/:reviewId/reply
await client.replyToReview('server-id', 'review-id', 'Thank you!')
client.reply_to_review("server-id", "review-id", reply="Thank you!")
钱包
获取钱包
const wallet = await client.getWallet()
wallet = client.get_wallet()
充值
| 字段 | 类型 | 必填 | 说明 |
|---|
amount | number | 是 | 充值金额 |
note | string | 否 | 备注 |
await client.topUpWallet(100, 'Monthly deposit')
client.top_up_wallet(100, note="Monthly deposit")
列出交易记录
GET /api/wallet/transactions
const txns = await client.listTransactions({ limit: 50 })
txns = client.list_transactions(limit=50)
权益
GET /api/servers/:serverId/shop/entitlements
const entitlements = await client.listEntitlements('server-id')
entitlements = client.list_entitlements("server-id")
