---
name: qiuzhong-api-client
description: Use when a user asks to query or integrate qiuzhong.fastoffice.site for football fixtures, live scores, postmatch reports, events, lineups, stats, odds, money flow, 竞彩足球, 北单, leagues, teams or players.
---
# 球中 API 客户端

API 基址：`https://qiuzhong.fastoffice.site/v1`。先用已有结果，再选择能回答问题的最少接口。只依据实际返回作答，不补造数据。

## 开始使用

1. 每个新会话读取本 Skill 最新版；长会话距上次成功读取满 24 小时后，在下一次查询前重新读取。读取 Skill 不发送 API Key，不为此建立定时任务。临时无法读取时沿用已知规则，不猜新接口。
2. 请求头使用 `X-Api-Key`：优先使用用户在当前会话提供的 Key，否则读取 `QIUZHONG_API_KEY`。不输出 Key；只发往 `https://qiuzhong.fastoffice.site`，不跟随跨域重定向。
3. 首次调用业务接口前或更换 Key 后，先 `GET /usage`，核实套餐、今日／总剩余额度、每分钟限额、历史范围、到期时间，简短告知一次。只用当前 Key 实际返回；`总额度` 非 null 是有效期合计额度，不是每天恢复。同一会话复用权限信息，不在每次查询前后调用 `/usage`；用户问用量、续费升级或需要核实限额时再查。首次核实失败不继续批量请求。
4. 普通后续查询直接执行。无需例行健康检查；排障时 `/health` 每个会话最多一次，已有成功请求则跳过。用户尚未提出具体查询时先问要查什么，不默认拉取全站赛程。
5. 常见查询按本页直接调用，无需读取完整 OpenAPI。参数不明确、使用未列出的能力或开发接入时，读取 [OpenAPI](https://qiuzhong.fastoffice.site/openapi.json)，路径、参数、类型、枚举、默认值及响应结构以它为准；仍无法确认则询问，禁止猜测。

使用环境变量时，先检查是否配置，不输出其值：
```bash
test -n "${QIUZHONG_API_KEY:-}" || { echo "QIUZHONG_API_KEY 未配置" >&2; exit 1; }
curl --fail-with-body --max-time 90 -H "X-Api-Key: $QIUZHONG_API_KEY" \
  "https://qiuzhong.fastoffice.site/v1/usage"
```
不要在同一条命令用临时赋值 `QIUZHONG_API_KEY=... curl ... "$QIUZHONG_API_KEY"`，变量可能在赋值前展开为空。会话已有有效权限时跳过示例请求。

## 按问题选择入口

下面路径均相对 API 基址；`{matchId}` 等占位符必须替换为接口真实返回的 ID。

| 用户想看 | 最少调用方式 |
| --- | --- |
| 某天、某联赛的比赛 | `/matches`，带所需日期／`league_id`，不要先拉全站再筛选 |
| 现在进行中的比赛 | `/matches/live`；限定联赛时带 `league_id` |
| 一场已完赛的详细表现、事件和球员情况 | 优先一次 `/matches/{matchId}/report` |
| 单独问比分／基本资料 | 优先复用列表；缺少所需信息才查 `/matches/{matchId}` |
| 只需某一类比赛数据 | `/events`、`/lineups`、`/player-stats` 或 `/stats`，接在 `/matches/{matchId}` 后 |
| 上半场／下半场角球、射门等统计 | 一次 `/matches/{matchId}/stats`，读取 `数据.上半场`／`数据.下半场`，缺失为 null；详见足球参考 |
| xG、射门图等多个统计模块 | 一次 `/matches/{matchId}/stats?include=shotmap,momentum,positions,xg_timeline`，只选需要的模块 |
| 赛前 xG | `/matches/{matchId}/prematch-xg`，与赛中／赛后实际射门 xG 区分 |
| 赛前盘口、初盘和最新赛前盘 | `/matches/{matchId}/odds`；多公司用 `bookmaker_ids` 合并 |
| 逐次变盘历史 | `/matches/{matchId}/odds/history`，必须带 `market`；先读赔率参考 |
| 当前滚球盘口 | `/matches/{matchId}/live-odds`；已完赛不查滚球 |
| 资金分布／变化历史 | 已有列表能回答则直接用；否则 `/matches/{matchId}/money`／`/matches/{matchId}/money/history` |
| 竞彩足球比分、赛程、赛事前瞻、最新五种奖金 | 一次 `/jc/matches?date={日期}`，不逐场补详情 |
| 竞彩足球奖金历史或彩果 | `/jc/matches/{jcId}/bonus`；`jcId` 来自足球竞彩列表 |
| 北单赛程和关联 | `/bd/matches?date={日期}`；已有匹配直接用返回的 `比赛ID` |
| 联赛、球队、球员或其他资料 | 搜索发现真实 ID；季节／历史汇总先读足球参考，完整目录见 OpenAPI |

赔率公司和能力以当前 Key 的 `/bookmakers` 为准，同一 Key 会话内复用。未指定公司默认 Bet365；同场单公司用 `bookmaker_id`，多公司用 `bookmaker_ids`（最多 10 家），二者不同时传。批量结果逐家公司判断，保留成功项，不把一家失败说成全部无数据。盘口快照不传 `market`；历史接口必须传。首次查询赔率／资金时只读对应参考，不把竞彩奖金当作博彩公司赔率。

## 三条常用流程

### 已有比赛 ID：直接查需要的数据

- 已完赛且需要多个赛后模块，优先报告；只问单项则查该子接口。报告只读已发布归档，不触发查询补采；支持近 12 个月已有归档，并受 Key 历史权限限制。不包含赔率、资金、竞彩奖金或交锋。
- 读取 `缺失模块` 和 `模块状态`。基础比赛缺失返回 404；部分模块缺失仍返回 200，成功请求计一次业务额度。已收录只说明快照存在，不保证所有指标齐全。缺失时返回已有内容，不自动改查其他子接口补抓或反复请求报告。
- 单独查询统计时合并所需 `include`；列表已有比分、双方、时间等就直接使用。已取得的完赛结果和分页在本会话复用，用户要求重新核对时才重查。

```text
GET /matches/{matchId}/report
GET /matches/{matchId}/stats?include=shotmap,xg_timeline
```
这两个示例是不同需求的选择，不是需要连续执行的步骤。

### 查某天、某联赛：限定范围再分页

- “今天”“这周六”等先转换为实际北京时间日期，核对星期；只查用户要求的日期和赛事。默认比赛列表不包括所有专项赛事；已知联赛 ID 直接使用，不再遍历联赛目录。
- 只问今晚赛程时查 `/matches`，按开球时间筛选；不额外拉 `/matches/live`。明确要当前实时比分才查实时入口并复用结果。跨午夜、专项赛事和指定球队定位规则见足球参考。
- 普通列表完整查询用 `per_page=200`；定位少量对象用较小页大小。按 `元数据.分页.有下一页` 继续，翻页保持筛选条件和页大小不变；没有总数时不推算总数。完整读取与最多展示 10 场是两回事，用户要全部时给出全部结果。
- “支持哪些联赛”等概括问题只读第一页，列真实例子并说明不是完整清单；不自动翻完全部目录或逐个查询比赛。

```text
GET /leagues?name={联赛搜索词}&page=1&per_page=10
GET /matches?league_id={leagueId}&date_from={开始日期}&date_to={结束日期}&page=1&per_page=200
```
已有 `leagueId` 则跳过第一步。搜索词仅用于发现候选，不代表确认了实体。候选明显唯一时直接继续，多个候选都合理时才询问；不得构造或凭记忆填写 ID。当前会话复用已确认的 ID，新会话或上下文缺失时重新发现。

### 竞彩：列表能回答的就不逐场查

- 足球：一次 `/jc/matches` 返回赛程、比分、五种最新固定奖金和官方赛事前瞻。读每场的 `赛事前瞻.{模块}.数据`，同时检查该模块的状态、采集时间（模块与字段见 references/lottery.md）；仅需历史奖金／彩果才调用 `/bonus`。需要同场球中事件、统计或赔率时，直接使用列表的 `比赛ID`（`mt_`），不再调用 `/fixture` 转换；`比赛ID=null` 时展示已有竞彩数据，不自行匹配或重复查询。
- 足球竞彩 ID、北单 ID 与球中 `mt_` 比赛 ID 不可混用。编号日期和开球日期不同，按各接口口径查询。详情及北单期号规则见竞彩参考。

## 结果与失败怎么处理

- 比赛 `/lineups` 分别展示“来源更新时间”和“最近采集时间”，按返回时区转为北京时间。旧“更新时间”只是来源时间的兼容字段；来源时间未变不代表停止采集，最近采集不代表名单刚变更或完整。缺少采集时间时明确未知，不用请求时间补填。
- 缺失字段保留 null，空数组不等于确定没有事件或无人伤停，也不能填 0；真实 0 保留。比赛状态、销售状态、开奖状态分别解释。
- 关联返回 `待确认`／`未匹配` 或赔率暂不可用：展示其他已有数据，由平台维护关联；不自行搜索其他赛程拼接，不选择候选、不传 `candidate_id` 修复。同一问题已知缺关联时，不继续试其他依赖该关联的接口。
- 中文优先自然表达，`中文名`／`主队中文名`／`客队中文名` 有值时优先展示；缺失则用原文名称，冷门实体保留原名。主要字段名为中文，不承诺所有名称均为中文；翻译不作为 ID、筛选或关联依据。队标直接使用返回地址，不附 Key，204 时用占位图。
- 每分钟频率和历史权限以 `/usage` 为准；同一 Key 多端共享额度，批量分页顺序排队。已有请求仍在等待时不发重复请求。
- 400 先修正参数，不能原样重试；401/403 核对鉴权或历史权限；429 按 `Retry-After` 等待，额度耗尽则停止；503 最多退避重试一次。具体恢复规则见限额参考，不无限重试。
- 普通用户回答比赛、时间、公司、盘口和实际数据，不堆接口术语；开发接入才提供路径和参数。接口事实与外部资料分开标注，不根据赔率给出投注建议。FIFA 排名不由本 API 提供，见足球参考。

## 按需参考

仅按需读取对应参考，组合问题可读多份；已安装目录可读同名本地文件，网页使用下面完整地址。读取参考文档无需 Key，不预加载全部文件。

- [足球：定位、日期、积分榜、球员统计、伤停与 FIFA](https://qiuzhong.fastoffice.site/skills/qiuzhong-api-client/references/football.md)
- [赔率与资金：公司、盘口、历史分页和阶段](https://qiuzhong.fastoffice.site/skills/qiuzhong-api-client/references/odds-money.md)
- [竞彩与北单：奖金、日期和状态](https://qiuzhong.fastoffice.site/skills/qiuzhong-api-client/references/lottery.md)
- [权限与错误：额度、频率、历史范围和重试](https://qiuzhong.fastoffice.site/skills/qiuzhong-api-client/references/access.md)

只使用完成本次体育查询所需的 HTTP 工具；不要搜索、安装无关 Skill，也不要附加无关的计划、测试、子 Agent 或审批流程。运行环境强制要求的系统级规则仍须遵守。
