HUB və API inteqrasiyası

1) HUB-ın rolu və məsuliyyət sahəsi

• protokolları və formatları birləşdirmək;
• etibarlılığı təmin etmək (retralar, növbələr, polislər, circuit breaker);
• təhlükəsizliyə zəmanət vermək (mTLS, OAuth2, JWT, HMAC, IP-allowlist);
• müşahidəni mərkəzləşdirmək (log, metrika, izləmə);
• provayderin dəyişdirilməsini asanlaşdırmaq (adapterlər + sahələrin mappinqi);
• məhsul komandaları üçün sabit müqavilələr vermək.

2) Dizayn prinsipləri

Konsistent müqavilələr: vahid DTO/hadisələr, ciddi sxem və versiyası.
İdempotentlik: sorğu açarları, deduplikasiya, təhlükəsiz təkrarlamalar.
Fail-safe default: polislər taymaut, backoff, circuit breaker.
Bir funksiya kimi observability: hər şey ölçülə bilər və izlənilə bilər.
Domendən inteqrasiya ayrılması: adapterlər nüvənin biznes məntiqini «bilmir».
Hadisə: asenkron proseslər üçün publish/subscribe.
Version: SemVer müqavilələri və idarə deprikasiya.

3) Yüksək səviyyəli memarlıq

API Gateway: autentifikasiya, rate limits, kanarya relizləri, WAF.
Orkestrator/Router: provayderlər, prioritetlər, failover, smart-routing.
Provayder adapterləri: REST/gRPC/GraphQL/WebSocket, mapping sahələri, yerli caches.
EDA-şina (Kafka/RabbitMQ/NATS): hadisələr «ödəniş yaradıldı», «KYC keçdi», «oyun seansı başladı».
Müqavilə/sxem xidməti: JSON/Avro/Protobuf üçün Schema Registry.
İnteqrasiya vəziyyətinin anbarı: idempotentlik açarları, korelasiya, statuslar.
Müşahidə: Prometheus/OTel + daşbordları və alertlər.
DevPortal: inteqrasiya kataloqları, OpenAPI/Protobuf, nümunələr, qum qutuları.

4) Məlumat müqavilələri və sxemlər

Ciddi sxemlər (JSON Schema/Avro/Protobuf), giriş/çıxışda məcburi validasiya.
Schema Registry uyğunluq siyasəti ilə (backward-compatible).
Dəqiq səhv müqavilələri (vahid kod/detal formatı).

5) Dəstəklənən protokollar

REST (OpenAPI): universal, sənədləşdirilməsi asandır.
gRPC: daxili əlaqələr üçün yüksək performans.
GraphQL: yığılmış nümunələr lazım olduqda.
Webhooks: xarici sistemlərə hadisələr; HMAC imzası, təkrar çatdırılma.
SSE/WebSocket: Canlı hadisələr axını (canlı statuslar, əməliyyatlar).

6) Təhlükəsizlik və giriş

mTLS daxili xidmətlər arasında.
Xarici müştərilər üçün OAuth2/OIDC, qısa ömürlü tokenlər.
Xidmət şəxsiyyət federasiyası üçün JWT; audit claims.
webhooks/kritik kolbeks üçün HMAC imzalar.
IP-allowlist, WAF, RASP, anti-bot filtrləri.
Gizli menecment (KMS/HSM), açar rotasiyası, split-knowledge.
GDPR/PCI DSS: fərdi və kart məlumatlarının minimuma endirilməsi, tokenlaşdırma.

7) Marşrutlaşdırma və orkestr

Policy-based routing: geo, valyuta, uğursuzluq metrik, SLA provayder.
Failover: PSP/provayder ardıcıllığı, avtomatik deqradasiya.
Circuit Breaker: Tez-tez səhvlər üçün sürətli uğursuzluğa davamlı filiallar.
Bulkhead: provayder/tenant/hovuz axını ilə izolyasiya.
Saga/uzun proseslər üçün orkestr (qeydiyyat → KYC → depozit).

8) İdempotentlik və Exactly-Once (mümkün qədər)

Idempotency-Key + status/cavab cache.
Şində hadisələrin deuplikasiyası (korelasiya açarı).
TTL ilə «seen-requests» saxlama.

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 nəticəni saxlayacaq və təkrarlandıqda eyni cavabı qaytaracaq.

9) Növbələr və hadisə şinası

Kafka/NATS/RabbitMQ asenkron addımlar üçün: KYC nəticələri, ödəniş statusları, oyun provayderinin balansı.
Partizan açarları olan mövzular: 'tenantId', 'userId' və ya 'providerId'.
Retention və DLQ (dead-letter) fiksdən sonra avtomatik yenidən göndərmə ilə.
Zəmanətli hadisə yayımı üçün əsas xidmətlərdə Outbox-pattern.

10) Version və uyğunluq

Müqavilələrdə SemVer: 'v1', 'v1. 1`, `v2`.
İki minor versiyanın paralel mövcudluğu, dəqiq deprikasiya qrafiki.
Miqrasiya adapterləri (müvəqqəti sahə mapperləri) hamar keçid üçün.

11) Müşahidə və etibarlılıq

Metriklər: latency p50/p95/p99, error rate, throughput, provayder success ratio, hadisə təsdiqi vaxtı, «Vaxt-to-Wallet».
Trace (OTel): API çağırışından provayderin cavabına qədər 'trace _ id '/' span _ id' vasitəsilə.
Log: strukturlaşdırılmış, 'request _ id', PII/PAN maskalanması.
SLO: məsələn, 99. 9% uğurlu cavablar <1. Kritik yollar üçün 5s.
Alertlər: SLO-error budget, DLQ böyüməsi, retraj/taym anomaliyalarına görə.

12) Qum qutuları və test konturları

Hər bir provayder üçün Sandbox: fiksturlar, cavab emulyatorları, verilənlərin versiyalaşdırılması.
Contract-testing (Pact/Buf) və SDK avtomatik generasiya.
«Pik turnirlər», «ödəniş dalğaları» ssenariləri üzrə yükləmə profilləri.

13) İnteqrasiya kateqoriyaları (iGaming üçün nümunə)

Ödənişlər/nəticələr: PSP, A2A/Open Banking, kriptovalyutalar.
KYC/AML/Risk: şəxsiyyətin/ünvanların yoxlanılması, sanksiya siyahıları, davranış hesabları.
Oyun provayderləri/Aqreqatorlar: sessiyaların başlaması, oyun tokenləri, nəticələrin əks kollbekləri.
Rabitə: email/SMS/push/messencer.
Analitika/BI: Hadisə axını və aqreqatları.
Frod/Çarcbeki: disput mərkəzləri, xəbərdarlıqlar.

14) Multi-tenantlıq və regionallıq

tenantId ilə izolyasiya: şifrələmə açarları, kvotalar, limitlər, qoşulma hovuzları.
Geo-charding: yaxın ROP/regiona marşrutlaşdırma, yerli qaydaların uçotu.
Lokallaşdırılmış provayderlər/ödəniş metodları: yurisdiksiya və KYC səviyyələri üzrə siyahı.

15) Performans və caching

Token Cache (PSP/KYC), provayderlərin meta-məlumat cavabları (TTL).
Connection pooling ireuse TLS sessiyaları.
Async I/O yüksək RPS üçün; adapterlərdə batching.
Rate limits müştəri və provayder perimetrlərində.

16) Keçici ssenarilər (nümunələr)

16. 1 Depozit (kart)

1. 'POST/payments' (idempotent) → Orkestrator → PSP # 1.
2. 2s vaxt; при `5xx/timeout` — retry с backoff; deqradasiya zamanı - PSP # 2.
3. Hadisə 'payment. authorized '→ balans nüvəsi → BI/antifrod.

16. 2 KYC

1. 'POST/kyc/submit' → KYC provayder adapteri.
2. Cavab async: webhook 'kyc. result 'HMAC tərəfindən imzalanır; uğursuzluqla - təkrar çatdırılma (N dəfəyə qədər).
3. Hadisə 'kyc. verified 'şin dərc olunur.

16. 3 Oyun sessiyası

1. 'POST/games/session' → aqreqator adapteri → token sessiyası.
2. Nəticələrin/bahislərin kolbekləri → HUB imza və idempotentliyi təsdiqləyir.
3. Hadisə 'game. round. settled 'ödənişlərin və hesabatların hesablanmasına gedir.

17) Səhvlər və vahid cavab formatı

Коды: `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) Təhlükəsiz webhooks: imza və təkrar

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

drift vaxt yoxlayın və yalnız yeni bildirişlər qəbul edin. Təkrar - N-ə qədər eksponent, sonra DLQ-də.

19) Dəyişikliklər və buraxılışlar

Kanarya adapterləri (1-5% trafik), feature flags per-tenant.
Backward-compatible buraxılışlar: əvvəlcə adapterlər, sonra müqavilələr.
Xarici provayderlər üçün CAB/CRQ, deploi pəncərələri SLA ilə razılaşdırılır.

20) SLA / SLO / OLA

SLA provayder: aptaym ≥ 99. 9%, ack webhooks ≤ 3s, ödənişin finalı ≤ 30s (p95).
SLO HUB: p95 < 1. Kritik end nöqtələrinə 5s, error-rate <0. 3%.
OLA daxili: növbə limitləri, retraj büdcəsi, maksimum DLQ-vaxt.

21) İnteqrasiya kataloqu və DevPortal

Provayderlərin səhifələri: statuslar, adapter versiyaları, sahə tələbləri, çek vərəqləri.
Avtogen SDK (OpenAPI/gRPC), nümunələr, Postman kolleksiyaları, mock-serverlər.
«Test in Sandbox» düyməsi və CI inteqrasiya paylaynları.

22) Təhlükəsizlik və uyğunluq

PII-log redaksiyası, at-rest sahələrinin şifrələnməsi, PAN sahələri yalnız tokenləşdirilmiş formada.
Operator panelləri üçün RBAC/ABAC, ən kiçik imtiyazlar prinsipi.
Razılıq registrləri (GDPR), silinmə/portasiya hüququ.
Yeni inteqrasiyalar üçün risk satıcısı və DPIA.

23) Tətbiq planı (MVP → Scale)

MVP (0-2 ay): Gateway, 1-2 PSP, 1 KYC, 1 oyun aqreqatoru, əsas metriklər, idempotentlik, DLQ.
Phase 2 (3-4 ay): EDA-şina, DevPortal, müqavilə testləri, fallback-marşrutlaşdırma, webhooks-imza.
Phase 3 (5-6 ay): geo-rollover, SLA smart-routing, genişləndirilmiş SLO/alertlər, SDK avtogen, canary ilə klasterlər.

24) Satış öncəsi yoxlama siyahısı

Registry müqavilələr, uyğunluq testləri keçdi.
Taymautların/retrajların/breykerlərin polisləri müəyyən edilmiş və e2e-testlərlə örtülmüşdür.
IdempotencyKey kritik POST/PUT daxildir.
webhooks imzaları yoxlanılır, təkrar konfiqurasiya, DLQ izlənilir.
p95/p99 və error-rate metrləri SLO-ya uyğundur, alertlər bağlıdır.
KMS sirləri, rotasiya yoxlanılır; IP-allowlist/WAF aktivdir.
Runbooks/playbook hadisələr nəşr, on-call boyalı.
DevPortal və qum qutuları tərəfdaşlar üçün mövcuddur, versiyaları sənədləşdirilmişdir.

Qısa nəticə

İnteqrasiya HUB sizin nüvənizlə xarici xidmətlər dünyası arasında sənaye «qalxanı və tərcüməçisidir». Onun gücü ciddi müqavilələr, idempotentlik, hadisə şinası, idarə olunan versiyalaşdırma və müşahidə qabiliyyətindədir. Belə bir memarlıq provayderlərin onbordinqini sürətləndirir, riskləri azaldır, proqnozlaşdırıla bilən SLO-lar verir və trafikin zirvələri altında ölçməni və yeni bazarlara çıxışı asanlaşdırır.