zhaogd/as-daycard-openapi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
30198c7191c15bf6d838415e27f3e2bf59bed915
as-daycard-openapi/API_DOC.md
zhaogd 30198c7191 初始化天卡开放平台后端项目 
包含完整功能模块：
- 设备激活（直销激活码模式 + 代销免激活码模式）
- 微信支付 + 天卡订单
- 天卡池管理 + 异步橘视厅SDK激活
- 第三方合作伙伴接口（代销模式）
  - 签名鉴权（appKey/appSecret + nonce防重放）
  - 天卡消耗（事务 + 幂等 + 并发控制）
  - 媒资接口（三级授权过滤）
  - 审计日志
- 定价策略（3层：门店 > 渠道 > 平台）
- 分账（微信分账 + 分润规则）
- Docker部署（含Redis容器）
2026-07-26 12:34:13 +08:00

15 KiB
Raw Blame History

天卡开放平台 · 接口对接文档

项目：as-daycard-openapi | 端口：8084 | 更新：2026-07-22

一、统一规范

返回格式（所有接口统一）

{"code": 0, "msg": "success", "data": {...}}
  • code=0 成功，非0失败
  • data 业务数据，统一放在 data 字段内
  • 错误时：{"code": 错误码, "msg": "错误信息", "data": {}}

接口分类

分类 路径前缀 鉴权 请求头 调用方
管理后台 /manage/**、/sys/login JWT token 浏览器前端
第三方开放 /openapi/partner/** appKey签名 appKey/timestamp/nonce/sign 第三方EPG
APK设备 /api/jst/** 设备sign sign 我们APK
支付回调 /openapi/payment/**、/openapi/settle/** 无 - 微信服务器

二、管理后台接口（JWT鉴权）

鉴权：请求头 token: <登录返回的token>
登录：POST /sys/login（免鉴权）返回 token
返回：{code:0, msg:"success", data:{...}}

2.1 登录鉴权

路径 方法 说明
POST /sys/login POST 登录（username/password/uuid/captcha），返回token+refreshToken
POST /sys/refresh POST 刷新token（refreshToken）
POST /sys/logout POST 退出登录
GET /captcha.jpg GET 验证码图片（参数uuid）

2.2 用户管理 /manage/user

路径 方法 说明
/manage/user/list GET 用户列表（分页）
/manage/user/info GET 当前登录用户信息
/manage/user/info/{userId} GET 用户详情
/manage/user/save POST 保存用户
/manage/user/update POST 修改用户
/manage/user/delete POST 删除用户
/manage/user/password POST 修改密码

2.3 角色管理 /manage/role

路径 方法 说明
/manage/role/list GET 角色列表
/manage/role/select GET 角色下拉
/manage/role/info/{roleId} GET 角色详情（含menuIdList）
/manage/role/save POST 保存角色
/manage/role/update POST 修改角色
/manage/role/delete POST 删除角色

2.4 菜单管理 /manage/menu

路径 方法 说明
/manage/menu/nav GET 当前用户菜单+权限
/manage/menu/list GET 菜单列表
/manage/menu/select GET 菜单下拉
/manage/menu/info/{menuId} GET 菜单详情
/manage/menu/save POST 保存菜单
/manage/menu/update POST 修改菜单
/manage/menu/delete/{menuId} POST 删除菜单

2.5 组织管理 /manage/org

路径 方法 说明
/manage/org/list GET 组织列表（树）
/manage/org/tree GET 组织树（下拉）
/manage/org/all-tree GET 组织树（含门店）
/manage/org/list-data GET 组织列表（扁平）
/manage/org/channels GET 渠道列表
/manage/org/channel/{channelId}/agent-tree GET 渠道下代理树
/manage/org/{orgId}/card-stats GET 组织卡统计
/manage/org/card-type-detail-stats GET 卡类型明细统计
/manage/org/card-overview GET 组织卡概览
/manage/org/{orgId}/same-channel-orgs GET 同渠道组织树
/manage/org/info/{id} GET 组织详情
/manage/org/save POST 保存组织
/manage/org/update POST 修改组织
/manage/org/delete POST 删除组织

2.6 门店管理 /manage/store

路径 方法 说明
/manage/store/list GET 门店列表
/manage/store/list-by-agent/{agentOrgId} GET 按代理商列门店
/manage/store/search GET 门店搜索（分页）
/manage/store/{storeOrgId}/cards GET 门店绑定卡列表

2.7 合同权益 /manage/contract

路径 方法 说明
/manage/contract/by-store POST 按门店查权益激活码

2.8 天卡激活码 /manage/daycard/activation-code

路径 方法 说明
/manage/daycard/activation-code/list/{storeOrgId} GET 按门店查激活码
/manage/daycard/activation-code/generate POST 生成激活码
/manage/daycard/activation-code/{id}/regenerate POST 重新生成code
/manage/daycard/activation-code/{id}/status PUT 启用/禁用
/manage/daycard/activation-code/{id} DELETE 删除激活码

2.9 天卡管理 /manage/daycard

路径 方法 说明
/manage/daycard/pool/list GET 天卡池列表
/manage/daycard/pool/stats GET 库存统计
/manage/daycard/pool/import POST 导入天卡卡密
/manage/daycard/order/list GET 天卡订单列表
/manage/daycard/list GET 天卡订单列表
/manage/daycard/info/{orderNo} GET 订单详情
/manage/daycard/benefits/{deviceId} GET 设备天卡权益
/manage/daycard/device/unbind POST 解绑设备天卡
/manage/daycard/device/unbind-org POST 设备组织解绑

2.10 天卡定价 /manage/price

路径 方法 说明
/manage/price/list GET 定价策略列表
/manage/price/info/{id} GET 定价详情
/manage/price/effective GET 生效中定价（门店>渠道>平台）
/manage/price/save POST 新增定价
/manage/price/update POST 修改定价
/manage/price/delete POST 删除定价

2.11 天卡退款 /manage/refund

路径 方法 说明
/manage/refund/list GET 退款记录列表
/manage/refund/info/{refundNo} GET 退款详情
/manage/refund/apply POST 发起退款（orderNo+reason）

2.12 分润规则 /manage/profit-rule

路径 方法 说明
/manage/profit-rule/list GET 分润规则列表
/manage/profit-rule/info/{id} GET 规则详情（含items）
/manage/profit-rule/save POST 新增分润规则
/manage/profit-rule/update POST 修改分润规则
/manage/profit-rule/delete POST 删除分润规则
/manage/profit-rule/preview POST 分润试算（超30%告警）

2.13 分账查询 /manage/profit-sharing

路径 方法 说明
/manage/profit-sharing/list GET 分账单列表（含details）
/manage/profit-sharing/info/{id} GET 分账单详情
/manage/profit-sharing/stats GET 分账统计（按日期/组织）

2.14 分账接收方 /manage/profit-receiver

路径 方法 说明
/manage/profit-receiver/list GET 接收方列表
/manage/profit-receiver/info/{id} GET 接收方详情
/manage/profit-receiver/save POST 新增接收方
/manage/profit-receiver/delete POST 删除接收方
/manage/profit-receiver/sync/{id} POST 同步到微信

2.15 设备管理 /manage/device

路径 方法 说明
/manage/device/list GET 设备列表
/manage/device/info/{id} GET 设备详情
/manage/device/save POST 新增设备
/manage/device/update POST 修改设备
/manage/device/delete POST 删除设备
/manage/device/bindStore POST 绑定门店

2.16 支付配置 /manage/payconfig

路径 方法 说明
/manage/payconfig/list GET 支付配置列表
/manage/payconfig/info/{id} GET 配置详情
/manage/payconfig/save POST 新增配置
/manage/payconfig/update POST 修改配置
/manage/payconfig/delete POST 删除配置

2.17 统计看板 /manage/stats

路径 方法 说明
/manage/stats/overview GET 总览看板
/manage/stats/orders GET 订单趋势（startDate/endDate）
/manage/stats/pool GET 库存统计
/manage/stats/channels GET 渠道统计

2.18 橘视厅媒资 /manage/jetsen-media

路径 方法 说明
/manage/jetsen-media/nav GET 首页导航
/manage/jetsen-media/tags GET 栏目标签（parentid）
/manage/jetsen-media/catalog-tree GET 栏目树（一级+二级）
/manage/jetsen-media/list GET 内容列表（catalogid必填）
/manage/jetsen-media/search GET 搜索（keyword）
/manage/jetsen-media/export GET 导出Excel

2.19 合作伙伴管理 /manage/partner

路径 方法 说明
/manage/partner/list GET 合作伙伴列表
/manage/partner/info/{id} GET 合作伙伴详情
/manage/partner/save POST 新增（自动生成appKey/appSecret）
/manage/partner/update POST 修改
/manage/partner/delete POST 删除

2.20 内容包管理 /manage/content-package

路径 方法 说明
/manage/content-package/list GET 内容包列表
/manage/content-package/info/{id} GET 内容包详情
/manage/content-package/info-by-partner/{partnerId} GET 按partner查内容包
/manage/content-package/save POST 新增内容包
/manage/content-package/update POST 修改内容包
/manage/content-package/delete POST 删除内容包

2.21 天卡采购 /manage/partner-card

路径 方法 说明
/manage/partner-card/purchase POST 采购天卡（partnerId+quantity）
/manage/partner-card/stock GET partner库存查询
/manage/partner-card/list GET 池子记录分页

三、第三方开放接口（appKey签名鉴权）

鉴权说明

签名算法：sign = MD5(appKey + timestamp + nonce + appSecret).toUpperCase()

请求头：

请求头 说明
appKey 平台分配的应用Key
timestamp 毫秒时间戳（5分钟有效）
nonce 随机串（5分钟防重放）
sign 签名（大写MD5）

返回：{code:0, msg:"", data:{...}}
鉴权失败：HTTP 401 {code:401, msg:"错误描述"}

3.1 媒资接口 /openapi/partner/media

三级授权：CONTENT(单部内容) > CATALOG(栏目) > FULL(全量)

路径 方法 参数 说明
/openapi/partner/media/package GET 无 查看授权范围
/openapi/partner/media/catalog-tree GET 无 栏目树（按授权过滤）
/openapi/partner/media/list GET catalogid,pageindex,pagesize 内容列表（按授权过滤）
/openapi/partner/media/search GET keyword,pageindex,pagesize 搜索（按授权过滤）

3.2 天卡代销 /openapi/partner/card

路径 方法 参数 说明
/openapi/partner/card/consume POST body:{mac,deviceUid,deviceSn,channelOrgId} 消耗天卡：分配1张绑定设备+异步激活
/openapi/partner/card/stock GET 无 我的可用天卡库存

consume返回：

{"code":0,"msg":"","data":{"deviceId":123,"thirdCardNo":"xxx","cardCode":"xxx","expireAt":"...","status":"ACTIVE"}}

四、APK设备接口（设备sign鉴权）

鉴权说明

  • sign获取：POST /api/jst/init 返回sign（在data内）
  • sign校验：后续请求头携带 sign
  • 免sign接口：POST /api/jst/init
  • 返回：{code:0, msg:"success", data:{...}}

4.1 设备接口 /api/jst

路径 方法 鉴权 说明
/api/jst/init POST 无 设备初始化，返回sign。代销模式：不传activationCode时按设备标识查找已注册设备
/api/jst/checkBenefits POST sign 查询天卡权益（ACTIVE返回thirdCardNo/UNBOUND）
/api/jst/price POST sign 查询天卡价格（3层匹配）
/api/jst/daycard/create POST sign 创建天卡订单（返回codeUrl二维码）
/api/jst/daycard/status/{orderNo} GET sign 查询支付状态
/api/jst/heartBeat POST sign 心跳续期sign
/api/jst/refreshSign POST sign 刷新sign（旧sign失效）

init请求体：

{"activationCode":"激活码(代销模式不传)","mac":"设备MAC","deviceUid":"设备标识","deviceSn":"序列号"}

init返回：

{"code":0,"msg":"success","data":{"device":{"deviceId":123,"roomNo":"001"},"sign":"xxx"}}

4.2 UI数据接口 /api/jst

路径 方法 说明
/api/jst/topButtons POST 顶栏按钮（logo/搜索/帮助）
/api/jst/filter/tags POST 筛选分类（栏目/类型/地区/年代）
/api/jst/filter/content POST 筛选内容列表
/api/jst/config GET 独立配置（logoUrl+loginBg）

4.3 APK调用流程

正常模式：init(activationCode) -> checkBenefits -> 无权益则price+create+支付+status -> checkBenefits拿thirdCardNo播放
代销模式：第三方consume消耗天卡 -> APK init(免activationCode,传设备标识) -> checkBenefits拿thirdCardNo播放

五、支付回调接口（微信服务器调用）

路径 方法 说明
/openapi/payment/wechat/notify POST 微信支付回调（验签+发卡）
/openapi/payment/notify POST 微信支付回调（旧路径兼容）
/openapi/payment/refund/notify POST 微信退款回调
/openapi/payment/wechat/profit-sharing/notify POST 微信分账回调（明细级）
/openapi/settle/notify POST 微信分账回调（结算级）

六、路径变更对照表（前端适配用）

旧路径 新路径
/sys/user/** /manage/user/**
/sys/role/** /manage/role/**
/sys/menu/** /manage/menu/**
/sys/org/** /manage/org/**
/sys/store/** /manage/store/**
/sys/contract/** /manage/contract/**
/sys/jetsen-media/** /manage/jetsen-media/**
/openapi/partner/list /manage/partner/list
/openapi/partner/info/** /manage/partner/info/**
/openapi/partner/save /manage/partner/save
/openapi/partner/update /manage/partner/update
/openapi/partner/delete /manage/partner/delete
/openapi/daycard/pool/** /manage/daycard/pool/**（已有，DayCardPoolController已删）
/sys/login /sys/login（不变）
/sys/refresh /sys/refresh（不变）
/sys/logout /sys/logout（不变）

七、返回格式变更对照

接口类型 旧格式 新格式
APK设备 {code:200, msg:"success", data:{...}} {code:0, msg:"success", data:{...}}
APK UI {retCode:"00000000", data:{...}} {code:0, msg:"success", data:{...}}
APK init {code:200,...,data:{device:{}},sign:"xxx"} {code:0,...,data:{device:{},sign:"xxx"}}
管理后台 {code:0, msg:"success", page:{...}} {code:0, msg:"success", data:{page:{...}}}