Marketplace API 参考

本文档描述 AI Agent Marketplace 的完整 API 接口。

基础信息

Base URL: /api
认证方式: 复用现有 Chameleon Session/Token 认证
内容类型: application/json

商品市场 API

商品列表

获取商品列表，支持分页、筛选和搜索。

GET /marketplace/listings

查询参数：

参数	类型	必填	说明
page	integer	否	页码，默认 1
size	integer	否	每页数量，默认 20
asset_type	string	否	资产类型筛选
pricing_model	string	否	定价模式筛选
keyword	string	否	关键词搜索
sort_by	string	否	排序：price/rating/created_at
sort_order	string	否	排序方向：asc/desc

响应：

{
  "items": [
    {
      "id": "uuid",
      "title": "商品标题",
      "description": "商品描述",
      "asset_type": "agent",
      "pricing_model": "one_time",
      "base_price": 100,
      "rating_avg": 4.5,
      "rating_count": 10,
      "seller": {
        "id": "uuid",
        "username": "卖家名"
      },
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 20
}

商品详情

获取单个商品的详细信息。

GET /marketplace/listings/{id}

响应：

{
  "id": "uuid",
  "title": "商品标题",
  "description": "商品描述",
  "cover_image_url": "https://...",
  "asset_type": "agent",
  "asset_id": "uuid",
  "pricing_model": "one_time",
  "base_price": 100,
  "status": "published",
  "download_count": 50,
  "rating_avg": 4.5,
  "rating_count": 10,
  "tags": ["标签1", "标签2"],
  "seller": {
    "id": "uuid",
    "username": "卖家名",
    "avatar_url": "https://..."
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

上架商品

卖家上架新的 AI 资产。

POST /marketplace/listings

请求体：

{
  "asset_type": "agent",
  "asset_id": "uuid",
  "title": "商品标题",
  "description": "商品描述",
  "cover_image_url": "https://...",
  "pricing_model": "one_time",
  "base_price": 100,
  "tags": ["标签1", "标签2"]
}

响应： 返回创建的商品详情

更新商品

更新已上架商品的信息。

PUT /marketplace/listings/{id}

请求体： 与上架商品相同（可选字段）

下架商品

删除或下架商品。

DELETE /marketplace/listings/{id}

商品评价列表

获取商品的评价列表。

GET /marketplace/listings/{id}/reviews

查询参数：

参数	类型	必填	说明
page	integer	否	页码，默认 1
size	integer	否	每页数量，默认 20

提交评价

购买后对商品进行评价。

POST /marketplace/listings/{id}/reviews

请求体：

{
  "rating": 5,
  "comment": "非常好用的 Agent！"
}

交易 API

创建订单

购买商品，创建交易订单。

POST /marketplace/orders

请求体：

{
  "listing_id": "uuid"
}

响应：

{
  "id": "uuid",
  "listing_id": "uuid",
  "total_price": 100,
  "platform_fee": 20,
  "seller_income": 80,
  "status": "paid",
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:00:01Z"
}

购买流程时序图：

sequenceDiagram
    participant B as Buyer
    participant API as Marketplace API
    participant W as Wallet Service
    participant S as Seller

    B->>API: POST /orders (listing_id)
    API->>W: 检查买家余额
    W-->>API: 余额充足
    API->>W: 冻结买家积分
    API->>API: 创建订单 (pending)
    API->>W: 扣除买家积分
    API->>W: 计算佣金 (price * commission_rate)
    API->>W: 卖家入账 (price - commission)
    API->>API: 订单完成 (paid)
    API-->>B: 返回订单 + 资产访问权限

我的订单列表

获取当前用户的订单列表。

GET /marketplace/orders

查询参数：

参数	类型	必填	说明
page	integer	否	页码，默认 1
size	integer	否	每页数量，默认 20
status	string	否	状态筛选

订单详情

获取单个订单的详细信息。

GET /marketplace/orders/{id}

申请退款

对已购买的订单申请退款。

POST /marketplace/orders/{id}/refund

请求体：

{
  "reason": "退款原因"
}

积分钱包 API

查询钱包余额

获取当前用户的钱包信息。

GET /wallet

响应：

{
  "id": "uuid",
  "balance": 1000,
  "frozen_balance": 0,
  "total_earned": 5000,
  "total_spent": 4000
}

积分流水

获取钱包的交易流水记录。

GET /wallet/transactions

查询参数：

参数	类型	必填	说明
page	integer	否	页码，默认 1
size	integer	否	每页数量，默认 20
type	string	否	类型筛选

响应：

{
  "items": [
    {
      "id": "uuid",
      "type": "spend",
      "amount": -100,
      "balance_after": 900,
      "reference_type": "order",
      "reference_id": "uuid",
      "description": "购买商品：xxx",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 50,
  "page": 1,
  "size": 20
}

积分充值

充值积分（MVP 阶段使用模拟支付）。

POST /wallet/topup

请求体：

{
  "amount": 1000,
  "payment_method": "mock"
}

积分提现

将积分提现或兑换。

POST /wallet/withdraw

请求体：

{
  "amount": 500,
  "method": "alipay"
}

用户间转账

向其他用户转账积分。

POST /wallet/transfer

请求体：

{
  "to_user_id": "uuid",
  "amount": 100,
  "message": "转账备注"
}

管理后台 API

获取平台配置

获取所有平台配置项。

GET /admin/config

响应：

{
  "commission_rate": 0.20,
  "min_withdrawal": 1000,
  "daily_earn_cap": 500
}

更新平台配置

更新指定的平台配置项。

PUT /admin/config/{key}

请求体：

{
  "value": "0.25",
  "description": "平台佣金比例"
}

审核商品列表

获取待审核或已审核的商品列表。

GET /admin/listings

查询参数：

参数	类型	必填	说明
page	integer	否	页码，默认 1
size	integer	否	每页数量，默认 20
status	string	否	状态筛选

审核/下架商品

修改商品的状态（审核通过、下架等）。

PUT /admin/listings/{id}/status

请求体：

{
  "status": "published",
  "reason": "审核通过"
}

平台统计数据

获取平台的统计信息。

GET /admin/stats

响应：

{
  "total_listings": 100,
  "total_orders": 500,
  "total_users": 200,
  "total_transaction_volume": 50000,
  "platform_commission_total": 10000
}

错误处理

错误响应格式

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "积分余额不足",
    "details": {
      "required": 100,
      "available": 50
    }
  }
}

错误码列表

错误码	说明	HTTP 状态码
INSUFFICIENT_BALANCE	积分余额不足	400
LISTING_NOT_FOUND	商品不存在	404
ORDER_NOT_FOUND	订单不存在	404
ALREADY_REVIEWED	已经评价过该商品	400
INVALID_PRICING_MODEL	无效的定价模式	400
UNAUTHORIZED	未授权	401
FORBIDDEN	权限不足	403