Entegrasyon HUB ve API bağlantıları

1) HUB rolü ve sorumluluk alanı

• Protokolleri ve formatları birleştirin;
• Güvenilirliği sağlamak (retrays, kuyruklar, zaman aşımı politikaları, devre kesici);
• Garanti güvenliği (mTLS, OAuth2, JWT, HMAC, IP-allowlist);
• Gözlenebilirliği merkezileştirmek (günlükler, metrikler, izler);
• Değiştirme sağlayıcısını basitleştirin (adaptörler + alan eşleme)
• Ürün ekipleri için istikrarlı sözleşmeler verin.

2) Tasarım ilkeleri

Tutarlı sözleşmeler: Tek DTO/olaylar, sıkı şema ve sürüm.
Idempotency - istek anahtarları, veri tekilleştirme, güvenli yeniden denemeler.
Varsayılan arıza güvenliği: zaman aşımı, geri kapanma, devre kesici ilkeleri.
Bir fonksiyon olarak gözlemlenebilirlik: her şey ölçülebilir ve izlenebilirdir.
Entegrasyonun etki alanından ayrılması: bağdaştırıcılar çekirdeğin iş mantığını "bilmezler".
Olay değeri: Eşzamansız işlemler için yayınla/abone ol.
Sürüm oluşturma: SemVer sözleşmeleri ve yönetilen depriction.

3) Üst düzey mimari

Ağ Geçidi API'si: kimlik doğrulama, hız sınırları, kanarya sürümleri, WAF.
Orchestrator/Router: Sağlayıcılar tarafından yönlendirme, öncelikler, yük devretme, akıllı yönlendirme.
Sağlayıcı adaptörleri: REST/gRPC/GraphQL/WebSocket, alan eşleme, yerel önbellekler.
EDA veri yolu (Kafka/RabbitMQ/NATS): olaylar "ödeme oluşturuldu", "KYC geçti", "oyun oturumu başladı".
Sözleşme/Şema Hizmeti: JSON/Avro/Protobuf için Şema Kaydı.
Entegrasyon durumu depolama: idempotence anahtarları, korelasyon, durumlar.
Gözlemlenebilirlik: Prometheus/OTel + gösterge panoları ve uyarıları.
DevPortal: entegrasyon dizinleri, OpenAPI/Protobuf, örnekler, sanal alanlar.

4) Veri sözleşmeleri ve şemaları

Sıkı şemalar (JSON Şeması/Avro/Protobuf), zorunlu giriş/çıkış doğrulaması.
Geriye dönük uyumlu ilkeye sahip Şema Kayıt Defteri.
Açık hata kuralları (tek tip kod/ayrıntı biçimi).

5) Desteklenen protokoller

REST (OpenAPI): çok yönlü, belgelenmesi kolay.
gRPC: Dahili iletişim için yüksek performans.
GraphQL: toplanmış örneklere ihtiyaç duyulduğunda.
Webhooks: dış sistemlere olaylar; HMAC imzası, yeniden teslim.
SSE/WebSocket: canlı olay akışı (canlı durumlar, işlemler).

6) Güvenlik ve erişim

Dahili hizmetler arasında mTLS.
Dış müşteriler için OAuth2/OIDC, kısa ömürlü belirteçler.
Hizmet Kimlikleri Federasyonu için JWT; Denetim iddiaları.
Webhook'lar/kritik collback'ler için HMAC imzaları.
IP-allowlist, WAF, RASP, anti-bot filtreleri.
Gizli yönetim (KMS/HSM), anahtar rotasyonu, bölünmüş bilgi.
GDPR/PCI DSS: kişisel ve kart verilerinin minimize edilmesi, tokenizasyon.

7) Yönlendirme ve orkestrasyon

Politika tabanlı yönlendirme: coğrafi, para birimi, başarısızlık metrikleri, SLA sağlayıcısı.
Yük devretme: PSP/sağlayıcı dizisi, otomatik bozulma.
Devre Kesici: sık hatalar için hızlı hataya dayanıklı dallar.
Bulkhead: sağlayıcı/kiracı/iplik havuzuna göre izolasyon.
Uzun süreçler için Saga/orkestrasyon (kayıt - KYC - depozito).

8) Idempotence ve Tam Olarak Bir Kez (olabildiğince gerçek)

Idempotency-Key + durum/yanıt önbelleği.
Veri yolu olayı veri tekilleştirme (korelasyon anahtarı).
TTL ile depolama "seen-requests".

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 sonucu kaydeder ve tekrarlarda aynı yanıtı döndürür.

9) Kuyruklar ve etkinlik otobüsü

Asenkron adımlar için Kafka/NATS/RabbitMQ: KYC sonuçları, ödeme durumları, oyun sağlayıcı bakiyesi.
Üyelik anahtarlarına sahip temalar 'tenantId', 'userId' veya 'providerId'dir.
Düzeltme sonrası otomatik yeniden gönderim ile tutma ve DLQ (dead-letter).
Garantili olay yayınlama için çekirdek hizmetlerinde giden kutusu deseni.

10) Sürüm oluşturma ve uyumluluk

Sözleşmelerde SemVer: 'v1', 'v1. 1 ',' v2 '.
İki küçük versiyonun paralel varlığı, net bir depriksiyon programı.
Yumuşak bir geçiş için geçiş bağdaştırıcıları (geçici alan eşleyicileri).

11) Gözlemlenebilirlik ve güvenilirlik

Metrikler: gecikme p50/p95/p99, hata oranı, verim, sağlayıcılara göre başarı oranı, olay onay süresi, "Time-to-Wallet".
İzleme (OTel): API çağrısından sağlayıcı yanıtına kadar uçtan uca 'trace _ id'/' span _ id'.
Günlükler: yapılandırılmış, 'request _ id' korelasyonu, PII/PAN maskeleme.
SLO: Örneğin, 99. %9 başarı oranı <1. Kritik yollar için 5'ler.
Uyarılar: SLO hata bütçesi, DLQ büyümesi, yeniden ödeme/zaman aşımı anomalileri ile.

12) Kum havuzları ve test devreleri

Her sağlayıcı için Sandbox: düzeltmeler, cevap emülatörleri, veri sürümleri.
Sözleşme sınaması (Pact/Buf) ve SDK otojenerasyonu.
"Zirve turnuvaları", "ödeme dalgaları" senaryolarına göre profiller yükleyin.

13) Entegrasyon kategorileri (iGaming için örnek)

Ödemeler/para çekme: PSP, A2A/Open Bankacılığı, kripto ağ geçitleri.
KYC/AML/Risk: kimlik/adres doğrulama, yaptırım listeleri, davranışsal puanlama.
Oyun Sağlayıcıları/Toplayıcılar: Oturum Başlatmaları, Oyun Belirteçleri, İade Kolleksiyonları.
İletişim: e-posta/SMS/push/messengers.
Analytics/BI: Etkinlik akışı ve toplamları.
Dolandırıcılık/Şarj Cihazları: anlaşmazlık merkezleri, uyarılar.

14) Çok kiracılık ve bölgesellik

TenantId izolasyonu: şifreleme anahtarları, kotalar, sınırlar, bağlantı havuzları.
Geo-sharding: Yerel kuralları dikkate alarak en yakın RAP/bölgeye yönlendirme.
Yerelleştirilmiş sağlayıcı/ödeme yöntemleri: yargı ve KYC seviyelerine göre liste.

15) Performans ve önbelleğe alma

Token önbelleği (PSP/KYC), sağlayıcı meta veri yanıtları (TTL).
Bağlantı birleştirme ve TLS oturumlarının yeniden kullanımı.
Yüksek RPS için Async I/O; adaptörlerde yağlama.
Müşteri ve sağlayıcı çevrelerindeki hız sınırları.

16) Uçtan uca senaryolar (örnekler)

16. 1 Depozito (kart)

1. 'POST/payments' - Orkestratör - PSP # 1.
2. Zaman aşımı 2s; при '5xx/timeout' - yeniden deneme с geri alma; Bozulma sırasında - PSP # 2.
3. Olay 'ödeme. Yetkilendirilmiş '- balance core - BI/anti-fraud.

16. 2 KYC

1. 'POST/kyc/submit' - KYC sağlayıcı adaptörü.
2. async: webhook 'kyc. Sonuç 'HMAC tarafından imzalanmıştır; Arıza durumunda - tekrarlanan teslimat (N zamanına kadar).
3. Event 'kyc. Doğrulandı 'yazısı otobüste yayınlandı.

16. 3 Oyun oturumu

1. 'POST/games/session' - toplayıcı bağdaştırıcı - session token.
2. Sonuçların/bahislerin Collbecks - HUB imza ve idempotency doğrular.
3. Olay 'oyunu. yuvarlak. Yerleşmiş ', ödemelerin hesaplanmasına ve raporlamaya girer.

17) Hatalar ve tek tip yanıt 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) Güvenli webhooks: Imzalayın ve tekrarlayın

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

Zaman kaymasını kontrol edin ve yalnızca yeni bildirimleri kabul edin. Tekrarlar - katlanarak N'ye, sonra DLQ'ya.

19) Değişim Yönetimi ve Bültenleri

Kanarya adaptörleri (trafiğin %1-5'i), kiracı başına bayraklar içerir.
Geriye dönük uyumlu sürümler: önce adaptörler, sonra sözleşmeler.
Harici sağlayıcılar için CAB/CRQ, dağıtım pencereleri SLA tutarlıdır.

20) SLA/SLO/OLA

SLA sağlayıcısı: çalışma süresi ≥ 99. 9 %, ack webhooks ≤ 3c, ödeme sonuçlandırma ≤ 30c (p95).
SLO HUB: p95 <1. Kritik uç noktalara 5c, hata oranı <0. 3%.
İçeride OLA: sıra sınırları, bütçeyi yeniden ödeme, maksimum DLQ süreleri.

21) Entegrasyon Kataloğu ve DevPortal

Sağlayıcı sayfaları: durumlar, bağdaştırıcı sürümleri, alan gereksinimleri, kontrol listeleri.
SDK autogen (OpenAPI/gRPC), örnekler, Postman koleksiyonları, sahte sunucular.
"Sandbox'ta Test Et" düğmesi ve CI entegrasyon hatları.

22) Güvenlik ve uyumluluk

Günlüklerde PII sürümü, dinlenme alanlarının şifrelenmesi, PAN alanları yalnızca belirtilmiş biçimde.
Operatör panelleri için RBAC/ABAC, en az ayrıcalık ilkesi.
İzin Kayıtları (GDPR), silme/port hakkı.
Yeni entegrasyonlar için satıcı riski ve DPIA.

23) Uygulama Planı (MVP - Ölçek)

MVP (0-2 ay): Ağ geçidi, 1-2 PSP, 1 KYC, 1 oyun toplayıcı, temel metrikler, idempotency, DLQ.
Aşama 2 (3-4 ay): EDA veri yolu, DevPortal, sözleşme testleri, geri dönüş yönlendirmesi, webhooks imzası.
Faz 3 (5-6 ay): geo-rollover, SLA üzerinden akıllı yönlendirme, genişletilmiş SLO/uyarılar, SDK autogen, kanarya ile kümeler.

24) Satış öncesi kontrol listesi

Kayıt Defterindeki sözleşmeler, uyumluluk testleri geçti.
Zaman aşımı/geri ödeme/kırıcı politikaları e2e testleri ile belirlenir ve kapsanır.
IdempotencyKey kritik POST/PUT'a dahildir.
Webhooks imzaları doğrulanır, tekrarlar yapılandırılır, DLQ izlenir.
P95/p99 ve hata oranı metrikleri SLO'ya karşılık gelir, uyarılar bağlanır.
KMS'deki sırlar, rotasyon test edildi; IP-allowlist/WAF aktiftir.
Runbooks/incident playbooks yayınlandı, on-call planlandı.
DevPortal ve sanal alanlar iş ortaklarına açıktır, sürümleri belgelenmiştir.

Özet

Entegrasyon HUB'ı, özünüz ve dış hizmetler dünyası arasında endüstriyel bir "kalkan ve çevirmen'dir. Onun gücü sıkı sözleşmeler, idempotency, olay otobüsü, kontrollü sürüm ve gözlemlenebilirlik yatıyor. Bu mimari, sağlayıcının katılımını hızlandırır, riski azaltır, öngörülebilir SLO'lar sağlar ve trafik zirveleri için ölçeklendirmeyi ve yeni pazarlara girmeyi basitleştirir.