注单记录

平台提供两种读取方式，通常一起使用：

接口	用途
GET /v1/records	按创建时间窗口拉取某一时刻的注单快照，适合补数据和对账
GET /v1/record-changes	按游标持续读取注单的变更，适合实时同步

两个接口共用注单限流，默认每个商户 2 次/秒（以 capabilities.limits 为准）。

注单字段

一局游戏对应一条注单，派奖、退款到达后注单会产生新的 revision。

字段	类型	说明
record_id	string	注单 ID。不等于交易 ID 或对局 ID
revision	integer	修订号，越大越新
player_id	string	平台玩家 ID
game_id	string	游戏 ID
currency	string	币种代码
round_id	string	对局 ID，与资金交易、对局结束通知中的一致
parent_round_id	string | null	父局 ID，免费局等子局才有
bet_amount	decimal string	已确认扣款的投注额；扣款确认前为 0
refund_amount	decimal string	已确认的退款额
payout_amount	decimal string	已确认的累计派奖额
net_amount	decimal string	玩家输赢 = payout_amount + refund_amount - bet_amount，可为负
status	string	OPEN（未结算）、SETTLED（已结算）、VOID（全额取消）
created_at	string	注单创建时间
settled_at	string | null	结算时间；OPEN 时为 null
updated_at	string	本修订的时间

• OPEN 注单的 payout_amount 只是目前已确认的派奖，不是最终结果。
• 部分退款后，注单按剩余投注保持 OPEN 或 SETTLED；只有全额取消且没有有效结算时才是 VOID。
• 现金奖励（gift-tasks）不计入注单的派奖。

{
  "record_id": "0192f700-7f8e-71a2-c3d4-0e1f2a3b4c5d",
  "revision": 2,
  "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
  "game_id": "0192f6a5-1111-7aaa-8bbb-000000000001",
  "currency": "USD",
  "round_id": "r-20260923-000123",
  "parent_round_id": null,
  "bet_amount": "10.00",
  "refund_amount": "0.00",
  "payout_amount": "19.50",
  "net_amount": "9.50",
  "status": "SETTLED",
  "created_at": "2026-09-23T08:00:00.000Z",
  "settled_at": "2026-09-23T08:00:05.000Z",
  "updated_at": "2026-09-23T08:00:05.000Z"
}

按时间窗口拉取

GET {API_URL}/v1/records

参数	必填	说明
created_from	首次必填	窗口起点（包含），RFC3339，最多毫秒精度
created_to	首次必填	窗口终点（不包含）。窗口必须大于 0 且不超过 24 小时
player_id	否	只看某个玩家
game_id	否	只看某个游戏
limit	否	每页条数，1–1000，默认 100
cursor	续页必填	上一页的 next_cursor。带 cursor 时只能再带 limit，不能再传其他参数

GET /v1/records?created_from=2026-09-23T00:00:00Z&created_to=2026-09-24T00:00:00Z&limit=500

成功响应 200

字段	说明
items	注单列表，按 (created_at, record_id) 升序
next_cursor	下一页游标；没有下一页时为 null
has_more	是否还有下一页
snapshot_watermark	首次请求时冻结的快照位置
projection_as_of	数据的截止时间

• 首次请求会冻结快照：同一条游标链中看到的是同一时刻的数据，按顺序翻页不会漏也不会重复。
• 快照之后发生的派奖、退款等修改，请通过读取注单变更获取。
• 游标自首次请求起 24 小时内有效，过期返回 410 CURSOR_EXPIRED。
• 响应中的时间统一为 UTC、三位毫秒，例如 2026-09-23T08:00:00.000Z。

读取注单变更

GET {API_URL}/v1/record-changes

since、from_now=true 和 cursor 三选一，必须且只能传一个。

参数	说明
since	从这个变更时间开始读取（包含），RFC3339
from_now	固定为 true：从当前位置开始，不返回历史变更
cursor	上一页的 next_cursor
limit	每页条数，1–1000，默认 100

成功响应 200

字段	说明
items[].sequence	变更序号（十进制字符串），严格递增。不是时间戳
items[].record_id	注单 ID
items[].revision	本次变更后的修订号
items[].changed_at	变更时间
items[].record	该修订的完整注单
next_cursor	下次读取用的游标，一定有值，即使本页为空
has_more	是否还有积压
projection_as_of	数据的截止时间

{
  "data": {
    "items": [
      {
        "sequence": "1024",
        "record_id": "0192f700-7f8e-71a2-c3d4-0e1f2a3b4c5d",
        "revision": 2,
        "changed_at": "2026-09-23T08:00:05.000Z",
        "record": { "record_id": "0192f700-7f8e-71a2-c3d4-0e1f2a3b4c5d", "revision": 2, "status": "SETTLED", "…": "…" }
      }
    ],
    "next_cursor": "eyJ2Ijox…",
    "has_more": false
  },
  "request_id": "0192f700-req-0001"
}

持续同步

1. 保存每次响应的 next_cursor（持久化），下次用它继续读。
2. has_more=true 时立即读下一页；为 false 时等待一段时间再读。
3. 同一条注单可能出现多次。按 record_id 保存，只在 revision 更大时覆盖。

重建与游标过期

变更数据保留 90 天。游标或 since 早于保留期时，返回 410 CURSOR_EXPIRED，平台不会悄悄跳过缺失的部分。

需要从头建立数据，或游标过期后，按以下顺序操作才能保证不漏单：

1. 调用 GET /v1/record-changes?from_now=true，保存返回的 next_cursor（此时 items 为空）。
2. 用 /v1/records 按 24 小时一个窗口，拉取需要的历史区间。
3. 从第 1 步的游标开始读取变更，按 revision 去重覆盖。

不要用本地时间代替第 1 步

第 1 步的位置由平台确定。用本地时钟计算 since 来衔接，可能因为时钟差或提交延迟漏掉变更。

平台数据同步暂时落后时，接口返回 503，不会返回空页。稍后重试即可。