加密赌场

Torrent Gear

提供商的单一API：设计、验证、互操作性

文章全文

💡 18+.集成和平台命令的技术材料。不打电话。

1）为什么"单一API"以及它是什么

单个API是任何内容提供商（RGS，实时工作室，头奖，KYC/AML，附属机构）根据以下规则与平台进行通信的规范和一组最终内容/事件：

单一资源模型（玩家,会话,bets, settlements, bonuses, jackpots, payments）,一般事件合同和标识符,安全和向后兼容性标准,SDK/工具,以加快集成。

目标：减少时间到集成度，减少"现金路径"上的错误，并提供可预测的升级。

2）设计原则

1.Domain-first.首先是字典和不变量（投注，设置，RG限制），然后是终端。

2.Compatibility by default.任何更改-默认情况下兼容；严格按照过程进行突破性更改。

3.Idempotency everywhere.所有现金命令都是可重复的，没有副作用。

4.真理的事件来源（分发）。操作→总线事件；分析师听轮胎而不是OLTP。

5.Least privilege & zero-trust.代币，签名，按品牌/地区划分。

6.Observability.端到端"trace_id"，可理解的错误模型，p95/p99度量。

3）资源模型（简化）

播放器：平台侧的伪ID播放器，地理/货币/RG状态。

Session：提供者与平台之间的通道（"session_id"，TTL，地理/限制）。

Bet：授权/出价。

定居：回合的结果和胜利的信用。

奖金/Wager：奖金/残差状态。

Jackpot：会费/触发器/付款。

事件：不可变域事件（Kafka/类似物）。

标识符为："tenant_id"，"brand_id"，"region"，"player_id"，"session_id"，"round_id"，"bet_id"，"settlement_id"。所有字符串，全球独有（UUID/KSUID/Snowflake）都包含在日志和事件中。

4） API合同： 查询、回复、错误

4.1授权和安全性

OAuth2 Client Credentials或mTLS+请求主体签名（HMAC/EdDSA）。

Скоупы вида: `bets:write`, `settlements:write`, `sessions:read`, `events:publish`.

在每个请求中，标题都是强制性的：

`X-Trace-Id`, `X-Brand-Id`, `X-Region`, `X-Idempotency-Key`.

4.2 Endpoint示例

创建会议


POST /v1/sessions
{
"player_id":"p_19f3",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE",  "constraints":{"max_bet":5,"rg_flags":["self_exclusion":false]}
}
→ 201
{
"session_id":"s_456",  "expires_at":"2025-10-23T19:10:00Z"
}

费率授权（hold）


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2.00,"currency":"EUR"}
}
→ 200 { "status":"authorized","hold_id":"h_zz1" }

定居点


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14.60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 { "status":"credited","settlement_id":"st_77" }

4.3错误（单一模型）

`code`: машинное имя (`RG_BLOCK`, `LIMIT_EXCEEDED`, `DUPLICATE`, `IDEMPOTENCY_MISMATCH`, `INVALID_STATE`, `AUTH_FAILED`).

"消息"：简短的人。

`retryable`: `true/false`.

"trace_id"：用于搜索日志。

示例：


409 CONFLICT
{
"code":"DUPLICATE",  "message":"Bet already authorized with a different amount",  "retryable":false,  "trace_id":"tr_a1b2c3"
}

5）事件总线和电路

5.1个基本拓扑

`player.registered`, `session.started	ended`
`bet.authorized	settled
`bonus.issued	consumed
`wager.progress.updated`
`jackpot.contribution	triggered
`rg.limit.hit`, `rg.reality_check`
`wallet.debit.`, `wallet.credit.`

5.2事件图（Avro/JSON计划）

json
{
"event_id":"uuid",  "event_type":"bet.settled",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",  "trace_id":"tr_a1b2c3",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1.00,"currency":"EUR"},   "win":{"amount":14.60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1",  "schema_version":"1.2.0"
}

规则：逆向兼容的电路演变，注册+合同测试。

6） API验证： 策略和规则

6.1何处储存版本

Path版本：'/v1/……'（简单地清除/路由）。

头版： '接受：application/vnd。platform.api+json;version=1.2`.

事件：事件字段+registry中的"schema_version"。

练习：HTTP路径，事件schema_version，点可能性小费。

6.2 SemVer和更改类型

PATCH（次要）-反向市场：新的可选字段、新的端点、新的事件类型。

MAJOR-破解：重命名字段，更改语义，删除。只允许通过新的"/vN/"和旧的解密。

6.3稳定合同（无法中断）

关键标识字段的名称和类型（'_id'、'idempotency_key'）。

货币模型（"amount/currency"，精度）。

状态语义（"authorized"，"credited"，"forfeited"等）。

等效性：重复行为严格定义。

7）兼容性和进化

7.1附录（安全）

带有默认值的新可选字段。

新的事态发展/终点而不改变现有事态发展。

Enum从"unknown"的后退扩展。

7.2更改（risky）

更改字段类型（数字→字符串）。

更改约束力（选择性→要求）。

业务逻辑逆转（"settle"以前称为"authorize"）。

→需要新的主要版本和迁移海德。

7.3撤销

字段/端点标记为"deprecated_since： 1"。7`, `removed_in: 2.0`.

通讯：发布注释，通讯，发布头条（"Sunset"，"Deprecation"）。

跟踪使用"过时"路径进行主动伙伴通知。

8）相同性和一致性

标题"X-Idempotency-Key"对于所有记录操作都是必需的。

语义：重复使用相同的键→相同的结果（200与以前的身体）。

键绑定到参数组成（例如"bet_id+amount"）。

长过程的传奇："authorize → commit/lock → settle → credit"；补偿-"rollback"事件。

9）分割,过滤器,分类

基于Cursor的分区（对于大流，严格优先于"page/limit"）。

统一：'？cursor=……＆limit=200＆order=asc'。

答案是："next_cursor"，"has_more"。

过滤器：按时间（'occurred_at_from/to'、'tenant_id'、'game_id'、'status'。

10） Locali,货币,数据居住

ISO-4217货币；精度存储在方案中（"scale"），计算存储在次要单位（cents）中。

Locali是BCP 47（"en-GB"，"pt-BR"）。

每个请求都是"区域"；PII和货币交易不会跨越地区。

在BI店面中掩盖PII和RLS。

11）可观察性和限制

强制性标题："X-Trace-Id"，"X-Provider-Id"，与事件相关。

度量标准：p50/p95/p99 latency，error rate（按代码），throughput，queue lag（用于事件）。

Rate limits: per provider / per brand;对"Retry-After"的回应。

WORM审核关键更改（限制，RTP池，头奖公式）。

12）合同测试和质量

合同测试（Pact/其他）：提供商↔平台↔事件用户。

负载：投注/设置的"风暴"；目标p95。

溷沌桉例：双发、订单外、钱包延迟。

带有虚假金钱和测试"player_id"的沙盒。

13） SDK、发电机和文档

OpenAPI/AsyncAPI → SDK生成（TypeScript/Java/Kotlin/Go/Rust）。

"authorize/settle/rollback"、转发和错误处理的示例代码。

带有查询/响应示例（curl+JSON）的实时坞站，Postman/Insomnia集合。

具有更改类型和兼容性标签的Changelog。

14）迁移路线图（示例）

1.v1.6 → v1.7 （minor）：在"settle"（选项）中添加了"bonus_state"字段。

2.v1.x EOL公告：6个月-信件+"Deprecation"头条+使用的行车记录仪。

3.v2.0（主要）：单独的'wallet。commit'（以前称为implicit），需要新字段"settlement_id"。

4.迁移海德：mapping field，timeline，fichflag"双字母"（并行发布"v1"/"v2"事件）。

5.Sunset v1：阻止新的集成,仅通过SLA例外进行扩展。

15）支票单

对于平台架构师

有一个域实体和不变量的单一词典。
OpenAPI/AsyncAPI+Schema Registry, semver, process depreprected.
所有写作操作的幂等性；密钥被记录下来。
单一错误模型和代码。
Sagi和outbox/CDC在现金路径上。
Rate-limits, observability, WORM审核。
合作伙伴可以使用沙盒和合同测试。
数据驻留和RLS/掩码。

对于提供商

始终发送"X-Trace-Id"和"X-Idempotency-Key"。
请求的重播安全处理；我不是在创造。
处理"Deprecation/Sunset"并阅读Changelog。
发表/阅读有关注册计划的事件；保存版本。
我身边有背影/背影和重复数据消除。

16）反模式（红旗）

在DB中手动编辑平衡/设置。

发布outbox/CDC事件。

缺少idempotency →付款/借记。

PII/不同地区的货币混合，没有"区域"标签。

"安静"的突破性变化，没有新版本和解密。

手动SDK生成（从实际辐条漂移）。

Big-bang迁移没有鞭打和双重事件写作。

单个API不仅是"尾矿集合"，而且是生态系统的合同：一致的字典，稳定的货币不变性，有转换的事件，可理解的互操作性规则和可管理的减排。该平台依靠语义反射，等效性，outbox/CDC，可观察性和严格的安全性，可以快速无痛地连接提供商，并且升级已从风险转变为常规。