健康站接口参考

健康站接口提供附近健康站查询、预约管理、到站核验、检测报告获取等能力。接口需 JWT 用户鉴权（Authorization: Bearer <token>）， Base URL 前缀为 /api/v1/。

本页为健康站接口的完整 API 参考。产品概念介绍、业务流程、场景说明见健康站开放网络文档。

概述

Base URL：https://api.xiaobaotop.com

鉴权：所有接口需 Bearer Token，通过短信登录等方式获取。

方法	路径	说明
GET	`/api/v1/stations`	健康站列表
GET	`/api/v1/stations/nearby/list`	附近健康站（按距离排序）
GET	`/api/v1/stations/{pointsCode}`	健康站详情
GET	`/api/v1/stations/{pointsCode}/available-dates`	可预约日期
GET	`/api/v1/stations/{pointsCode}/available-time-slots`	可预约时段
POST	`/api/v1/benefit-appointments`	创建预约
GET	`/api/v1/benefit-appointments`	预约列表
POST	`/api/v1/benefit-appointments/{id}/cancel`	取消预约
POST	`/api/v1/health-station/verify-code`	到站码核验
GET	`/api/v1/health-data/station-reports`	检测报告列表

健康站列表

GET/api/v1/stations

查询参数：

参数	类型	必填	说明
`page`	integer	否	页码，默认 1
`page_size`	integer	否	每页数量，默认 20，最大 50
`city_code`	string	否	城市编码过滤
`keyword`	string	否	按名称搜索

附近健康站

GET/api/v1/stations/nearby/list

查询参数：

参数	类型	必填	说明
`lat`	number	是	纬度（WGS-84）
`lng`	number	是	经度（WGS-84）
`radius`	integer	否	搜索半径（米），默认 5000，最大 50000
`limit`	integer	否	返回数量，默认 10，最大 50

响应示例（每项含 distance_meters 字段）：

{
  "success": true,
  "code": 0,
  "data": [
    {
      "points_code": "STA001",
      "points_name": "晓葆健康站（朝阳门店）",
      "address": "北京市朝阳区朝阳门外大街 18 号",
      "lat": 39.9183,
      "lng": 116.4336,
      "distance_meters": 820,
      "business_hours": "09:00-18:00",
      "status": "active"
    }
  ]
}

健康站详情

GET/api/v1/stations/{pointsCode}

返回健康站完整信息，包含设备列表、服务项目、评价统计、营业时间等。

路径参数	类型	说明
`pointsCode`	string	健康站编码（如 `STA001`）

可预约日期

GET/api/v1/stations/{pointsCode}/available-dates

返回未来 30 天内有可用时段的日期列表（YYYY-MM-DD 数组）。

可预约时段

GET/api/v1/stations/{pointsCode}/available-time-slots

查询参数：

参数	类型	必填	说明
`date`	string	是	日期，格式 `YYYY-MM-DD`

返回当日各时段的剩余可预约名额。

创建预约

POST/api/v1/benefit-appointments

请求体：

字段	类型	必填	说明
`points_code`	string	是（健康站预约）	健康站编码
`appointment_time`	string	是	预约时间，ISO8601 格式，须晚于当前时间
`appointment_type`	string	是	`HEALTH_STATION` 或 `GENERAL`
`family_member_id`	integer	是	家庭成员 ID（为谁预约）
`user_benefit_item_id`	integer	否	使用权益卡的权益项 ID
`notes`	string	否	备注，最长 1000 字符

成功响应（201 Created）：

{
  "success": true,
  "code": 0,
  "data": {
    "appointment_id": 50001,
    "appointment_no": "APT202604010001",
    "status": "confirmed",
    "appointment_time": "2026-04-10T10:00:00+08:00",
    "points_code": "STA001",
    "health_station_name": "晓葆健康站（朝阳门店）"
  }
}

预约列表

GET/api/v1/benefit-appointments

返回当前用户所有预约记录，支持 status 过滤（confirmed / completed / cancelled）和 type 过滤（upcoming / past）。

取消预约

POST/api/v1/benefit-appointments/{id}/cancel

取消指定预约。已完成的预约不可取消，返回 422。

请求体（可选）：

字段	类型	说明
`cancel_reason`	string	取消原因，最长 500 字符

到站码核验

POST/api/v1/health-station/verify-code

健康站设备扫码后调用此接口验证用户到站码，返回用户信息与授权状态。

请求体：

字段	类型	必填	说明
`code`	string	是	到站码（用户 App 上的 6 位字母数字码）
`points_code`	string	是	当前健康站编码

获取健康站报告

GET/api/v1/health-data/station-reports

返回用户在健康站的聚合检测报告列表（按到访记录分组）。

GET/api/v1/health-data/station-reports/{aggregateId}

返回单次到站的完整报告，包含各检测指标数值、趋势对比、AI 健康建议。

权益卡封装模式