logan

Appearance

1. 获取店铺首页信息 ​

接口地址：/home/shop

请求参数：

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

变更记录：2026-1-30 移除 show_contact；shop_contact改为文本

成功响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "token": "1111",
    "shop": {
      "id": 4,
      "user_id": 1004,
      "shop_name": "ovo小店",
      "stock_display": 2,
      "merchant_time": 1763795563,
      "shop_contact": "",
      "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,
    "minimumFee": 0.01,
    "isFavorited": false
  }
}

错误响应示例：

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

字段说明：

根级别字段：

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

shop（店铺信息）：

  • id：店铺 ID
  • user_id：商家用户 ID
  • shop_name：店铺名称
  • shop_logo：店铺 Logo 图片 URL
  • stock_display：库存显示方式（参考商户手册部分）
  • merchant_time：商家开通时间（时间戳）
  • show_merchant_time：是否显示商家开通时间（0-不显示，1-显示）
  • shop_contact：""
  • 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 计算并保留 3 位小数，低于 minimumFee 时按 minimumFee 收取
  • 实际支付金额 = 商品金额 + 订单服务费

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，返回店铺内所有状态为 1 且 show_option=1 的商品
  • 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

变更记录：2026-1-30 移除 show_contact；shop_contact改为文本

响应示例：

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": "",
      "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 表示不限最小购买数量
  • limit_quantity_max：最大购买数量，0 表示不限最大购买数量

批发折扣：

  • 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 （使用收藏列表中的 relation_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 （使用收藏列表中的 relation_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",
                "shop_name": "xxxx", // 商品所属店铺的店铺名  （新增于 2026-02-03）
                "shop_no": "88888", // 店铺号  （新增于 2026-02-03）
                "goods_is_freeze": 0, // 商品是否被冻结 1=冻结 0=正常 （新增于 2026-02-05）
                "is_lose": 0, // 商品是否失效 1=失效 0=正常 （新增于 2026-02-05）
                "is_lose_text": "" // 商品失效文案 （新增于 2026-02-05）
            }
        ],
        "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}）
  • shop_name：店铺名 （新增于 2026-02-03）
  • shop_no：店铺号 （新增于 2026-02-03）
  • goods_is_freeze：商品是否被冻结 1=冻结 0=正常 （新增于 2026-02-05）
  • is_lose：商品是否失效 1=失效 0=正常 （新增于 2026-02-05）
  • is_lose_text：商品失效文案 （新增于 2026-02-05）

说明：

  • 收藏列表按收藏时间倒序排列（最新收藏的在前）
  • 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",
                "is_lose": 0, // 店铺是否失效 1=失效 0=正常 （新增于 2026-02-05 , 此值为1时 上面部分数据可能不返回，前端可用形式 data?.shop_name || '数据已经失效' 做默认数据）
                "is_lose_text": "" // 店铺失效文案 （新增于 2026-02-05）
            }
        ],
        "total": 1
    }
}

字段说明：

  • id：关注记录 ID
  • user_id：用户 ID
  • relation_id：关联的店铺 ID
  • type：关注类型（2-店铺）
  • create_time：关注时间
  • update_time：更新时间
  • goods_count：店铺商品数量
  • shop_link：店铺访问链接（完整 URL）
  • is_lose：店铺是否失效 1=失效 0=正常 （新增于 2026-02-05）
  • is_lose_text：店铺失效文案 （新增于 2026-02-05）

说明：

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

9. 强制删除收藏数据 ​

  • 新增于 2026-02-05

接口地址：/home/favorite/forceDeleteFavorite

认证：需要登录

请求参数：

参数名类型必填说明
idInteger是收藏记录 ID

成功响应示例：

json
{
  "code": 1,
  "msg": "删除成功"
}

错误响应示例：

json
{
  "code": 0,
  "msg": "参数错误"
}
json
{
  "code": 0,
  "msg": "..." // 其他错误响应也是仅msg不同
}

说明：

  • 强制删除收藏记录，不会触发任何逻辑，只是删除数据。建议收藏列表中存在 is_close为1时，使用此接口进行删除。

V3 最近访问与分享 ​

成功加载 /home/shop 自动记录当前用户最近访问；读取与快捷管理使用 /home/client/access、pinShop、clearRecent。新增 /home/shop/share 提供来自 shop_intro 的分享描述，V3 仅在分享页展示。详见 V3账户与访问设置。

店铺分享（2026-10-09） ​

POST /home/shop/share：参数 token（店铺号），返回 shop_no、shop_name、shop_logo、description。description 来自店铺 shop_intro，去除 HTML 并保留段落。H5 使用 简介 + 空行 + 店铺链接：URL。

POST /home/shop/prepareShare：需要用户登录，参数 token、init_data（Telegram 原始签名数据）、app_url（用户端 Mini App 的 t.me 入口）。后端校验签名、Telegram 用户与登录用户一致，以及入口机器人与 BOT_APP_TOKEN 的 getMe 用户名一致。

成功返回 data: { id: "prepared-message-id", expiration_date: 1900000000 }。前端调用 Telegram 8.0+ WebApp.shareMessage(id, callback)，由用户选择聊天并确认发送。卡片正文为店铺简介，底部按钮为“访问店铺”，链接由后端生成 https://t.me/机器人/应用名?startapp=shop_店铺号。简介为空使用店铺名，超过 TG 4096 字符限制则截断并加省略号。

使用用户端 BOT_APP_TOKEN，不能使用商户通知机器人的 telegram_bot_token。前端入口配置为 VITE_APP_SHARE_URL，H5 入口配置为 VITE_WEB_SHARE_URL。本功能需要前后端一起发布，无数据库变更。