开放 API 文档 · 千里香商城

接入说明

Base URL：http://127.0.0.1:8090/api/open；如果部署在域名或反向代理后，请替换为实际地址。所有接口返回 JSON，成功为 {"ok": true}，失败为 {"ok": false, "error": "错误说明"}。

API Key 可在「管理后台 → API 对接」查看与重置。请勿把 Key 写入前端代码、公开仓库或可被用户下载的文件。

每个请求都必须在 Header 中携带：

X-API-Key: zk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

建议门店系统通过固定出口 IP 调用；生产环境可在 Nginx 层增加 IP 白名单、HTTPS 与限流。

GET/api/open/health

curl http://127.0.0.1:8090/api/open/health \
  -H "X-API-Key: zk_xxx"

POST/api/open/members/sync

{
  "phone": "13800138000",
  "nickname": "门店会员",
  "points": 5000,
  "level": 2,
  "store_member_id": "STORE-10086"
}

接口按手机号幂等：存在则更新，不存在则创建。返回的 created 表示是否新建。

POST/api/open/members/points

增量增加 / 扣减（最低为 0）：

{
  "phone": "13800138000",
  "points_delta": 200,
  "reason": "门店消费赠送"
}

设置为绝对值：

{
  "phone": "13800138000",
  "action": "set",
  "points": 5000,
  "reason": "月度积分结转"
}

GET/api/open/members/{phone}

返回会员积分、余额、等级、邀请码、门店会员 ID 与账号状态。

POST/api/open/members/token

{
  "phone": "13800138000",
  "next": "/me"
}

返回 7 天有效的 Token 与 login_url，可直接跳转商城自动登录：

http://127.0.0.1:8090/#/sso?token=...&next=%2Fme

GET/api/open/products?type=mall

type 支持 mall（商城商品）与 exchange（积分兑换）。返回商品 ID、名称、价格、积分、库存、销量与图片地址。

GET/api/open/orders?phone=13800138000

返回最近 50 笔订单，含订单号、状态、金额、商品明细与物流信息，可用于门店客服查询。

每期活动有 total_shares 个连续号码。份额售罄时服务端在同一事务内自动开奖：

seed = "{cloud_id}:{total_shares}:{last_order_no}:{sum_order_ms}:{last_order_ms}"
hash = SHA-256(seed)
lucky = int(hash[0:16], 16) % total_shares + 1