API unic pentru furnizori: design, versiune, compatibilitate

Articol complet

💡 18+. Material tehnic pentru echipe de integrare și platformă. Nu este un apel pentru a juca.

1) De ce „API unic” și ce este

Un singur API este o specificație și un set de puncte finale/evenimente prin care orice furnizor de conținut (RGS, studio live, jackpot, KYC/AML, afiliați) comunică cu platforma în conformitate cu aceleași reguli:

model de resurse unificate (jucători, sesiuni, pariuri, decontări, bonusuri, jackpoturi, plăți), contracte de evenimente comune și identificatori, standarde de securitate și compatibilitate înapoi, SDK/instrumente pentru accelerarea integrărilor.

Scopul: reducerea timpului de integrare, reducerea erorilor pe „căi bănești” și furnizarea de upgrade-uri previzibile.

2) Principii de proiectare

1. Domeniu-în primul rând. În primul rând, dicționarul și invarianții (rata, setarea, limitele RG), apoi punctele finale.

2. Compatibilitate în mod implicit. Orice modificare este compatibilă în mod implicit; ruperea schimbărilor strict prin proces.

3. Idempotenţă peste tot. Toate comenzile de bani sunt repetabile fără efecte secundare.

4. Evenimentele sunt sursa adevărului. Operațiuni → evenimente la autobuz; Analytics ascultă autobuzul, nu bate OLTP.

5. Cel mai puțin privilegiu și zero-încredere. Jetoane, semnături, segmentare după marcă/regiune.

6. Observabilitate. End-to-end 'trace _ id', model de eroare ușor de înțeles, metrici p95/p99.

3) Model de resurse (simplificat)

Jucător: Player partea platformei pseudo-ID, geo/valută/RG stări.

Sesiune: un canal între furnizor și platformă ('session _ id', TTL, geo/restricții).

Pariu: autorizare pariu/debit.

Decontare: Rezultatul rundei și câștigul de credit.

Bonus/Pariu: Bonus/status echilibru vager.

Jackpot: contribuții/declanșatoare/plăți.

Eveniment: evenimente de domeniu neschimbate (Kafka/analogi).

Identificatori: 'tenant _ id',' brand _ id', 'region', 'player _ id',' session _ id', 'round _ id',' bet _ id', 'settlement _ id'. Toate - șir, la nivel global unic (UUID/KSUID/fulg de zăpadă), sunt incluse în jurnale și evenimente.

4) contracte API: cereri, răspunsuri, erori

4. 1 Autorizare și securitate

OAuth2 acreditările clienților sau mTLS + Request Body Signature (HMAC/EdDSA).

Скоупы вида: 'pariuri: scrieți', 'așezări: scrieți', 'sesiuni: citiți', 'evenimente: publicați'.

Anteturile sunt necesare în fiecare cerere:

„X-Trace-Id',” X-Brand-Id', „X-Region”, „X-Idempotency-Key”.

4. 2 Exemple de criterii finale

Crearea sesiunii


POST/v1/sesiuni
{
"player_id":"p_19f3," "game_id":"studio:slot_forge_02," "monedă": "EUR", "locale": "de-DE", "constrângeri": {"max _ bet": 5, "rg _ flags': [" self _ exclusion ": false]}
}
→ 201
{
„session_id":"s_456,” „expires_at":"2025-10-23T19:10:00Z”
}

Autorizarea tarifului (cala)


POST/v1/pariuri/autorizare
Anteturi: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456," "bet_id":"b_001," "round_id":"r_8c12," sumă ": {" sumă ": 2. 00, „monedă”:” EUR”}
}
→ 200 {"status": "autorizat", "hold _ id':" h _ zz1 "}

Decontare


POST/v1/pariuri/soluționare
Anteturi: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001," "round_id":"r_8c12," câștig ": {" sumă ": 14. 60, "monedă":" EUR"} ", bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"status": "credited", "settlement _ id':" st _ 77 "}

4. 3 Erori (model unic)

'code': машинное имя ('RG _ BLOCK', 'LIMIT _ EXCEED', 'DUPLICATE', 'IDEMPOTENCY _ MISMATCH', 'INVALID _ STATE', 'AUTH _ FAILED').

„message”: scurt pentru persoana.

"retryable": "adevărat/fals'.

'trace _ id': pentru a căuta jurnalele.

Exemplu:


409 CONFLICT
{
„cod „: „DUPLICAT”, „mesaj”:” Pariu deja autorizat cu o sumă diferită”, „retrizabil”: fals', „trace_id":"tr_a1b2c3”
}

5) Event bus și circuite

5. 1 Subiecte de bază

"jucator. înregistrat „,” sesiune. a început	ended '
"bet. autorizat	decontate
"bonus. emise	consumate
"pariu. progrese. actualizated '
jackpot. contribuție	declanșat
"rg. limită. hit ',' rg. reality_check'
"umed. debit. ", portofel. credite ".

5. 2 Schema de evenimente (Avro/JSON Schema)

json
{
"event_id":"uuid," "event_type":"bet. settled "," occurred_at":"2025-10-23T16:21:05Z, "tenant_id":"brand-7," "regiune": "EU", "player_id":"p_19f3," trace_id":"tr_a1b2c3, "" sarcină utilă ": {
„round_id":"r_8c12,” „pariu „: {„sumă”: 1. 00, „valută”:” EUR”}, „câștig „: {„sumă”: 14. 60, "monedă":" EUR"} ", in_bonus":true
}, „idempotency_key":"bet_r_8c12_1,” „schema_version":"1”. 2. 0"
}

Reguli: evolutie compatibila inapoi a sistemelor, registru + teste contractuale.

6) Versiunea API: strategii și reguli

6. 1 În cazul în care pentru a stoca versiunea

Versiunea traseului: '/v1/... "(doar cache/rută).

Versiunea antet: 'Accept: cerere/vnd. platformă. api + json; versiunea = 1. 2`.

Evenimente: 'schema _ versiune' în câmpul de evenimente + registru.

Practică: cale pentru HTTP, schema_version pentru evenimente, caracteristică steaguri pentru capacitățile de punct.

6. 2 SemVer și tipuri de schimbare

PATCH (minor) - andocare inversă: noi câmpuri opționale, noi puncte finale, noi tipuri de evenimente.

MAJOR - rupere: redenumirea câmpurilor, schimbarea semanticii, ștergerea. Permisă numai prin noul „/vN/” și epuizarea vechiului.

6. 3 Contracte stabile (care nu pot fi încălcate)

Nume și tipuri de câmpuri de identificare cheie ('_ id',' idempotency _ key ').

Model monetar („sumă/monedă”, precizie).

Semantica statutului („autorizat”, „creditat”, „pierdut” etc.).

Idempotență: comportamentul de repetiție este strict definit.

7) Compatibilitate și evoluție

7. 1 Adăugați (în condiții de siguranță)

Noi câmpuri opţionale cu valori implicite.

Evenimente/puncte finale noi fără a le modifica pe cele existente.

Extindere enum cu rezervă în „necunoscut”.

7. 2 Modificări (riscante)

Modificarea tipului de câmp (număr → linie).

opțional → necesar.

Inversarea logicii de afaceri („soluționare” înainte de „autorizare”).

→ nevoie de o nouă versiune majoră și ghid de migrare.

7. 3 Deprecierea

Câmpul/punctul final este marcat cu 'depreciat _ deoarece: 1. 7 ',' eliminat _ în: 2. 0`.

Comunicare: note de lansare, buletin informativ, anteturi de depreciere ('Apus de soare', 'Depreciere').

Urmărirea utilizării căilor „învechite” pentru notificările proactive ale partenerilor.

8) Idempotență și consecvență

Antetul „X-Idempotency-Key” este necesar pentru toate operațiunile de înregistrare.

Semantică: repetați cu aceeași cheie → același rezultat (200 cu același corp).

Cheile sunt legate de o compoziție a parametrilor (de exemplu, 'bet _ id + count').

Sagas privind procesele lungi: „autorizarea → angajarea/blocarea → decontarea creditului →”; compensare - evenimente „rollback”.

9) Paginare, filtre, sortare

Paginare bazată pe cursor (strict preferată „pagină/limită” pentru fire mari).

Unificare: "? cursor =... & limit = 200 & order = asc '.

În răspunsul: 'next _ cursor', 'has _ more'.

Filtre: la timp ('happened _ at _ from/to'), 'tenant _ id',' game _ id', 'status'.

10) Localizări, valute, rezidență de date

Moneda în ISO-4217; precizia este stocată în schemă („scară”), calcule - în unități minore (cenți).

Locali - BCP 47 („en-GB”, „pt-BR”).

În fiecare cerere - „regiune”; PII și tranzacțiile cu numerar nu traversează regiunile.

PII și RLS mascare în vitrine BI.

11) Observabilitate și limite

Rubricile necesare: „X-Trace-Id',” X-Provider-Id', corelație cu evenimentele.

Metrics: p50/p95/p99 latență, rata de eroare (de coduri), debit, coadă lag (pentru evenimente).

Limite de tarif: per furnizor/per brand; răspunsurile din „Retry-After”.

Auditul WORM al modificărilor critice (limite, piscine RTP, formule jackpot).

12) Testarea și calitatea contractelor

Teste de contract (Pact/altele): furnizor ↔ platformă ↔ consumatori de evenimente.

Încărcare: „furtună” de rate/așezări; obiectivele p95.

Cazuri de haos: dublu-livrare, out-of-order, întârzieri portofel.

Sandbox '/sandbox 'cu bani fictivi și testul' player _ id'.

13) SDK, generatoare și documentație

OpenAPI/AsyncAPI → generarea SDK (TypeScript/Java/Kotlin/Go/Rust).

Exemple de cod pentru „authorize/settle/rollback”, retroactive și manipularea erorilor.

Dock live cu exemple de cerere/răspuns (curl + JSON), colecția Postman/Insomnia.

Changelog cu tipuri de schimbare și etichete de compatibilitate.

14) Foaia de parcurs privind migrația (exemplu)

1. v1. 6 → v1. 7 (minor) A fost adăugat câmpul „bonus _ state” în „settle” (opțional).

2. v1. x Anunț EOL: timp de 6 luni - literă + antet „Depreciere” + tablou de bord de utilizare.

3. v2. 0 (major): individual 'wallet. comite „(anterior implicit), este necesar un nou câmp” settlement _ id'.

4. Ghid de migrare: maparea câmpului, cronologie, fichflag-ul „scrierii duble” (publicarea paralelă a evenimentelor „v1 ”/„ v2”).

5. Sunset v1: blocarea noilor integrări, care se extinde numai pentru excepțiile SLA.

15) Liste de verificare

Pentru arhitecți platformă

Există un singur dicționar de entități de domeniu și invarianți.
OpenAPI/AsyncAPI + Schema Registry, semver, procesul de decretări.
Idempotența pe toate operațiunile de scriere; cheile sunt documentate.
Un singur model de eroare și coduri.
Sagas și outbox/CDC pe Money Ways.
Limite de rată, observabilitate, audit WORM.
Sandbox și testele contractuale sunt disponibile pentru parteneri.
Rezidența datelor și RLS/mascare.

Pentru furnizor

Trimit întotdeauna "X-Trace-Id' și" X-Idempotency-Key ".
Am proces solicita repetiții în condiții de siguranță; Eu nu creez dubluri.
Procesarea „depreciere/apus de soare” și citirea Changelog.
Public/citesc evenimente conform schemelor de registru; Păstrez o versiune.
Am reîncercare/backoff și deduplicare pe partea mea.

16) Anti-modele (steaguri roșii)

Modificări manuale ale soldurilor/așezărilor în baza de date.

Publicarea evenimentelor „trecut” outbox/CDC.

Fără idempotență → plăți/debite duplicate.

Amestecarea PII/banilor din diferite regiuni fără a marca „regiune”.

„Liniște” modificări de rupere fără o versiune nouă și decretare.

Generarea manuală a SDK (derivă cu specificații reale).

Migrații big-bang fără steaguri și scris dublu eveniment.

Un singur API nu este doar o „colecție de puncte finale”, ci un contract ecosistemic: un dicționar consistent, invarianți monetari stabili, evenimente versionate, reguli clare de compatibilitate și decretări ușor de gestionat. Bazându-se pe versiunea semantică, idempotență, outbox/CDC, observabilitate și securitate puternică, platforma conectează furnizorii rapid și fără durere, iar upgrade-urile se transformă din risc în rutină.