接入方式
说球帝提供标准 HTTP 与 WebSocket 两类接入方式。前者适合定时拉取的资讯与资料场景，后者适合需要持续推送的实时数据场景。两种方式共用同一套鉴权体系与账号体系，切换接入方式时不需要重新申请账号，也不需要重新走一遍资质流程。对于同时存在批量拉取与实时推送需求的客户，可以在同一个账号下并行使用两种方式，服务端会按请求来源分别统计调用量，不会相互影响配额。首次接入建议先用 HTTP 方式跑通链路，再根据业务节奏决定是否补充 WebSocket 通道。
接口说明 - 说球帝 · 智能体育赛事平台
接口说明栏目是「说球帝」面向开发与对接人员整理的一份数据接口规范总览。在这里，你可以了解到平台对外提供的接入方式、数据格式、鉴权机制、频率限制、错误处理以及版本管理方式等关键信息。无论你是准备将说球帝的赛事数据集成到自有应用，还是希望把平台能力嵌入现有业务流程，本栏目都会把每一项约定讲清楚，方便你评估工作量、安排开发排期。我们尽量用通俗的语言描述技术细节，让对接人员不必反复沟通就能读懂规则，减少来回确认的成本。栏目内容会随平台能力持续更新，建议在正式开工前完整浏览一遍，遇到理解不一致的地方也可以直接对接技术同事确认。
接口能力说明
数据格式
接口默认返回 JSON 结构，字段命名保持统一的风格，嵌套层级控制在三层以内，方便前端直接映射到页面组件，减少中间转换层。需要 CSV 或 XML 的场景可以单独说明，我们会在网关层做转换，不要求客户端自己解析，也不会因此额外增加对接方的开发量。所有时间字段统一采用带时区的标准格式，数值字段会明确说明单位与精度，布尔字段只使用真与假两种取值，避免出现空字符串或数字混用带来的歧义。
鉴权机制
每个接入方分配独立的密钥对，请求头携带签名与时间戳，服务端会校验签名有效性与时间窗口，超过允许偏差的请求会被拒绝并返回明确原因。密钥支持自助轮换，旧密钥在过渡期内仍然可用，避免轮换过程中出现调用中断。建议把密钥放在服务端环境变量中，不要写进前端代码或提交到版本库。如果怀疑密钥泄露，可以立即在控制台作废旧密钥并生成新的密钥对，作废动作即时生效，不需要等待人工审核。
频率限制
接口按套餐档位设置调用频率上限，超出后返回明确的限流状态码与建议重试时间，而不是直接丢弃请求，客户端可以据此做退避重试。对于有突发流量预期的客户，可以提前告知，我们会临时调整配额，避免活动期间出现不必要的失败。建议客户端实现本地缓存，对短时间内重复的查询做合并，既能降低调用量，也能让页面加载更稳定。限流统计按账号维度计算，多个应用共用同一账号时会共享配额。
错误处理
所有异常都返回统一的错误结构，包含错误码、可读描述与排查建议，客户端可以据此决定是重试、提示用户还是记录日志。常见的接入问题在文档里都有对应条目，按错误码检索就能定位到原因。遇到文档没覆盖的情况，可以通过对接群直接找技术同事确认，我们会补充到文档中供后续接入方参考。建议在客户端对错误码做分类处理，把可重试的错误与需要人工介入的错误区分开，避免无意义的循环重试。
版本管理
接口按大版本号区分，新增字段属于兼容性变更，不会影响已有调用，客户端可以忽略不认识的字段继续运行。涉及字段废弃时会提前通知并保留一段共存期，让客户有足够时间完成代码调整，不会突然中断服务。建议在请求中显式指定使用的大版本号，而不是依赖服务端默认值，这样在版本切换时行为更可预期。版本变更记录会集中列出，方便对接人员一次性核对影响范围。
对接前需要了解的几个要点
这份接口说明具体包含什么
它并不是一份只列请求地址的清单，而是把接入说球帝数据能力需要知道的约定集中放在一起：用哪种通道接入、返回结构长什么样、请求怎么证明身份、调用频率如何计算、出错时怎么判断原因、后续升级会不会影响现有代码。把这几件事看完，对接方基本能独立判断工作量，也能预估需要投入多少人天。
客户通常会关心哪几个点
实际沟通中，问得最多的是三件事：一是首次接入需要多久，二是实时数据的延迟大概在什么范围，三是调用量增长后配额能不能跟着调整。前两个问题在接入方式与数据格式两节里能找到答案，第三个问题取决于所选套餐档位，可以在对接时直接说明预期的峰值调用量，我们会给出对应的配额建议。
判断接口质量的标准
可以看四点：字段命名是否前后一致，错误返回是否带可读描述与排查建议，版本变更是否有提前通知与共存期，限流是否给出建议重试时间而不是直接丢弃。这四点决定了长期维护成本。字段命名混乱会让前端反复写映射，错误信息含糊会让排查时间成倍增加，缺少共存期则意味着每次升级都要紧急改代码。
第一次接触容易忽略的地方
最常见的是把密钥写进前端代码，其次是忽略时间戳窗口导致签名校验失败，还有的客户端不做退避重试，遇到限流就密集重发，反而让情况更糟。另外，很多人会跳过错误码说明直接开工，等到线上出问题才回来翻文档，这时候定位成本会高很多。建议在联调阶段就把这几项检查一遍，后续会省下不少沟通时间。