Integrasiýa HUB we API baglanyşyklary

1) HUB-yň roly we jogapkärçiligi

• teswirnamalary we formatlary birleşdirmek;
• ygtybarlylygy üpjün etmek (retralar, nobatlar, wagt polisleri, circuit breaker);
• howpsuzlygy kepillendirmek (mTLS, OAuth2, JWT, HMAC, IP-allowlist);
• syn edilişini merkezleşdirmek (loglar, metrikler, ýollar);
• üpjün edijiniň çalşylmagyny ýönekeýleşdirmek (adapterler + meýdan mapping);
• önüm toparlary üçin durnukly şertnamalary bermek.

2) Dizaýn ýörelgeleri

Konsistent şertnamalary: ýeke-täk DTO/wakalar, berk shema we wersiýa.
Idempotentlik: soragyň açarlary, de-duplikasiýa, howpsuz gaýtalanmalar.
"Fail-safe": "Time", "backoff", "circuit breaker".
Gözegçilik etmek funksiýa hökmünde: hemme zat ölçelip we yzarlap bolýar.
Integrasiýanyň domenden bölünmegi: adapterler ýadronyň işewürlik logikasyny "bilmeýärler".
Hadysalar: asenkron prosesler üçin publish/subscribe.
Wersiýa: SemVer şertnamalary we dolandyrylýan deprikasiýa.

3) Ýokary derejeli binagärlik

API Gateway: autentification, rate limits, kanar relizleri, WAF.
Orkestrator/Router: üpjün edijiler boýunça marşrut, ileri tutulýan ugurlar, failover, smart-routing.
Üpjün edijileriň adapterleri: REST/gRPC/GraphQL/WebSocket, meýdan mapping, ýerli keşler.
EDA-şina (Kafka/RabbitMQ/NATS): "töleg döredildi", "KYC geçdi", "oýun sessiýasy başlandy" wakalary.
Şertnamalaryň/shemalaryň hyzmaty: JSON/Euro/Protobuf üçin Schema Registry.
Integrasiýa ýagdaýynyň ammary: idempotentligiň açarlary, korelýasiýa, statuslar.
Syn edilişi: Prometheus/OTel + daşbordlar we alertler.
DevPortal: integrasiýa kataloglary, OpenAPI/Protobuf, mysallar, sandyk gutulary.

4) Maglumatlaryň şertnamalary we shemalary

Berk shemalar (JSON Schema/Euro/Protobuf), girelgede/çykyşda hökmany tassyklama.
"Schema Registry" ("Schema registry").
Ýalňyşlyklar barada anyk ylalaşyklar (kod/jikme-jiklikleriň ýeke-täk formaty).

5) Goldanýan teswirnamalar

REST (OpenAPI): ähliumumy, resminamalaşdyrmak aňsat.
gRPC: içerki gatnaşyklar üçin ýokary öndürijilikli.
GraphQL: jemlenen nusgalar zerur bolanda.
Webhooks: daşarky ulgamlara wakalar; HMAC goly, gaýtadan eltip bermek.
SSE/WebSocket: live-wakalaryň akymy (live-statuslar, amallar).

6) Howpsuzlyk we elýeterlilik

mTLS içerki hyzmatlaryň arasynda.
Daşarky müşderiler üçin OAuth2/OIDC, gysga ömürli tokenler.
Hyzmat şahsyýet federasiýasy üçin JWT; claims barlagy.
Webhooks/möhüm kolbekler üçin HMAC gollary.
IP-allowlist, WAF, RASP, anti-bot süzgüçleri.
Gizlin dolandyryş (KMS/HSM), açarlaryň aýlanmagy, split-knowledge.
GDPR/PCI DSS: şahsy we kartoçka maglumatlaryny azaltmak, bellik etmek.

7) Marşrut we orkestr

Policy-based routing: geo, walýuta, şowsuzlyk metrikleri, üpjün edijiniň SLA boýunça.
Failover: PSP/üpjün edijileriň yzygiderliligi, awtomatiki pese gaçmagy.
Circuit Breaker: ýygy-ýygydan ýalňyşlyklarda çalt şowsuzlyga çydamly şahalar.
Bulkhead: üpjün edijiler/tenantlar/akym howuzy boýunça izolýasiýa.
Saga/orkestr üçin uzyn prosesler (hasaba alyş → KYC → goýum).

8) Idempotentlik we Exactly-Once (mümkin boldugyça hakyky)

Idempotency-Key + keş status/jogap.
Tekerdäki wakalaryň duplikasiýasy (korelýasiýa açary).
"seen-requests" c TTL.

http
POST /payments
Idempotency-Key: 3d8c1a4f-7f0e-4a2a-9e5a-2b8d3e7e2c11
Content-Type: application/json

json
{
"tenantId": "eu-casino-12",
"userId": "u-9812",
"currency": "EUR",
"amount": 50. 00,
"method": "card",
"metadata": {"orderId": "ORD-2025-1105-001"}
}

HUB netijäni saklar we gaýtalananda şol jogaby yzyna gaýtarar.

9) Nobatlar we waka tekeri

Kafka/NATS/RabbitMQ asinxron ädimler üçin: KYC-netijeler, töleg ýagdaýlary, oýun üpjün edijisiniň balansy.
Partiýa girişi bolan mowzuklar: 'tenantId', 'userId' ýa-da 'providerId'.
Retention we DLQ (dead-letter).
Wakalaryň kepillendirilen çap edilmegi üçin esasy hyzmatlarda Outbox-pattern.

10) Wersiýalaşdyrmak we gabat gelmek

Şertnamalarda SemVer: 'v1', 'v1. 1`, `v2`.
Iki minor wersiýasynyň parallel bolmagy, deprikasiýanyň anyk tertibi.
Göçmek üçin geçiş adapterleri (meýdanlaryň wagtlaýyn mapperleri).

11) Gözegçilik we ygtybarlylyk

Metrikler: latency p50/p95/p99, error rate, throughput, success ratio, wakalary tassyklamak wagty, "Time-to-Wallet".
Traýsing (OTel): "trace _ id "/" span _ id" API çagyryşyndan üpjün edijiniň jogabyna çenli.
Loglar: gurluşly, 'request _ id' korelýasiýasy, PII/PAN maskalanmagy.
SLO: mysal üçin 99. Üstünlikli jogaplaryň 9% -i <1. 5s kritiki ýollar üçin.
Alertler: SLO-error budget, DLQ beýikligi, retraý/wagt anomaliýalary boýunça.

12) Gum gutulary we synag konturlary

Her bir üpjün ediji üçin Sandbox: fiksturlar, jogap emulýatorlary, maglumatlary wersiýalaşdyrmak.
Contract-testing (Pact/Buf) we SDK awtogenerasiýasy.
"Iň ýokary ýaryşlar", "töleg tolkunlary" ssenarileri boýunça ýükleýji profiller.

13) Integrasiýa kategoriýalary (iGaming üçin mysal)

Tölegler/netijeler: PSP, A2A/Open Banking, kripto-şlýuzlar.
KYC/AML/Töwekgelçilik: şahsyýeti/salgyny barlamak, sanksiýa sanawlary, özüni alyp baryş hasaby.
Oýun üpjün edijileri/Agregatorlar: sessiýalary başlamak, oýun bellikleri, netijeleriň ters kolbekleri.
Aragatnaşyk: email/SMS/push/messengerler.
Analitika/BI: wakalaryň akymy we agregatlar.
Frod/Çarjbeki: jedel merkezleri, duýduryşlar.

14) Köp tenantlyk we sebitlilik

TenantId boýunça izolýasiýa: şifrlemek açarlary, kwotalar, çäkler, birikme howuzlary.
Geo-şarding: iň ýakyn ROR/sebite ugrukdyrmak, ýerli düzgünleri hasaba almak.
Lokallaşdyrylan üpjün edijiler/töleg usullary: ýurisdiksiýa we KYC-derejeler boýunça sanaw.

15) Öndürijilik we kesmek

Tokenlaryň keşi (PSP/KYC), üpjün edijileriň meta-maglumat jogaplary (TTL).
Connection pooling ireuse TLS sessiýalary.
Async I/O ýokary RPS üçin; adapterlerde batching.
Müşderi we üpjün ediji perimetrlerinde rate limits.

16) Çatrykly ssenariýalar (mysallar)

16. 1 Goýum (kart)

1. 'POST/payments' (idempotent) → Orkestrator → PSP # 1.
2. Wagt aýlawy 2s; при `5xx/timeout` — retry с backoff; pese gaçanda - PSP # 2.
3. Waka 'payment. authorized '→ balans özeni → BI/antifrod.

16. 2 KYC

1. 'POST/kyc/submit' → KYC üpjün edijisiniň adapteri.
2. Jogap async: webhook 'kyc. result 'HMAC tarapyndan gol çekilýär; şowsuzlykda - gaýtadan eltip bermek (N gezek çenli).
3. 'kyc. verified 'tekerde çap edilýär.

16. 3 Oýun sessiýasy

1. 'POST/games/session' → agregator adapteri → sessiýanyň belligi.
2. Netijeleriň/nyrhlaryň kollbekleri → HUB goly we idempotentligi tassyklaýar.
3. 'game' wakasy. round. settled 'tölegleriň we hasabatlylygyň hasaplanmagyna girýär.

17) Ýalňyşlyklar we jogabyň ýeke-täk formaty

Коды: `INTEGRATION_TIMEOUT`, `PROVIDER_UNAVAILABLE`, `CONTRACT_VALIDATION_FAILED`, `SECURITY_SIGNATURE_INVALID`.

json
{
"code": "PROVIDER_UNAVAILABLE",
"message": "Primary PSP degraded, switched to fallback",
"correlationId": "9f8e1b6a-1c2d-4b4e-9d31-91c6bc31c1d4",
"provider": "psp-1",
"hint": "Retry allowed; idempotency key required"
}

18) Howpsuz webhooks: gol we gaýtalamak

X-Signature: sha256=hex(hmac_sha256(secret, body + timestamp))
X-Timestamp: 1730812800

Wagtyň driftini barlaň we diňe täze habarnamalary kabul ediň. Gaýtalamalar - N-e çenli eksponent boýunça, soňra DLQ-de.

19) Üýtgetmeleri dolandyrmak we goýbermek

Kanar adapterleri (traffigiň 1-5%), feature flags per-tenant.
Backward-compatible relizleri: ilki adapterler, soň şertnamalar.
Daşarky üpjün edijiler üçin CAB/CRQ, deploý penjireleri SLA boýunça ylalaşylýar.

20) SLA / SLO / OLA

Üpjün edijiniň SLA: apteim ≥ 99. 9%, ack webhooks ≤ 3s, tölegiň tamamlanmagy ≤ 30s (p95).
SLO HUB: p95 < 1. Kritiki endpointlere 5s, error-rate <0. 3%.
Içinde OLA: nobat çäkleri, retraýlaryň býudjeti, iň ýokary DLQ-döwürleri.

21) Integrasiýa katalogy we DevPortal

Üpjün edijileriň sahypalary: statuslar, adapterleriň wersiýalary, meýdanlara bildirilýän talaplar, çek sahypalary.
Awtogen SDK (OpenAPI/gRPC), mysallar, Postman kolleksiýalary, mock-serwerler.
"Test in Sandbox" düwmesi we CI integrasiýa paýlaýjylary.

22) Howpsuzlyk we gabat gelmek

PII-loglarda redaksiýa, at-rest meýdançalaryny şifrlemek, PAN meýdançalary diňe tokenleşdirilen görnüşde.
Operator panelleri üçin RBAC/ABAC, iň az artykmaçlyklar ýörelgesi.
Razylyk registrleri (GDPR), aýyrmak/portlamak hukugy.
Täze integrasiýa üçin wendor-töwekgelçilik we DPIA.

23) Giriş meýilnamasy (MVP → Scale)

MVP (0-2 aý): Gateway, 1-2 PSP, 1 KYC, 1 oýun agregatory, esasy metrikler, idempotentlik, DLQ.
Phase 2 (3-4 aý): EDA-şina, DevPortal, şertnama-synaglar, fallback-marşrut, webhooks-gol.
Phase 3 (5-6 aý): geo-rollover, smart-routing SLA, giňeldilen SLO/alertler, awtogen SDK, canary.

24) Azyk önüminden öň çek-sanawy

Registriýada şertnamalar, laýyklyk synaglary geçdi.
Taýmautlaryň/retraýlaryň/breýkerleriň polisleri berilýär we e2e-synaglar bilen örtülendir.
IdempotencyKey möhüm POST/PUT-a girizildi.
Webhooks gollary barlandy, gaýtalanmalar konfigurasiýa edildi, DLQ gözegçilik edilýär.
p95/p99 we error-rate ölçegleri SLO-a laýyk gelýär, aladalar birikdirildi.
KMS-de syrlar, aýlanyş barlandy; IP-allowlist/WAF işjeň.
Runbooks/wakalaryň oýun kitaplary çap edildi, on-call boýaldy.
DevPortal we gum gutulary hyzmatdaşlar üçin elýeterlidir, wersiýalary resminamalaşdyryldy.

Gysgaça netije

Integrasiýa HUB, ýadrosyňyz bilen daşarky hyzmatlar dünýäsiniň arasynda senagat "galkany we terjimeçisidir". Onuň güýji berk şertnamalarda, idempotentlikde, wakalaryň tekerinde, dolandyrylýan wersiýalaşdyrmakda we gözegçilik astynda saklanýar. Şeýle binagärlik üpjün edijileriň onbordingini çaltlaşdyrýar, töwekgelçilikleri peseldýär, öňünden aýdyp boljak SLO-lary berýär we traffigiň iň ýokary derejesine ýetmegi we täze bazarlara çykmagy aňsatlaşdyrýar.