足球 API WebSocket 数据变更订阅接口文档

接口说明

连接后订阅比赛，实时推送所有变更

请求方式: WebSocket
请求地址: wss://api.superscore.cn/ws/change

请求头与鉴权

字段	类型	必填	文档示例值	说明
`token`	string	是	`传商户KEY`	token(传商户KEY)仅供测试,正式站请设置IP

商户密钥仅保存在自己的服务端。测试 token 与正式 IP 授权的适用范围以本表及账户授权说明为准。

客户端消息参数

字段	类型	必填	文档示例值	说明
`type`	string	是	`subscribe`	客户端消息：subscribe、unsubscribe、ping、heartbeat。
`matchId`	string	否	`YOUR_MATCH_ID`	比赛 ID；subscribe / unsubscribe 时必填，ping / heartbeat 时无需传入。

调用示例

替换 YOUR_MERCHANT_KEY、YOUR_MATCH_ID 等占位值后，在已授权的服务端调用。示例不会在本页面发起真实请求。

JavaScript 消息订阅

// 在服务端代理完成账户与 IP 授权后使用；替换 YOUR_MATCH_ID。
const socket = new WebSocket("wss://api.superscore.cn/ws/change");
socket.addEventListener('open', () => {
  socket.send(JSON.stringify({type: 'subscribe', matchId: 'YOUR_MATCH_ID'}));
});
socket.addEventListener('message', event => {
  const message = JSON.parse(event.data);
  console.log(message.type, message.data, message.timestamp);
});
// 取消订阅：{type: 'unsubscribe', matchId: 'YOUR_MATCH_ID'}
// 心跳：{type: 'ping'} 或 {type: 'heartbeat'}

返回参数

WebSocket 返回消息对象。

字段路径	类型	说明与枚举
`type`	string	服务端消息类型，包括连接、订阅确认、心跳、错误和数据变更。
`data`	object	消息数据。订阅确认包含 matchId，错误包含 message；变更数据按消息类型对应接口字段解析。
`timestamp`	int64	消息时间戳，毫秒。
`messageId`	string	可选消息 ID。
`matchId`	string	可选比赛 ID，数据推送时使用。

响应结构示例

下面的值仅展示字段类型，不是实时数据或真实调用结果。动态 map 的键取决于实际返回，不编造固定字段。

展开完整 JSON 结构

{
  "type": "示例字符串",
  "data": {},
  "timestamp": 0,
  "messageId": "示例字符串",
  "matchId": "示例字符串"
}

错误处理与使用说明

先建立连接，再发送订阅消息。比赛 ID 放在消息体中。
subscribe / unsubscribe 的 matchId 不能为空；未知 type 或无法解析的消息会返回错误消息。
ping 对应 pong，heartbeat 对应 heartbeat_ack；服务端枚举序列化可能使用大写名称，客户端应按实际响应处理。
推送数据随事件类型变化，不使用 REST 的 success / code / message / data 包装。
在自己的服务端完成账户与 IP 授权，不在公开页面放置商户密钥。