Łącza integracyjne HUB i API

1) Rola HUB i obszar odpowiedzialności

• ujednolicenie protokołów i formatów;
• zapewnienie niezawodności (przekaźniki, kolejki, polityka timeout, wyłącznik);
• zabezpieczenie gwarancyjne (mTLS, OAuth2, JWT, HMAC, IP-permlist);
• scentralizować obserwowalność (kłody, mierniki, ślady);
• Uproszczenie zmieniającego się dostawcy (adaptery + mapowanie pól)
• dać stabilne kontrakty dla zespołów produktów.

2) Zasady projektowania

Spójne umowy: pojedynczy DTO/wydarzenia, ścisły schemat i wersja.
Idempotence - klucze żądania, deduplikacja, bezpieczne ponowne próby.
Domyślne zabezpieczenie awarii: timeout, backoff, zasady wyłącznika.
Obserwowalność jako funkcja: wszystko jest mierzalne i identyfikowalne.
Oddzielenie integracji od domeny: adaptery nie „znają” logiki biznesowej jądra.
Wartość zdarzenia: publikacja/subskrybowanie procesów asynchronicznych.
Wersioning: SemVer kontraktuje i zarządza deprymacją.

3) Architektura wysokiego poziomu

Interfejs API Gateway: uwierzytelnianie, limity stawek, wydania kanaryjskie, WAF.
Orchestrator/Router: routing przez dostawców, priorytety, awaria, inteligentne routing.
Adaptery dostawcy: REST/gRPC/GraphQL/WebSocket, mapowanie pola, lokalne bufory.
Autobus EDA (Kafka/RabbitMQ/NATS): zdarzenia „płatność utworzona”, „KYC przeszedł”, „sesja gry rozpoczęła się”.
Umowa/usługa programu: rejestr schematów dla JSON/Avro/Protobuf.
Stan integracji: klucze idempotencji, korelacja, statusy.
Obserwowalność: Prometeusz/OTel + deski rozdzielcze i wpisy.
DevPortal: katalogi integracyjne, OpenAPI/Protobuf, przykłady, piaskownice.

4) Umowy i schematy dotyczące danych

Rygorystyczne schematy (JSON Schema/Avro/Protobuf), obowiązkowa walidacja wejściowa/wyjściowa.
Rejestr schematu z zasadami kompatybilnymi wstecz.
Wyraźne konwencje o błędach (jednolity format kodu/szczegółów).

5) Obsługiwane protokoły

REST (OpenAPI): wszechstronny, łatwy do udokumentowania.
gRPC: wysoka wydajność komunikacji wewnętrznej.
GraphQL: gdy potrzebne są próbki zagregowane.
Haki internetowe: wydarzenia dla systemów zewnętrznych; Podpis HMAC, redelivery.
SSE/WebSocket: transmisja na żywo (status na żywo, transakcje).

6) Bezpieczeństwo i dostęp

mTLS między służbami wewnętrznymi.
OAuth2/OIDC dla klientów zewnętrznych, krótkotrwałe żetony.
JWT dla Federacji Usług Tożsamości; roszczeń z audytu.
Podpisy HMAC dla haków/krytycznych kolbacków.
Lista IP, WAF, RASP, filtry anty-bot.
Tajne zarządzanie (KMS/HSM), rotacja klucza, wiedza o podziale.
RODO/PCI DSS: minimalizacja danych osobowych i kart, tokenizacja.

7) Routing i orkiestra

Routing oparty na zasadach: według geo, waluta, wskaźniki awarii, dostawca SLA.
Awaria: sekwencja PSP/dostawcy, automatyczna degradacja.
Wyłącznik: szybkie gałęzie tolerancyjne dla częstych błędów.
Grodzie: izolacja przez dostawcę/najemcę/basen nici.
Saga/orkiestra na długie procesy (rejestracja → KYC → depozyt).

8) Idempotencja i dokładnie raz (tak prawdziwe, jak dostaje)

Idempotence-Key + status/response cache.
Deduplikacja zdarzeń autobusowych (klucz korelacji).
Przechowywanie „widzialne żądania” z 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 zapisze wynik i zwróci tę samą odpowiedź na powtórki.

9) Kolejki i autobus imprezowy

Kafka/NATS/RabbitMQ dla asynchronicznych kroków: wyniki KYC, statusy wypłat, saldo dostawcy gier.
Tematy z klawiszami członkostwa to 'tenantId',' ‡ Id' lub ' Id'.
Retencja i DLQ (dead-letter) z automatyczną resubmisją po naprawie.
Wzorzec skrzynki zewnętrznej w usługach jądra dla gwarantowanego publikowania wydarzeń.

10) Wersioning i kompatybilność

SemVer w sprawie umów: "v1", "v1. 1 "," v2 ".
Równoległe istnienie dwóch mniejszych wersji, wyraźny harmonogram deprymacji.
Adaptery migracyjne (tymczasowe mapery pola) umożliwiające płynne przejście.

11) Obserwowalność i niezawodność

Metryki: latency p50/p95/p99, wskaźnik błędów, przepustowość, wskaźnik sukcesu przez dostawców, czas potwierdzenia zdarzenia, „Time-to-Wallet”.
Śledzenie (OTel): end-to-end 'trace _ id'/' span _ id' z połączenia API do odpowiedzi dostawcy.
Dzienniki: ustrukturyzowane, z korelacją 'request _ id', maskowaniem PII/PAN.
SLO: na przykład 99. 9% wskaźnik sukcesu <1. 5s dla ścieżek krytycznych.
Wpisy: według budżetu błędu SLO, wzrostu DLQ, retray/anomalii timeout.

12) Piaskownice i obwody badawcze

Piaskownica dla każdego dostawcy: poprawki, emulatory odpowiedzi, wersioning danych.
Badanie kontraktowe (Pact/Buf) i autogeneracja SDK.
Załaduj profile zgodnie ze scenariuszami „turnieje szczytowe”, „fale płatnicze”.

13) Kategorie integracji (przykład dla iGaming)

Płatności/wypłaty: PSP, A2A/Open Banking, crypto gateways.
KYC/AML/Risk: weryfikacja tożsamości/adresu, listy sankcji, punktacja behawioralna.
Dostawcy/agregatorzy gier: Uruchamianie sesji, Żetony do gier, Kolekcje powrotne.
Komunikacja: e-mail/SMS/push/messengers.
Analityka/BI: Transmisja strumieniowa i agregaty wydarzeń.
Oszustwa/Ładowacze: centra sporów, wpisy.

14) Wielopoziomowość i regionalność

Izolacja TenantId: klucze szyfrowania, kontyngenty, limity, puli połączeń.
Geowłóknina: trasa do najbliższego RAP/regionu, z uwzględnieniem lokalnych zasad.
Zlokalizowany dostawca/metody płatności: lista według jurysdykcji i poziomów KYC.

15) Wydajność i buforowanie

Token cache (PSP/KYC), dostawca odpowiedzi metadanych (TTL).
Łączenie połączeń i ponowne wykorzystanie sesji TLS.
Async I/O dla wysokiego RPS; Masowanie w adapterach.
Oceń limity obwodów klienta i dostawcy.

16) Scenariusze końcowe (przykłady)

16. 1 Depozyt (karta)

1. 'POST/payments' → Orchestrator → PSP # 1.
2. Timeout 2s; мра '5xx/timeout' - retry „plecak”; podczas degradacji - PSP # 2.
3. Płatność za zdarzenie. autoryzowany "→ balance core → BI/anti-fraud.

16. 2 KYC

1. „POST/kyc/submit” → adapter dostawcy KYC.
2. async: webhook 'kyc. wynik "podpisuje HMAC; w przypadku awarii - wielokrotna dostawa (do N razy).
3. Wydarzenie 'kyc. zweryfikowany "jest publikowany do autobusu.

16. 3 Sesja gier

1. 'POST/gry/sesja' → adapter agregatora → token sesyjny.
2. Kolbecks wyników/zakładów → HUB zatwierdza podpis i idempotencję.
3. Gra wydarzeń. runda. rozliczane "obejmuje obliczanie płatności i sprawozdawczość.

17) Błędy i jednolity format odpowiedzi

Кода: „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) Bezpieczne haki internetowe: Podpisz i powtórz

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

Sprawdź dryf czasowy i zaakceptuj tylko nowe powiadomienia. Powtarza - wykładniczo do N, a następnie w DLQ.

19) Zarządzanie zmianami i wydania

Adaptery kanaryjskie (1-5% ruchu), posiadają flagi na lokatora.
Wsteczne wersje kompatybilne: adaptery najpierw, a następnie kontrakty.
CAB/CRQ dla zewnętrznych dostawców, wdrożyć okna są spójne SLA.

20) SLA/SLO/OLA

Dostawca SLA: czas uptime ≥ 99. 9%, ack webhooks ≤ 3c, zakończenie płatności ≤ 30c (p95).
SLO HUB: p95 <1. 5c do krytycznych punktów końcowych, wskaźnik błędu <0. 3%.
OLA wewnątrz: limity kolejki, budżet retrasy, maksymalny czas DLQ.

21) Katalog integracji i DevPortal

Strony dostawcy: statusy, wersje adapterów, wymagania dotyczące pola, listy kontrolne.
Autogen SDK (OpenAPI/gRPC), przykłady, kolekcje listonoszy, serwery makietowe.
Przycisk „Test in Sandbox” i linie integracyjne CI.

22) Bezpieczeństwo i zgodność

Edycja PII w logach, szyfrowanie pól odpoczynku, pola PAN tylko w tokenizowanej formie.
RBAC/ABAC dla paneli operatorów, zasada najmniejszego przywileju.
Rejestry zgody (RODO), prawo do usunięcia/portu.
Dostawca-ryzyko i DPIA dla nowych integracji.

23) Plan realizacji (MVP → skala)

MVP (0-2 miesiące): Gateway, 1-2 PSP, 1 KYC, 1 agregator gry, metryki wyjściowe, idempotencja, DLQ.
Faza 2 (3-4 miesiące): autobus EDA, DevPortal, testy kontraktowe, routing awaryjny, podpis haków internetowych.
Faza 3 (5-6 miesięcy): klastry z geo-rollover, inteligentne routing przez SLA, rozszerzone SLO/wpisy, SDK autogen, kanarka.

24) Lista kontrolna przedsprzedaży

Kontrakty w rejestrze, testy zgodności przeszły.
Zasady timeout/retray/breaker są ustawione i pokryte testami e2e.
Idempot Klucz jest zawarty w krytycznym POST/PUT.
Podpisy webhooks są weryfikowane, repliki są konfigurowane, DLQ jest monitorowane.
p95/p99 i mierniki błędów odpowiadają SLO, alerty są podłączone.
Sekrety w KMS, obrót testowany; Aktywna jest lista IP/WAF.
Runbooks/incident playbooks opublikowane, dyżur zaplanowany.
DevPortal i piaskownice są dostępne dla partnerów, wersje są udokumentowane.

Podsumowanie

Integracja HUB to przemysłowa „tarcza i tłumacz” między Twoim rdzeniem a światem usług zewnętrznych. Jego siła polega na ścisłych kontraktach, idempotencji, autobusie imprezowym, kontrolowanej wersji i obserwowalności. Ta architektura przyspiesza dostawcę na pokładzie, zmniejsza ryzyko, zapewnia przewidywalne SLO i upraszcza skalowanie dla szczytów ruchu i wejścia na nowe rynki.