PlayRouter API v1

§1整体架构 · 混乱止于 PlayRouter

不管选哪种接入方式，架构都是同一张图：你只面对 PlayRouter 一个对手方——上游几十家厂商的事件乱序、重复、迟到，全部在 PlayRouter 层被吸收，到达你的永远是签名可验、幂等可靠、有序的调用流。蓝色方向 A（你调用我们）两种产品皆有；琥珀方向 B（我们回调你的钱包）仅 Seamless 形态存在——两种形态的差异见 §3。

§2部署拓扑 · 运营商选服归属，双向同服，新增延迟保守 ≈50ms / 同城 ≈14ms

聚合器插在资金链路中间，最大的原罪是加延迟。我们的解法：三个服全开放、注册即用——运营商用哪个服，归属就在哪个服，挑离自己钱包后端最近的固定使用，双向流量、全部状态都在这一个服。选址原则只有一条：节点跟着运营商走，厂商在哪我们不关心——没有我们，运营商直连厂商也要走同样的距离；节点贴着运营商，厂商的远近就与新增延迟无关，PlayRouter 真正新增的只有几段同区小跳加处理时间。一个运营商一个家，家就开在运营商门口。

§3两种接入方式 · 怎么选

很多运营商分不清这两种钱包，一句话版本：Seamless = 钱不动，账单飞过来——玩家资金始终在你的系统里，每笔投注/派彩实时回调你的钱包记账；Transfer = 钱搬家，事后看账——先把钱划进厂商侧的游戏钱包，游戏期间没有任何回调，输赢事后拉记录。两个是独立产品：文档自包含，共享的 5 个目录/会话端点字段逐字相同、只是路径前缀不同（迁移时这部分代码只改前缀）；密钥账号级通用（2026-07-20 定案）——一把 pk_/sk_ 对两条产品线同时有效，迁移/增开产品线不换钥，可调端点集取决于账号的产品开通状态、与密钥无关。

怎么选 · 一张表看完

§4.1传输

§4.2签名 · HMAC-SHA256，双向同一方案

资金业务不适合 Bearer——双向调用都必须验证请求方身份与内容完整性。我们采用开发者最熟悉的 HMAC 格式（Stripe webhook 同款），并加上两块：防重放与密钥轮换。

• 验签失败 → HTTP 401（方向 A）；方向 B 运营商返回 200 + {"status":"error","reason":"invalid_signature"}——handler 里一律回 JSON 即可。PlayRouter 按配置故障处理：告警 + 冻结投递，不重试轰炸（误返回 401 等任何 4xx（429 除外——429 按 5xx 进重试时间表）同样入此桶，不出事故）。
• 密钥账号级、两条产品线通用（2026-07-20 定案）：一把 pk_/sk_ 对 Seamless / Transfer 同时有效，增开产品线不换钥。
• 密钥轮换：每环境最多 2 把 active key 并行（配额不分产品线、账号全局至多 4 把），按 X-Playrouter-Key-Id 选 secret 验证，摘掉旧钥即完成轮换——无需停机，无需"联系集成经理"。
• 双向共用同一组密钥（配置概念少一半）：

跨向 / 跨端点反射防御不依赖密钥隔离，由校验层承担：每端点 schema 严格校验，方向 B 回调必含 transaction_id、方向 A 任何端点不接受该字段（反之亦然）——反射请求在字段校验即被 400/422 拒绝，触不到业务逻辑。

§4.3错误模型 · HTTP 码管重试，body 管业务

调用方的重试逻辑应当只看 HTTP 层就能定。我们的规则一句话：HTTP 状态码只回答"接下来该干什么"。

本节讲的是模型，出现的码只是简例——完整错误码目录（方向 A 语义码 Seamless 面 30 个 / Transfer 面 27 个 + 名单逐项 3 个 + 方向 B 5 个 reason，含 message 样例）收在 文档站「附录 · 速查」↗。

{
  "error": {
    "code": "game_not_available",
    "message": "Game 'pg:fortune-tiger' is not enabled for your operator.",
    "doc_url": "https://docs.playrouter.io/errors/game_not_available",
    "request_id": "req_01H...",
    "fields": { "game_code": "not enabled" }
  }
}

每个 4xx/5xx 都带上述错误体（code 给程序判断、message 给人读、fields 逐字段定位）；唯一例外是基础设施层 5xx（LB 超时等）body 可能非 JSON——解析失败时直接按 HTTP 码行动，5xx 的动作本就是重试，不依赖 body。

方向 A 没有"错误藏在 200 里"：200 的 body 永远是成功语义——"成功" = 请求合法且已被受理处理完毕、给出最终业务答复：方向 B 的 declined、Transfer 划拨的 status:"failed"、campaigns/create 的 results 逐项，均属合法业务答复而非错误。API 永不返回 3xx 重定向（会破坏签名与幂等语义）。405/415 属基础设施层、可无错误体（按 HTTP 码行动即可）。

200 { "status": "declined", "reason": "insufficient_funds", "balance": "3.20" }

运营商要处理的全部错误分支 · 一屏写完

30 个语义码是给出事之后的人省排查时间的，不是给写代码的人加活的——code / message 只进日志，不要求逐个 catch；未识别的 code 一律按其 HTTP 码的动作处理（code 列表随时增补，不视为破坏性变更）。代码层面，两个方向合计要写的分支如下，再无其他：

2xx        → 用 body，完事
429        → 按 Retry-After 等待重试
5xx / 超时 → 用同一个 idempotency_key 重试
其余 4xx   → 终态：不重试，error 体记日志，等人来修

记账成功 / 重复交易    → 200 + 余额      ← 记账逻辑，本来就要写
业务拒绝（5 种 reason）→ 200 + declined  ← 同上
验签失败               → 200 + error     ← 一行 if，参考实现自带
JSON 解析失败          → 400             ← 零代码：框架默认行为
自己宕机               → 5xx             ← 零代码：框架/基建自动

§4.4金额与时间

^\d{1,18}(\.\d{1,12})?$

// 钱包回调 wallet/debit
{ "amount": "10.00", "source": "bet" }
// → 运营商响应
{ "status": "ok", "balance": "114.50", "operator_transaction_id": "op-991" }

// 每币种精度由 POST /v1/seamless/currencies 公布（转账面 /v1/transfer/currencies）
{ "data": [{ "code": "BRL",  "decimals": 2, "type": "fiat"   },
           { "code": "USDT", "decimals": 6, "type": "crypto" }] }

2026-07-03T12:00:00.000Z

// 钱包回调 · 事件发生时刻
{ "occurred_at": "2026-07-03T12:00:00.000Z" }
// 对账 transactions/list · 时间窗
{ "from": "2026-07-02T00:00:00.000Z", "to": "2026-07-03T00:00:00.000Z" }
// 投递日志 · 每次尝试
{ "attempted_at": "2026-07-03T12:00:05.200Z", "http_status": 200, "outcome": "ok" }

^[A-Z0-9]{3,4}$
// "BRL", "USD"          ← 法币 = ISO 4217 三字母
// "USDT", "BTC", "DOG"  ← 加密货币 = 3–4 位字母数字

^[a-z]{2}$
// "en", "pt", "zh"      ← ISO 639-1 小写两位

§4.5幂等 · 一套规则，两种钥匙

底层规律只有一条：调用方生成去重键，放进被签名的 body。区别只在键的"身份"——方向 A 的动作本身没有交易编号，要外挂一把一次性钥匙；方向 B 每笔天生就是账目，主键即幂等键。

§4.6投递保证 · 对运营商的三条书面承诺

厂商侧的事件可能乱序、重复、迟到。PlayRouter 的答案：混乱在我们这层终止。关键洞察——乱序对钱包数学无害（win 先到只是余额暂时偏高），有害的是引用悬空。

§4.7重试与限流 · 行为可预期

我们调运营商回调失败时的重试时间表是公开承诺，不是内部实现细节——运营商能精确预期 PlayRouter 的行为。

方向 A 限流

• 标准响应头 RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset；超限 429 + Retry-After。
• 配额按 API Key 计（同商户轮换期的两把 key 各有独立额度），并以下限保证形式公布——每个 API Key 每分钟至少可完成下表次数，实际放行量可能更高；下限值只会放宽、不会收紧。

RateLimit-* 头的值按端点给出（重查询端点与普通端点配额不同），请勿跨端点缓存。建议（非强制）以响应中的 RateLimit-Remaining 为准做自适应节流，而非硬编码固定速率。首次接入需大批量回补历史账单时，可联系我们临时提额。

§4.8DX / AI 原生资产 · 随 v1 交付

这些是产品，不是文档附件。

§4.9游戏素材直链 · assets.playrouter.io

上线一个大堂页，除了接 API，还要给几千款游戏配图标、logo、缩略图——行业常态是找各厂商要素材 zip 包，美术逐张裁切后自建图床，每上新一批游戏再来一轮。我们把这件事做成 imgix 式的图片变换服务：全部游戏素材由我们托管，URL 上改参数即得所需规格，直链嵌进运营商站点即可，无需下载、整理、自建任何图片基础设施。两条产品线共用本服务。

服务形态（DEMO 示意）

每款游戏的各类素材——方图标、横卡、竖版海报、游戏 logo、背景图、厂商 logo——都有一条稳定直链，形态大致如下：

https://assets.playrouter.io/g/{provider}/{game}/tile      ← 方图标
https://assets.playrouter.io/g/{provider}/{game}/thumb     ← 横卡
https://assets.playrouter.io/g/{provider}/{game}/logo      ← 游戏 logo
https://assets.playrouter.io/g/{provider}/{game}/bg        ← 背景图
https://assets.playrouter.io/p/{provider}/logo             ← 厂商 logo

大堂页里直接引用，参数在 URL 上现改现生效：

<img src="https://assets.playrouter.io/g/pragmatic/gates-of-olympus/tile?w=360&h=240&fit=cover&fmt=auto&dpr=2">

变换参数（DEMO 口径）

四条行为约定

• 公开只读、免签名——素材 URL 不含密钥，前端直接引用，不需要任何鉴权改造；写操作不存在，无攻击面扩大。
• 直链授权、流量全包——明确允许热链到运营商生产站点；全球边缘缓存就近出图，流量包含在聚合服务内，不另出账单。
• 地址永不脏——厂商换图时素材地址随内容版本更新下发，旧地址继续可用；运营商侧无需清缓存、无需回源校验。
• 缺图兜底、绝不开天窗——厂商未提供的规格由原图实时派生；连原图都缺时返回带游戏名的统一占位图。大堂页上永远不会出现破图（与 §4.3 的理念一致：可预期的降级优于报错）。

§5环境与配置

• 沙箱数据与生产完全隔离；沙箱含边界模拟器与认证测试套件。
• 密钥前缀可辨识环境——日志里泄露了也立刻知道影响面。
• 上线流程：沙箱跑认证套件全绿 → 后台一键申请生产密钥。