logan

Appearance

1. 获取店铺首页信息 ​

接口地址：/home/shop

请求参数：

参数名类型必填说明
tokenString是店铺号

成功响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "token": "1111",
    "shop": {
      "id": 4,
      "user_id": 1004,
      "shop_name": "ovo小店",
      "stock_display": 2,
      "merchant_time": 1763795563,
      "shop_contact": {
        "qq": "QQ：5111121254844544",
        "wechat": "<span style=\"font-weight: 500;\">446545415784</span>",
        "mobile": "<a href=\"tel:21321313546121\" style=\"text-decoration: none;\">21321313546121</a>",
        "site_link": "<a href=\"https://56421684464\" target=\"_blank\" style=\"text-decoration: none;\">641546514421</a>"
      },
      "show_contact": 1,
      "shop_close": 0,
      "shop_logo": "https://fast.qqss.net/upload/image/20251122/76a99779d8bd480e4e45208c4dda5f5b_692164eae77d8.png",
      "shop_notice_show": 1,
      "shop_notice": "",
      "show_merchant_time": 1
    },
    "extension": {
      // 扩展预留项，暂时无特殊用途。演示站实现了在线音乐播放
      "music": {
        "server": "netease",
        "type": "playlist",
        "music_id": "8152976493",
        "autoplay": 1,
        "delay": 1.5
      }
    },
    "categorys": [
      {
        "id": 5,
        "user_id": 1004,
        "name": "测试",
        "sort": 5,
        "status": 1,
        "create_at": "2025-11-23 14:56:58",
        "pid": 0,
        "goodsCount": 2
      },
      {
        "id": 4,
        "user_id": 1004,
        "name": "11111111",
        "sort": 4,
        "status": 1,
        "create_at": "2025-11-22 15:57:25",
        "pid": 0,
        "goodsCount": 1
      }
    ],
    "pcTemplate": "default",
    "feeRate": 0.05,
    "isFavorited": false
  }
}

错误响应示例：

json
{
  "code": 0,
  "msg": "店铺不存在" // 其他错误响应也是仅msg不同
}

字段说明：

根级别字段：

  • token：店铺号
  • shop：店铺基本信息
  • extension：店铺扩展信息（如音乐播放器配置等）
  • categorys：店铺商品分类列表
  • feeRate：商品费率（0.05 表示 5%）
  • isFavorited：当前用户是否已关注该店铺

shop（店铺信息）：

  • id：店铺 ID
  • user_id：商家用户 ID
  • shop_name：店铺名称
  • shop_logo：店铺 Logo 图片 URL
  • stock_display：库存显示方式（参考商户手册部分）
  • merchant_time：商家开通时间（时间戳）
  • show_merchant_time：是否显示商家开通时间（0-不显示，1-显示）
  • shop_contact：店铺联系方式对象
    • qq：QQ 号
    • wechat：微信号
    • mobile：手机号
    • site_link：网站链接
  • show_contact：是否显示联系方式（0-不显示，1-显示）
  • shop_close：店铺是否歇业（0-营业中，1-已歇业）
  • shop_notice：店铺公告内容
  • shop_notice_show：是否显示店铺公告弹窗（0-不显示，1-显示）

extension（扩展信息）：

  • music：音乐播放器配置（可选）
    • server：音乐服务器（如：netease-网易云音乐）
    • type：播放类型（如：playlist-歌单）
    • music_id：音乐/歌单 ID
    • autoplay：是否自动播放（0-否，1-是）
    • delay：延迟播放时间（秒）

categorys（分类列表）：

  • id：分类 ID
  • user_id：商家用户 ID
  • name：分类名称
  • sort：排序值（降序）
  • status：分类状态（1-启用）
  • create_at：创建时间
  • pid：父分类 ID（0 表示顶级分类）
  • goodsCount：该分类下的商品数量

说明：

  • 前端会根据 pcTemplate 或 mobileTemplate 动态加载对应的主题组件 【作废】
  • 如果 categorys 为空，前端会显示错误提示"请添加商品分类后重试！"
  • 如果 shop_notice_show=1 且 shop_notice 不为空，前端会显示店铺公告弹窗
  • 如果 extension.music 存在，前端会加载音乐播放器组件
  • feeRate 用于计算商品手续费，实际支付金额 = 商品金额 × (1 + feeRate)

2. 获取店铺商品列表 ​

接口地址：/home/shop/getGoodsList

请求参数：

参数名类型必填说明
tokenString是店铺号
cate_idInteger否分类 ID，不传则获取第一个分类的商品
limitInteger否每页数量，默认 8
pageInteger否页码，默认 1

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 4,
        "user_id": 1004,
        "name": "测试v",
        "price": "111.00",
        "wholesale_discount": 0,
        "wholesale_discount_list": [
          {
            "num": 100,
            "price": 20
          }
        ],
        "limit_quantity_max": 0,
        "limit_quantity": 1,
        "content": "<p>等等等等等等的学习学习宣传休息休息休息休息休息处休息休息休息休息休息休息休息休息 &nbsp; &nbsp; &nbsp; </p>",
        "event_give": [
          {
            "num": 10,
            "give_num": 0.1
          },
          {
            "num": 20,
            "give_num": 2
          }
        ],
        "addtion_give": [
          {
            "good_id": "",
            "bug_num": 10,
            "give_num": 2,
            "goods_name": null
          }
        ],
        "stock": 53,
        "stockStr": "很多",
        "is_favorited": false
      }
    ],
    "total": 1
  }
}

字段说明：

基础字段：

  • id：商品 ID
  • user_id：商家用户 ID
  • name：商品名称
  • price：商品单价
  • content：商品详情（HTML 格式）
  • stock：商品可用库存数量
  • stockStr：库存显示文本（根据商家设置可能显示具体数量或"充足"、"很多"等）
  • is_favorited：当前用户是否已收藏该商品

限购设置：

  • limit_quantity：最小购买数量（0-不限购）
  • limit_quantity_max：最大购买数量（0-不限购）

批发折扣：

  • wholesale_discount：是否开启批发折扣（0-不开启，1-开启）
  • wholesale_discount_list：批发折扣列表（数组）
    • num：购买数量达到此值时享受折扣
    • price：折扣后的单价

活动赠送：

  • event_give：叠加赠送列表（数组，买 N 送 M）
    • num：购买数量达到此值
    • give_num：赠送数量（每买 num 张赠送 give_num 张）

额外赠送：

  • addtion_give：附加赠送其他商品列表（数组）
    • good_id：赠品商品 ID
    • goods_name：赠品商品名称
    • bug_num：购买数量达到此值
    • give_num：赠送该商品的数量

说明：

  • 只返回状态为 1（上架）且 show_option=1 的商品
  • 商品按 sort 降序、id 降序排列
  • 如果不传 cate_id，默认获取第一个分类的商品
  • wholesale_discount_list、event_give、addtion_give 为空时返回空数组 []
  • 批发折扣：购买数量达到 num 时，单价变为 price
  • 叠加赠送：购买数量达到 num 的倍数时，每 num 张赠送 give_num 张同商品
  • 附加赠送：购买数量达到 bug_num 时，额外赠送 give_num 张指定的其他商品

3. 获取店铺分类列表 ​

接口地址：/home/shop/getCategoryList

请求参数：

参数名类型必填说明
tokenString是店铺号

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 116,
        "user_id": 1000,
        "name": "222",
        "sort": 116,
        "status": 1,
        "create_at": "2025-11-07 16:43:50",
        "pid": 0,
        "goodsCount": 2
      },
      {
        "id": 113,
        "user_id": 1000,
        "name": "栏目1",
        "sort": 113,
        "status": 1,
        "create_at": "2025-10-29 12:17:55",
        "pid": 0,
        "goodsCount": 1
      }
    ]
  }
}

字段说明：

  • id：分类 ID
  • user_id：商家用户 ID
  • name：分类名称
  • sort：分类排序值（按降序排列）
  • status：分类状态（1-启用）
  • create_at：创建时间
  • pid：父分类 ID（0 表示顶级分类）
  • goodsCount：该分类下的商品数量

4. 获取商品详情 ​

接口地址：/home/shop/getGoodsDetail

请求参数：

参数名类型必填说明
tokenString是店铺号
goods_idInteger是商品 ID

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "id": 1,
    "user_id": 1000,
    "name": "1000的商品1",
    "price": "15.00",
    "wholesale_discount": 0,
    "wholesale_discount_list": [],
    "limit_quantity_max": 0,
    "limit_quantity": 0,
    "content": "<p><span style=\"color: rgba(0, 0, 0, 0.9); background-color: rgb(255, 255, 255); font-size: 12px;\">商品描述q</span></p>",
    "event_give": [],
    "addtion_give": [],
    "shop": {
      "id": 2,
      "user_id": 1000,
      "shop_name": "1001小店",
      "stock_display": 2,
      "merchant_time": 1763483381,
      "shop_contact": {
        "qq": "",
        "wechat": "",
        "mobile": "",
        "site_link": ""
      },
      "show_contact": 0,
      "shop_close": 0,
      "shop_logo": "",
      "shop_notice_show": 0,
      "shop_notice": "",
      "show_merchant_time": 0
    },
    "stockStr": "充足",
    "is_favorited": false
  }
}

错误响应示例：

json
{
  "code": 0,
  "msg": "参数错误"
}
json
{
  "code": 0,
  "msg": "商品不存在或已下架"
}

字段说明：

商品基础信息：

  • id：商品 ID
  • user_id：商家用户 ID
  • name：商品名称
  • price：商品售价
  • content：商品详情（HTML 格式）

库存相关：

  • stock：商品可用库存数量（动态计算）
  • stockStr：库存显示文本（根据商家设置显示具体数量或"充足"、"缺货"等）

限购设置：

  • limit_quantity：是否限购（0-不限购，1-限购）
  • limit_quantity_max：限购数量（limit_quantity=1 时有效）

批发折扣：

  • wholesale_discount：是否开启批发折扣（0-不开启，1-开启）
  • wholesale_discount_list：批发折扣列表（数组）
    • num：购买数量达到此值时享受折扣
    • price：折扣后的单价

活动赠送：

  • event_give：叠加赠送列表（数组，买 N 送 M）
    • num：购买数量达到此值
    • give_num：赠送数量
  • addtion_give：附加赠送其他商品列表（数组）
    • good_id：赠品商品 ID
    • goods_name：赠品商品名称
    • bug_num：购买数量达到此值
    • give_num：赠送该商品的数量

其他字段：

  • is_favorited：当前用户是否已收藏该商品

说明：

  • 商品必须属于指定的店铺（通过 token 验证）
  • 只能查询状态为 1（上架）的商品
  • stock 是动态计算的可用库存数量
  • 库存显示根据 shop.stock_display 设置：0-不显示，1-显示具体数量，2-显示文字描述（如"充足"、"缺货"）
  • content 为 HTML 格式，需要前端渲染
  • wholesale_discount_list、event_give、addtion_give 为空时返回空数组 []
  • 批发折扣：购买数量达到 num 时，单价变为 price
  • 叠加赠送：购买数量达到 num 的倍数时，每 num 张赠送 give_num 张同商品
  • 附加赠送：购买数量达到 bug_num 时，额外赠送 give_num 张指定的其他商品

5. 切换商品收藏状态 ​

接口地址：/home/favorite/toggleGoodsFavorite

认证：需要登录

请求参数：

参数名类型必填说明
goods_idInteger是商品 ID

成功响应示例：

json
{
  "code": 1,
  "msg": "收藏成功",
  "data": {
    "is_favorited": true
  }
}
json
{
  "code": 1,
  "msg": "取消收藏成功",
  "data": {
    "is_favorited": false
  }
}

错误响应示例：

json
{
  "code": 0,
  "msg": "参数错误"
}
json
{
  "code": 0,
  "msg": "商品不存在或已下架"
}

说明：

  • 如果已收藏则取消收藏，未收藏则添加收藏
  • is_favorited 返回操作后的收藏状态

6. 切换店铺关注状态 ​

接口地址：/home/favorite/toggleShopFavorite

认证：需要登录

请求参数：

参数名类型必填说明
shop_idInteger是店铺 ID

成功响应示例：

json
{
  "code": 1,
  "msg": "关注成功",
  "data": {
    "is_favorited": true
  }
}
json
{
  "code": 1,
  "msg": "取消关注成功",
  "data": {
    "is_favorited": false
  }
}

错误响应示例：

json
{
  "code": 0,
  "msg": "参数错误"
}
json
{
  "code": 0,
  "msg": "店铺不存在或已关闭"
}

说明：

  • 如果已关注则取消关注，未关注则添加关注
  • is_favorited 返回操作后的关注状态

7. 获取收藏的商品列表 ​

接口地址：/home/favorite/goodsList

认证：需要登录

请求参数：

参数名类型必填说明
pageInteger否页码，默认 1
limitInteger否每页数量，默认 10

响应示例：

json
{
    "code": 1,
    "msg": "获取成功",
    "data": {
        "list": [
            {
                "id": 13,
                "user_id": 1000,
                "relation_id": 1,
                "type": 1,
                "create_time": "2025-11-28 13:08:46",
                "update_time": "2025-11-28 13:08:46",
                "goods_name": "1000的商品1",
                "goods_price": "15.00",
                "goods_status": 1,
                "goods_id": 1,
                "goods_url": "/goods-detail/5483/1"
            }
        ],
        "total": 1
    }
}

字段说明：

收藏记录字段：

  • id：收藏记录 ID
  • user_id：用户 ID
  • relation_id：关联的商品 ID
  • type：收藏类型（1-商品）
  • create_time：收藏时间
  • update_time：更新时间
  • goods_id：商品 ID（与 relation_id 相同）
  • goods_url：商品详情页地址（前端路由格式：/goods-detail/{店铺token}/{商品ID}）

说明：

  • 收藏列表按收藏时间倒序排列（最新收藏的在前）
  • goods_url 格式为 /goods-detail/{店铺token}/{商品ID}，用于前端路由跳转
  • 如果商品已被删除或不存在，goods 字段可能为 null
  • 代理商品的 is_proxy=1，可通过 source_user_id 追溯到源头商家
  • status=0 表示商品已下架，前端可显示"已下架"标识
  • stock_quantity=0 表示商品无库存，前端可显示"缺货"标识

8. 获取关注的店铺列表 ​

接口地址：/home/favorite/shopList

认证：需要登录

请求参数：

参数名类型必填说明
pageInteger否页码，默认 1
limitInteger否每页数量，默认 10

响应示例：

json
{
    "code": 1,
    "msg": "获取成功",
    "data": {
        "list": [
            {
                "id": 12,
                "user_id": 1000,
                "relation_id": 2,
                "type": 2,
                "create_time": "2025-11-28 13:01:58",
                "update_time": "2025-11-28 13:01:58",
                "shop_name": "1001小店",
                "goods_count": 1,
                "shop_link": "https://fast.qqss.net/link/5483"
            }
        ],
        "total": 1
    }
}

字段说明：

  • id：关注记录 ID
  • user_id：用户 ID
  • relation_id：关联的店铺 ID
  • type：关注类型（2-店铺）
  • create_time：关注时间
  • update_time：更新时间
  • goods_count：店铺商品数量
  • shop_link：店铺访问链接（完整 URL）

说明：

  • 关注列表按关注时间倒序排列（最新关注的在前）
  • shop_link 为店铺的完整访问链接，可直接用于跳转
  • goods_count 统计店铺当前的商品总数
  • 如果店铺已被删除或关闭，相关信息可能为空