Skip to content

3.4 注单查询 API(增量同步) ​

Exchange
http
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_timeTRUEstring变动时间区间起(含),RFC3339 UTC,须对齐整秒,例如 2026-10-20T00:00:00Z;不可早于 6 个月前
end_timeTRUEstring变动时间区间迄(含),RFC3339 UTC,须对齐整秒;须晚于 start_time,与 start_time 间隔不可超过 24 小时
cursorFALSEstring分页游标;第一页不带,之后带上一页响应的 next_cursor
langFALSEstringLANGUAGE_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。

字段类型说明
itemsarray区间内有变动的订单,内容为查询当下的最新状态(含全部 trades)
items[].changed_atstring该订单及其所属提交的最后变动时间(RFC3339 UTC,最多 9 位小数秒);同一订单只增不减,可作为版本号
has_moreboolean此区间是否还有下一页
next_cursorstring下一页游标;has_more 为 false 时为空字符串

TIP

changed_at 为平台数据的变动时间,并非下单时间或结算时间,请勿作为业务时间使用。

排序与分页 ​

  • items[] 依 changed_at 由旧到新排列,changed_at 相同时依 order_id 排列。
  • 第一页不带 cursor;has_more 为 true 时,带上 next_cursor 取下一页,直到 has_more 为 false。
  • 翻页期间订单若再次变动,该订单会移到更后面的位置再出现一次;已经取得的其他订单不受影响,不会漏单。

同步建议 ​

建议的同步流程

  1. 以固定间隔(例如每 5 分钟)执行一轮同步,本轮区间为 [上一轮 end_time, 当前时间 − 3 分钟],且不超过 24 小时。
  2. 不带 cursor 取第一页,依 has_more / next_cursor 取完全部页。
  3. 每笔订单以 order_id 写入(upsert):仅当 changed_at 比已存数据新时才覆盖。
  4. 本轮全部页取完后,记录本轮 end_time,作为下一轮的 start_time。
  • end_time 建议比当前时间早至少 3 分钟。 数据来源为备库,与主库之间有同步延迟;区间结束时间过于接近当前时间,可能漏取尚未同步的变动。
  • 区间可无缝衔接。 下一轮直接以本轮 end_time 作为 start_time;区间两端皆含,落在边界上的订单可能在两轮都出现。
  • 须容许重复。 同一订单可能在不同页或不同区间重复出现,商户端须以 order_id upsert,保持幂等。
  • 偶有批量变动。 平台重新同步数据时,可能有大量订单在同一区间内出现,订单内容不变,按 upsert 处理即可。
  • 平行处理或重试时须比对 changed_at。 多个 worker 同时同步、或失败重试较晚写入时,较旧的结果可能晚于较新的结果写入;仅在 changed_at 较新时覆盖,可避免旧状态覆盖新状态。

错误码 ​

code说明
10020参数错误:缺少 start_time / end_time、未对齐整秒、end_time 未晚于 start_time、区间超过 24 小时、start_time 早于 6 个月前、cursor 无效或不属于本次区间

其他错误码与其他查询 API 一致,详见查询 APIs 错误对照表。

BFX · BE THE GAME CHANGER