极客场馆开放平台 · 约课接口

版本 v1 · 配套文档：加密与签名接入 · 通用约定与错误码 所有路径前缀 https://www.gymker.com/api/open/v1。响应/错误码/幂等/限流见通用约定。

---

1. 能力总览

能力	scope	典型用途
约课记录列表	booking:read	拉某时段会员预约情况

每个 AppId 只对应一家门店，所有接口自动按该门店过滤。

---

2. 约课记录列表 · GET /bookings

按预约创建时间拉取约课记录，合并三类预约模型，统一列表 + bookingType 字段。scope booking:read。

Query	类型	必填	说明
startDate	yyyy-MM-dd	是	createTime >= startDate
endDate	yyyy-MM-dd	是	createTime <= endDate
memberId	long	否	按会员过滤
bookingType	string	否	不传查全部；group（团课）/ small（小班）/ private（私教）。与 排课接口 的 scheduleType 同一套词汇
page / size	int	否	默认 1 / 20，size ≤ 100

startDate / endDate 必填，跨度 ≤ 90 天。data：{ records[], total, current, size }，按预约创建时间倒序。

records[] 单元素：

{
  "bookingType": "private",       // group（团课）/ small（小班）/ private（私教）
  "id": 88001, "memberId": 12345,
  "scheduleId": 88001,            // group→class_schedule.id；small→small_class_schedule.id；private 即排课自身 id
  "coachStaffId": 5001,           // private 才有；group / small 的预约行不带教练，为 null
  "startTime": "2026-05-22T10:00:00", // private 才有；group / small 用 scheduleId 关联 /schedules
  "endTime": "2026-05-22T11:00:00",
  "status": 2,                    // 状态码按 bookingType 对照字典，见下
  "checkinTime": null,            // 核销（签到）时间，未核销为 null
  "source": "RESPONSIBLE_COACH",  // group=bookingSource / private=initiatorType；small 恒为 null
  "cancelTime": null,
  "createTime": "2026-05-20T09:58:00"
}

status 字典（团课与小班已对齐，私教仍是另一套）

status 原样透出，先看 bookingType 再查对应这一列：

bookingType	状态字典
group 团课	1 已预约 / 2 已取消 / 3 已签到 / 4 未到场 / 5 核销失败
small 小班	1 已加入 / 2 已退出 / 3 已签到 / 4 未到场
private 私教	0 待分配 / 1 待确认 / 2 已确认 / 3 已完成 / 4 已取消 / 5 已拒绝

✅ 团课和小班的前四个值含义一致（2026-08-02 对齐）。此前小班的 2 是”已签到”、 团课的 2 是”已取消”，同一个数字含义相反，对接方极易读错；现已把小班的 2/3 对调。

仍要注意两点：小班没有 5（“核销失败”是团课兜底扣课失败才落的状态，小班兜底失败不落这个值—— 但小班同样有兜底自动扣课，别把”没有 5”读成”没有兜底”）；私教是完全独立的一套， 它的 2 是”已确认”、3 是”已完成”，别拿团课/小班的字典去读。

课次时间不在本接口，group / small 都用 scheduleId 关联 排课接口 /schedules（那边同样用 group / small 区分）。

团课和小班在业务上是两套独立系统：团课=门店排班后挑教练，小班=教练自己发起。 但扣课口径两边相同，都是”占位就扣”（预约不即时扣、核销扣、没核销的次日兜底自动扣）—— 差别在表/接口/门店参数各自独立，不在规则。对接时按两条业务线处理，别假设实现通用。