调用说明 - JJB竞技宝

平台默认采用密钥加签名的鉴权方式。客户在后台生成一对访问密钥后，每次请求需携带时间戳与签名串，服务端会校验签名有效性与时间窗口，超出窗口的请求将被拒绝。密钥支持随时轮换，轮换期间新旧密钥可短暂并行，方便平滑切换。建议正式环境与测试环境使用不同密钥，并避免将密钥写入前端代码、公开仓库或客户端可反编译的产物中。若怀疑密钥泄露，应立即在后台作废旧密钥并重新生成，同时排查调用日志中的异常来源。

所有接口统一返回结构化数据，包含状态码、提示信息与数据体三部分。状态码用于快速判断本次调用是否成功，提示信息用于辅助定位问题，数据体承载业务内容。数据体中的字段命名在同类接口之间保持一致，时间字段统一使用标准时间格式，数值字段统一保留约定的小数位，便于客户直接映射到自有系统而无需额外转换。若某个接口因数据源特性需要特殊字段，会在接口文档中单独标注，不会悄悄改变既有字段的含义。

平台对单账号的调用频率设有上限，具体数值在接口文档中列明。若客户业务存在明显的峰值时段，可在方案确认阶段提出，平台会评估后调整配额，或建议采用批量接口减少请求次数，避免触发限流影响业务。触发限流时接口会返回明确的提示信息，客户应实现退避重试逻辑，而不是短时间内持续重发。对于长期高频调用的场景，建议提前沟通容量规划，把峰值与日常分开评估，避免上线后临时扩容。

不同数据源的更新节奏并不相同，平台会在接口文档中标注每类数据的更新周期。客户若对时效有更高要求，可在需求阶段说明，平台评估数据源条件后给出可行方案，并在方案文档中写明实际可达到的更新频率。需要注意的是，更新周期是数据源层面的客观约束，并非接口调用频率所能改变，因此建议客户在设计业务逻辑时预留合理的时间容差，不要把展示逻辑建立在"调用即最新"的假设上，避免因数据尚未刷新而产生误判。

接口返回的错误信息中会包含错误类型与简要原因，可先对照文档中的错误码说明排查。常见原因包括签名计算错误、时间戳偏差过大、参数缺失或格式不符、超出频率限制等，逐项核对通常能快速定位。若无法定位，可将请求参数、返回内容与发生时间一并提交给技术对接人，平台会在约定时限内响应并给出处理建议。建议在联调初期就建立错误日志记录习惯，把完整的请求与响应留档，能显著缩短排查时间。

平台在调整接口时会尽量保持向后兼容，确需变更时会提前通知并保留旧版本一段时间。客户可在后台查看当前使用的接口版本与对应的下线时间，按自身节奏安排升级，避免在业务高峰期临时改动。建议在收到升级通知后先评估影响范围，在测试环境完成验证，再逐步切换。若同时存在多个调用方，应协调好各自的升级时间，避免出现部分调用方已切换、部分仍在使用旧版本导致的数据口径不一致。

在正式接入前，客户方通常需要明确几项基础信息：调用方系统所处的网络环境、预计的调用量与峰值分布、需要使用的接口范围、期望的数据更新时效，以及负责对接的技术联系人。把这些信息提前整理好，可以在方案确认阶段一次性沟通清楚，减少来回确认。对于有特殊安全要求的客户，也可提前说明，平台会评估是否需要在鉴权方式或网络链路上做额外安排，避免联调阶段才发现条件不满足而返工。