加密賭場

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，可觀察性和嚴格的安全性，可以快速無痛地連接提供商，並且升級已從風險轉變為常規。