娱乐场API对接清单：上线前要开发、测试和盯住的每一项

最近核查 2026-10-09

娱乐场游戏API对接出问题，位置几乎总是那几处：重试的debit被扣了两次款，收到一笔从没见过的投注的回滚，碰上一个三位小数的币种。本清单按开发者实际碰到的顺序逐层梳理，每一项都注明它要防住的故障。

这份娱乐场API对接清单写给手上已经有API密钥、又背着上线日期的开发者。顺序按实际工作展开：先是钱包和供应商之间的接口约定，然后是大厅，再是游戏启动，最后是测试和上线第一周。

清单里每一项都对应一个真实的坑，少了它就会出事。建议放进共享文档逐项勾选，没解决的直接整理成问题发给供应商的对接团队。

0. 写第一行代码之前

• 拿到的是完整API文档，而不是销售PDF：所有接口、所有错误码、示例报文都要有。
• 清楚钱包模式。无缝钱包（seamless wallet），即每次投注和派彩供应商都回调你的服务器；或者转账钱包，即你把资金转进供应商那边的余额。本清单默认无缝模式，大多数聚合商卖的也是这种。
• 测试环境的凭证和回调地址与生产环境分开。
• 请求签名规则写得明白：用哪个header、什么算法（一般是HMAC-SHA256）、哪些字段参与签名、按什么顺序。
• 如果供应商要求加白名单，手上有它的出口IP地址。
• 有一个具体的技术对接人，以及几小时内就能得到回复的沟通渠道。

1. 钱包回调

供应商会因为四件事调用你的服务器，这四个接口必须最先做。

• Balance（查余额）。 以玩家币种返回当前可用余额。
• Debit（投注）。 余额够就扣除投注额，返回新余额。余额不足时返回文档规定的错误码，而不是500。
• Credit（派彩）。 加上赢得的金额。金额为零的credit同样合法，必须处理成功；很多游戏工作室会用它来结束一局输掉的游戏。
• Rollback（退款）。 撤销之前某一笔指定的debit。
• 每个响应都按文档要求签名或校验。
• 每次请求都校验传入的签名，签名不对就按文档错误码拒绝。
• 接口响应时间要远低于供应商的超时阈值。去文档里找这个数字：如果写的是3秒，就把99分位做到300毫秒以内。
• 金额以最小货币单位的整数或定点小数存储，绝不能用浮点数。
• debit和credit都带局ID和游戏ID，两个都要存。

场景。 一位玩家用很慢的手机网络转了一把。你的debit成功了，但响应花了4秒，而供应商3秒就放弃了。按它自己的规则，接下来它要么发rollback，要么重发debit。第2节和第3节就是为这一刻准备的。

2. 幂等

• 交易表里对供应商交易ID建了唯一约束。
• 同一个交易ID的debit或credit重复到达，不会再动一次钱，而是返回最初那次的响应，余额数值也一模一样。
• 交易ID相同但金额不同的重复请求，一律拒绝并高级别记录日志。这要么是供应商的bug，要么是攻击。
• 改余额和写交易记录在同一个数据库事务里完成，不存在只有其中一个落库的空窗。
• 同一玩家的并发请求要串行化（行锁或类似机制）。玩家开着两个游戏标签页同时投注，余额只够一笔时，两笔debit不能都通过。

3. 回滚

• rollback会指向它要取消的那笔debit，按供应商交易ID去查。
• 收到一笔从没收到过的debit的rollback：先记一条“墓碑”记录，再返回成功（或文档规定的代码）。如果那笔debit之后才到，这条墓碑能防止你把它扣掉。
• 对已经回滚过的debit再次rollback，返回最初的响应。
• 某局已经有派彩，又来了对其debit的rollback：严格按文档处理。有的供应商不允许，有的要求两笔都撤销。
• 回滚绝不能让余额变成说不清的状态。如果有可能变成负数，现在就定好规则并写下来。

4. 游戏局与未完成的游戏

• 能看到哪些局还开着（收到了debit，没收到结束它的credit）。
• 清楚供应商怎么关闭挂起的局：超时后自动credit、手动工具，还是提工单。
• 奖金和免费旋转产生的派彩都打了标签，好让你的奖金逻辑和现金派彩区别对待。
• 后台能按玩家查看完整的游戏局记录：每次请求、每次响应、时间戳。

5. 币种

• 每个玩家只有一个固定币种，注册时确定，启动游戏时传入，每次回调里原样带回。
• 检查回调里的币种和玩家币种是否一致，不一致就拒绝。
• 每个币种的小数位要对。大多数法币两位，有的零位，有的三位。加密货币可能八位甚至更多，传输时用多少精度要和供应商约定好。
• 大厅里每款游戏都真的支持你给它显示的币种。某个工作室可能支持EUR和USD，却不支持BDT或ETB。
• 每个币种的投注限额要合理。按EUR算很小的最低投注，换成IDR可能很奇怪，换成BTC又可能非常大。
• 报表里不要把显示币种和结算币种混在一起。

6. 游戏列表同步

• 游戏列表通过API定时拉取，至少每天一次，并存到本地。
• 被停用或下架的游戏，下次同步时就从大厅消失，而不是拖到下个季度。
• 如果大厅是人工挑选的，新游戏先进入待审状态，不要直接上大厅。
• 存的是供应商给的稳定游戏ID，而不是游戏名，名字会变。
• 图片缓存在自己这边，或者按适合手机的尺寸输出。
• 每款游戏都带上分类、工作室、设备支持和币种支持信息，这样大厅筛选才不会出错。
• 某个市场要关闭的工作室，用你自己的规则过滤掉，不能靠运气。

7. 启动链接

• 真钱模式启动时传一个和玩家绑定、短时效的会话token，绝不传密码或可重复使用的ID。
• 处理好token过期：旧标签页显示清楚的提示，而不是一个坏掉的框架。
• 启动时设定语言、币种、设备类型以及返回大厅的地址。
• 游戏支持的话，传入充值或收银台链接，让“余额不足”有地方可去。
• 游戏在iframe和新窗口里都能正常打开。有些工作室会在特定域名或浏览器上屏蔽iframe。
• 如果提供试玩，试玩绝不能碰真实钱包，这一点要专门测试。
• 用一台中端手机、4G网络，测量从点击到出现第一帧的时间。超过5秒就会流失玩家。

8. 测试

• 每个要支持的币种准备一个测试玩家。
• 每种游戏类型完整跑一局：老虎机、真人桌台、Crash游戏、桌面游戏、虚拟体育。
• 人为制造失败：让服务器返回超时、500、余额不足错误码，观察供应商接下来怎么做。
• 手动重放重复请求：debit两次、credit两次、rollback两次。
• 乱序请求：rollback先于debit，rollback之后又来credit。
• 同一玩家开两个标签页，同时转动。
• 游戏进行中会话过期。
• 一笔大额派彩和一笔零派彩。
• 测试期内的对账报表和供应商报表完全一致，精确到分。

9. 上线

• 换上生产密钥和回调地址，生产玩家不能再走测试环境。
• 对回调延迟、错误率和签名失败做监控，告警要发给具体的人，而不是一个没人看的仪表盘。
• 每日对账任务：按游戏、按币种把你的汇总和供应商的数据对一遍。
• 预付费模式下，额度告警线要设在远高于零的位置，而且周日也得有人能充值。
• 后台对每款游戏、每个工作室都有一键关停开关。
• 供应商的支持渠道和升级联系人写进运维手册。

10. 上线头七天

• 每天早上查对账。
• 复查所有被拒的回调和未结束的局。
• 按工作室盯住启动错误，一个出问题的工作室就能拖垮整个大厅。
• 向供应商要它那一侧的错误日志，两边对照。

做加密品牌的小团队，如果供应商文档扎实，一周内就能走完这份清单。文档单薄的话，这份清单也正好用来检验供应商：数一数有多少项你不得不去问。无缝钱包聚合商排名和适合新运营商的聚合商两页，正是按这类对接工作给供应商打分的。