API 参考

基础信息

公开接口基础路径：/apis/api.steam.timxs.com/v1alpha1，无需认证。

管理接口基础路径：/apis/console.api.steam.timxs.com/v1alpha1，需要管理员权限。

响应格式为 JSON。管理端验证失败时会返回 application/problem+json 的 Problem Details。

公开 API

GET /profile

获取 Steam 用户资料。失败或未配置时返回 404。

响应字段：

  • summary.steamId
  • summary.personaName
  • summary.profileUrl
  • summary.avatar / avatarMedium / avatarFull
  • summary.personaState
  • summary.gameExtraInfo / gameId
  • summary.lastLogoff
  • steamLevel
  • statusText
  • playing

GET /games

获取游戏库分页。

参数 类型 必填 说明
page int 否 页码，默认 1，低于 1 会按 1 处理
size int 否 每页数量，默认 20，最大 100
sortBy string 否 playtime_forever（默认）或 name

未配置或 service 返回 empty 时返回空分页：

{
  "page": 1,
  "size": 20,
  "total": 0,
  "items": []
}

游戏字段：

字段 说明
appId Steam AppID
name 游戏名称，优先使用 GetItems 本地化结果
playtimeForever / playtimeFormatted 总游玩分钟数 / 格式化文本
imgIconUrl / iconUrl 原始图标 hash / 展示图标 URL
rtimeLastPlayed / lastPlayedFormatted 最后游玩时间戳 / 日期
headerImageUrl / realHeaderImage 展示封面 URL / Steam 原始真实封面 URL
delisted GetItems 明确返回 visible=false 时为 true

headerImageUrl 可能为 null，调用方应准备占位图。GetItems 未返回某个 AppID 不会被判为 delisted=true。

GET /recent

获取最近游玩。

参数 类型 必填 说明
limit int 否 返回数量，默认 5，最大 20

未配置或无数据时返回空数组 []。

最近游玩元素包含 /games 的字段，并额外包含：

  • playtime2Weeks
  • playtime2WeeksFormatted
  • achievementProgressText
  • achievementsLocked
  • inLibrary

成就进度只在开启「显示最近游玩成就进度」后补全，且随最近游玩缓存返回。

GET /stats

获取统计数据：

{
  "totalGames": 150,
  "totalPlaytimeMinutes": 120000,
  "recentPlaytimeMinutes": 600,
  "totalPlaytimeFormatted": "2,000 小时",
  "recentPlaytimeFormatted": "10 小时 0 分钟"
}

GET /achievements/{appid}

获取指定游戏成就进度。

响应字段：

  • appId
  • gameName
  • achievedCount
  • totalAchievements
  • percentage
  • progressText

游戏无成就、成就不可访问或请求失败时，service 会返回 0 进度兜底。

GET /badges

获取徽章信息。

顶层字段：

  • badges
  • playerXp
  • playerLevel
  • xpNeededToLevelUp
  • xpNeededCurrentLevel
  • totalBadges
  • gameBadgeCount
  • levelProgressPercent

徽章字段：

  • badgeId
  • level
  • completionTime
  • xp
  • scarcity
  • appId
  • communityItemId
  • borderColor
  • imageUrl
  • badgeName
  • completionTimeFormatted
  • gameBadge
  • foil
  • displayName

GET /game-detail/{appId}

获取游戏卡片详情，可带 lang 参数。

字段包括：

  • appId
  • name
  • headerImage
  • shortDescription
  • developers
  • publishers
  • genres
  • isFree
  • priceFormatted
  • releaseDate
  • storeUrl
  • owned
  • playtimeForever
  • playtimeFormatted
  • rtimeLastPlayed
  • lastPlayedFormatted
  • achievedCount
  • totalAchievements
  • achievementProgress

此接口使用 Steam Store /api/appdetails，用于详情字段；列表封面/名称补全使用 GetItems，二者职责不同。

GET /heatmap/records

查询每日游戏时长记录。

参数 类型 必填 说明
startDate string 是 开始日期，yyyy-MM-dd
endDate string 是 结束日期，yyyy-MM-dd
appId long 否 游戏 ID，不传查询所有游戏
page int 否 页码，默认 1
size int 否 每页数量，默认 365

返回 ListResult<DailyPlaytimeRecord>，记录数据位于 items[].spec：

  • steamId
  • date
  • appId
  • gameName
  • playtimeMinutes
  • startTime
  • endTime

管理 API

POST /verify

请求体：

{
  "apiKey": "Steam API Key",
  "steamId": "76561198000000000"
}

验证成功时返回原请求体。验证失败时返回 Problem Details：

{
  "title": "验证失败",
  "status": 400,
  "detail": "错误原因"
}

POST /refresh

清空 Steam 内存缓存，并在后台触发一次预热。

{
  "success": true,
  "message": "Steam 数据缓存已清空"
}

POST /heatmap/track

手动触发一次游戏时长追踪。热力图未启用时返回 success=false 和提示消息。

POST /heatmap/cleanup

手动清理过期热力图记录。热力图未启用时返回 success=false 和提示消息。

Steam API 代理参考

自定义 API 代理需保持路径、查询参数、响应体透传。插件会用到：

路径 上游
/ISteamUser/* https://api.steampowered.com
/IPlayerService/* https://api.steampowered.com
/ISteamUserStats/* https://api.steampowered.com
/IStoreBrowseService/* https://api.steampowered.com
/api/appdetails https://store.steampowered.com

GetItems 行为

列表补全使用 IStoreBrowseService/GetItems/v1/，无需 API Key。请求必须包含 context.country_code，否则可能返回空数据。

插件按 35 个 AppID 一批请求并合并结果。单个批次失败时返回空 map，不影响其他成功批次。

字段语义：

  • name：本地化名称
  • assets.asset_url_format + assets.header：真实封面路径
  • visible=false：商店在当前地区/状态下不可见，插件标记 delisted=true
  • AppID 缺席：只表示本次 GetItems 未覆盖到该游戏，不会被判为不可用

真实封面格式：

https://shared.akamai.steamstatic.com/store_item_assets/steam/apps/<appid>/<hash>/header.jpg

appdetails 行为

游戏卡片详情使用 https://store.steampowered.com/api/appdetails?appids=<appid>&l=<language>&cc=<country>。

appdetails 返回描述、价格、开发商、类型等详情字段；不要用 GetItems 替代它。

appdetails 的 success:false 不区分原因——AppID 不存在、全球下架、区域锁、接口限流都会返回 false，且不含 data；非 game 类型（dlc/music/demo）反而返回 success:true（实测配乐 AppID 2678630 为 type:"music" 且成功）。因此不能据此判定「不可用」。游戏卡片在 success:false 时，会再用 GetItems 的 visible=false 二次确认是否真不可用（与列表判定同源）；GetItems 未明确返回 visible=false（缺席或失败）则按「加载失败」处理并保留重试，避免把限流误判成下架。