1
确认服务
先确认服务可用，并检查当前启用的运动。
curl "https://api.yogent.cn/v1/sports" \
-H "Authorization: Bearer YOUR_API_KEY"2
查一个联赛
拿到 league_id，后面查赛程、球队和积分榜都要用。
curl "https://api.yogent.cn/v1/football/leagues?per_page=5" \
-H "Authorization: Bearer YOUR_API_KEY"3
查这个联赛的赛程
按日期范围查询比赛，再用 fixture_id 拉详情。
curl "https://api.yogent.cn/v1/football/fixtures?league_id=18&date_from=2026-11-02" \
-H "Authorization: Bearer YOUR_API_KEY"Full example
完整请求和响应
同一套契约贯穿所有端点。切换标签查看 cURL、Python、JavaScript 和响应结构。
curl "https://api.yogent.cn/v1/football/fixtures?league_id=18" \
-H "Authorization: Bearer YOUR_API_KEY"示例 Key 为占位符，实际调用请替换为你的 Key。bash
Checklist
接入检查清单
上线前对照一遍，能避开大部分联调问题。
- Base URL 统一使用 https://api.yogent.cn，不带结尾斜杠。
- 每个请求都带 Authorization: Bearer <API Key>。
- 时间字段直接读 kickoff_at / updated_at，不要自己拼时区。
- 翻页只用 meta.pagination.next_cursor，不用页码。
- 关联数据可按需展开，字段可按需裁剪。
- 错误先读 errors[].code，再结合 HTTP 状态处理。
Errors
常见错误怎么处理
错误统一放在 errors[] 里，HTTP 状态和错误码分开。
| 状态 | 含义 | 怎么处理 |
|---|---|---|
| 401 | 未认证 | 检查 Authorization 请求头，确认 Key 没有多余空格。 |
| 403 | 无权限 / 已过期 | 确认 Key 未过期，且套餐包含当前查询的数据范围。 |
| 404 | 资源不存在 | 检查 league_id、fixture_id、season_id 是否来自当前运动。 |
| 429 | 频率超限 | 按 meta.rate_limit.reset_at 退避，不要立即重试。 |
| 5xx | 服务端错误 | 记录 meta.request_id，带请求时间联系商务或技术支持。 |
调试时不要在生产环境打印完整 Key；日志里只保留 Key 后四位和 request_id。
