3.4 注单查询 API(增量同步)
Exchangehttp
GET /api/v1/exchange/report/bets/changes返回指定时间区间内有变动的订单(含其全部提交),用于将注单增量同步至商户系统。订单本身或其任一提交发生变动(撮合、撤单、结算、重新结算、回滚、作废等)均视为变动。数据保留最近 6 个月。请求须带入 HMAC 验证 Header。
TIP
本 API 限流 100 次 / 分钟,超过返回 code:10060。额度按 api_key × 接口独立计算,各接口不共用;每次请求(含返回错误者)均计入。
与 3.3 注单查询 API 的差异
3.3 注单查询 依下单时间或结算时间筛选,无法完整反映回滚、作废等后续变动;本 API 依变动时间筛选,适合定期拉取变动并更新商户侧数据。两者返回的订单结构相同。
请求参数(Query String)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| start_time | TRUE | string | 变动时间区间起(含),RFC3339 UTC,须对齐整秒,例如 2026-10-20T00:00:00Z;不可早于 6 个月前 |
| end_time | TRUE | string | 变动时间区间迄(含),RFC3339 UTC,须对齐整秒;须晚于 start_time,与 start_time 间隔不可超过 24 小时 |
| cursor | FALSE | string | 分页游标;第一页不带,之后带上一页响应的 next_cursor |
| lang | FALSE | string | LANGUAGE_ZH_CN / LANGUAGE_EN(默认英文) |
TIP
本 API 以游标分页,每页固定最多 100 笔,不提供 page / page_size。cursor 仅对产生它的同一组 start_time / end_time 有效,更换区间须从第一页重新开始。cursor 内容不保证格式,请勿自行解析或组装。
响应 data
json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"order_id": "019e0000-0000-0000-0000-000000000000",
"player_external_id": "player1",
"event_id": "sr:match:00000000",
"status": "EXCHANGE_ORDER_STATUS_FILLED",
"trades": [
{
"trade_id": "00000000-0000-0000-0000-000000000070",
"settlement_status": "EXCHANGE_TRADE_SETTLEMENT_STATUS_SETTLED",
"settlement_result": "EXCHANGE_TRADE_SETTLEMENT_RESULT_WIN",
"settled_time": "2026-10-20T04:33:09Z",
...
}
],
"order_time": "2026-10-19T04:01:59Z",
"changed_at": "2026-10-20T04:33:10.184553771Z",
...
}
],
"has_more": true,
"next_cursor": "djF8MTc5MjM2ODAwMDAwMDAwMDAwMHwxNzky..."
}
}上例仅列出部分字段。
items[]每笔订单的完整字段与 3.3 注单查询 相同,另多一个changed_at。
| 字段 | 类型 | 说明 |
|---|---|---|
| items | array | 区间内有变动的订单,内容为查询当下的最新状态(含全部 trades) |
| items[].changed_at | string | 该订单及其所属提交的最后变动时间(RFC3339 UTC,最多 9 位小数秒);同一订单只增不减,可作为版本号 |
| has_more | boolean | 此区间是否还有下一页 |
| next_cursor | string | 下一页游标;has_more 为 false 时为空字符串 |
TIP
changed_at 为平台数据的变动时间,并非下单时间或结算时间,请勿作为业务时间使用。
排序与分页
items[]依changed_at由旧到新排列,changed_at相同时依order_id排列。- 第一页不带
cursor;has_more为true时,带上next_cursor取下一页,直到has_more为false。 - 翻页期间订单若再次变动,该订单会移到更后面的位置再出现一次;已经取得的其他订单不受影响,不会漏单。
同步建议
建议的同步流程
- 以固定间隔(例如每 5 分钟)执行一轮同步,本轮区间为
[上一轮 end_time, 当前时间 − 3 分钟],且不超过 24 小时。 - 不带
cursor取第一页,依has_more/next_cursor取完全部页。 - 每笔订单以
order_id写入(upsert):仅当changed_at比已存数据新时才覆盖。 - 本轮全部页取完后,记录本轮
end_time,作为下一轮的start_time。
end_time建议比当前时间早至少 3 分钟。 数据来源为备库,与主库之间有同步延迟;区间结束时间过于接近当前时间,可能漏取尚未同步的变动。- 区间可无缝衔接。 下一轮直接以本轮
end_time作为start_time;区间两端皆含,落在边界上的订单可能在两轮都出现。 - 须容许重复。 同一订单可能在不同页或不同区间重复出现,商户端须以
order_idupsert,保持幂等。 - 偶有批量变动。 平台重新同步数据时,可能有大量订单在同一区间内出现,订单内容不变,按 upsert 处理即可。
- 平行处理或重试时须比对
changed_at。 多个 worker 同时同步、或失败重试较晚写入时,较旧的结果可能晚于较新的结果写入;仅在changed_at较新时覆盖,可避免旧状态覆盖新状态。
错误码
| code | 说明 |
|---|---|
| 10020 | 参数错误:缺少 start_time / end_time、未对齐整秒、end_time 未晚于 start_time、区间超过 24 小时、start_time 早于 6 个月前、cursor 无效或不属于本次区间 |
其他错误码与其他查询 API 一致,详见查询 APIs 错误对照表。