Integrare HUB și legături API

1) Rolul HUB și domeniul de responsabilitate

• unifică protocoalele și formatele;
• asigurarea fiabilității (retribuții, cozi, politici de timeout, întrerupător de circuit);
• garanție de securitate (mTLS, OAuth2, JWT, HMAC, IP-allowlist);
• centralizează observabilitatea (busteni, metrici, urme);
• Simplificarea schimbării furnizorului (adaptoare + maparea câmpului)
• da contracte stabile pentru echipele de produse.

2) Principii de proiectare

Contracte consecvente: DTO/evenimente unice, schemă strictă și versiune.
Idempotency - chei de cerere, eliminare a duplicatelor, reîncărcări sigure.
Default fail-safe: timeout, backoff, politici de întrerupere a circuitului.
Observabilitatea ca funcție: totul este măsurabil și trasabil.
Separarea integrării de domeniu: adaptoarele nu „cunosc” logica de afaceri a nucleului.
Valoarea evenimentului: publicați/abonați-vă pentru procese asincrone.
Versioning: contractele SemVer și depricția gestionată.

3) Arhitectură de nivel înalt

Gateway API: autentificare, limite de rată, eliberări canare, WAF.
Orchestrator/Router: rutare de către furnizori, priorități, failover, smart-routing.
Adaptoare furnizor: REST/gRPC/GraphQL/WebSocket, maparea câmpului, cache-uri locale.
EDA bus (Kafka/RabbitMQ/NATS): evenimente "payment created", "KYC pass'," game session started ".
Contract/Schema de servicii: Schema Registry pentru JSON/Avro/Protobuf.
Stocarea stării de integrare: chei de idempotență, corelație, stări.
Observabilitate: Prometheus/OTel + tablouri de bord și alerte.
DevPortal: directoare de integrare, OpenAPI/Protobuf, exemple, cutii de nisip.

4) Contracte de date și scheme

Scheme stricte (JSON Schema/Avro/Protobuf), validare obligatorie intrare/ieșire.
Registru Schema cu politică compatibilă înapoi.
Convenții clare de eroare (cod uniform/format detaliu).

5) Protocoale acceptate

REST (OpenAPI): versatil, ușor de documentat.
gRPC: performanță ridicată pentru comunicații interne.
GraphQL: când sunt necesare eșantioane agregate.
Webhooks: evenimente la sisteme externe; Semnătură HMAC, redelivery.
SSE/WebSocket: streaming de evenimente live (stări live, tranzacții).

6) Securitate și acces

mTLS între serviciile interne.
OAuth2/OIDC pentru clienți externi, jetoane de scurtă durată.
JWT pentru Serviciul Federația de Identități; cererile de audit.
Semnături HMAC pentru webhook-uri/ciocniri critice.
IP-allowlist, WAF, RASP, filtre anti-bot.
Management secret (KMS/HSM), rotație cheie, split-knowledge.
GDPR/PCI DSS: minimizarea datelor personale și de card, tokenization.

7) Rutare și orchestrare

Rutare bazată pe politici: prin geo, valută, valori de eșec, furnizor SLA.
Failover: secvență PSP/furnizor, degradare automată.
Întrerupător de circuit: ramuri rapide tolerante la erori frecvente.
Perete etanș: izolarea de către furnizor/chiriaș/fir de piscină.
Saga/orchestrație pentru procese lungi (înregistrare → depozit → KYC).

8) Idempotence și exact-o dată (cât se poate de real)

Idempotency-Key + status/response cache.
Deduplicarea evenimentului autobuzului (cheie de corelare).
Depozitare „seen-cereri” cu 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 va salva rezultatul și va returna același răspuns la reluări.

9) Cozi și autobuz eveniment

Kafka/NATS/RabbitMQ pentru pași asincroni: rezultate KYC, statusuri de plată, soldul furnizorului de jocuri.
Temele cu cheile de membru sunt 'tenantId',' userId' sau 'providerId'.
Retenție și DLQ (literă moartă) cu retransmisie automată după remediere.
Outbox model în kernel servicii pentru garantat eveniment de publicare.

10) Versioning și compatibilitate

SemVer pe contracte: "v1", "v1. 1 ',' v2 '.
Existența paralelă a două versiuni minore, un program clar de depricție.
Adaptoare de migrare (mappers temporare de câmp) pentru o tranziție lină.

11) Observabilitate și fiabilitate

Valori: latență p50/p95/p99, rată de eroare, transfer, raport de succes de către furnizori, timp de confirmare a evenimentului, „Timp-la-portofel”.
Urmărirea (OTel): end-to-end 'trace _ id'/' span _ id' de la apelul API la răspunsul furnizorului.
Busteni: structurati, cu corelatie 'request _ id', mascare PII/PAN.
SLO: de exemplu, 99. 9% rata de succes <1. 5s pentru căi critice.
Alerte: prin bugetul SLO-eroare, creșterea DLQ, anomalii retray/timeout.

12) Cutii de nisip și circuite de testare

Sandbox pentru fiecare furnizor: remedieri, emulatoare de răspuns, versioning de date.
Testarea contractelor (Pact/Buf) și autogenerarea SDK.
Profilurile de încărcare în funcție de scenariile „turnee de vârf”, „valuri de plată”.

13) Categorii de integrare (exemplu pentru iGaming)

Plăți/retrageri: PSP, A2A/Open Banking, gateway-uri cripto.
KYC/AML/Risc: verificarea identității/adresei, liste de sancțiuni, notare comportamentală.
Furnizori/agregatori de jocuri: lansări de sesiuni, jetoane de jocuri, colecții de returnare.
Comunicatii: email/SMS/push/messengers.
Analytics/BI: Streaming de evenimente și agregate.
Fraudă/Încărcătoare: centre de dispută, alerte.

14) Multi-chirie și regionalitate

Izolarea TenantId: chei de criptare, cote, limite, piscine de conectare.
Geo-sharing: rutarea către cel mai apropiat RAP/regiune, ținând cont de regulile locale.
Furnizor localizat/metode de plată: lista după jurisdicție și nivelurile KYC.

15) Performanță și cache

Token cache (PSP/KYC), furnizor de răspunsuri metadate (TTL).
Punerea în comun a conexiunii și reutilizarea sesiunilor TLS.
Async I/O pentru SPR ridicat; butching în adaptoare.
Limitele ratei pentru perimetre client și furnizor.

16) Scenarii end-to-end (exemple)

16. 1 Depozit (card)

1. „POST/plăți” → Orchestrator → PSP # 1.
2. Timeout 2s; при '5xx/timeout' - încercați din nou с backoff; în timpul degradării - PSP # 2.
3. Plata evenimentului. autorizat "→ nucleu de echilibru → BI/antifraudă.

16. 2 KYC

1. „POST/kyc/submit” → adaptor furnizor KYC.
2. async: webhook 'kyc. rezultatul "este semnat de HMAC; în caz de eșec - livrare repetată (până la N ori).
3. Eveniment 'kyc. verificat "este publicat la autobuz.

16. 3 Sesiune de joc

1. „POST/jocuri/sesiune” → adaptor agregator → jeton de sesiune.
2. Colectarea rezultatelor/pariurilor → HUB validează semnătura și idempotența.
3. Jocul evenimentului. rotund. decontate "intră în calculul plăților și al raportării.

17) Erori și format de răspuns uniform

Коды: 'INTEGRARE _ TIMEOUT', 'FURNIZOR _ INDISPONIBIL', 'CONTRACT _ VALIDARE _ ESUAT', 'SECURITATE _ SEMNATURA _ 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) Cârlige securizate: Semnați și repetați

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

Verificați deriva de timp și să accepte numai notificări proaspete. Se repetă - exponențial la N, apoi în DLQ.

19) Managementul schimbărilor și versiuni

Adaptoarele canare (1-5% din trafic), prezintă steaguri per chiriaș.
Versiuni compatibile înapoi: adaptoare mai întâi, apoi contracte.
CAB/CRQ pentru furnizorii externi, implementați ferestrele sunt consecvente SLA.

20) SLA/SLO/OLA

Furnizor SLA: uptime ≥ 99. 9%, carti web ack ≤ 3c, finalizare plata ≤ 30c (p95).
SLO HUB: p95 <1. 5c la punctele finale critice, rata de eroare <0. 3%.
OLA în interior: limite de coadă, buget retray, DLQ maxim ori.

21) Catalog de integrare și DevPortal

Pagini furnizor: stări, versiuni adaptor, cerințe de câmp, liste de verificare.
SDK autogen (OpenAPI/gRPC), exemple, colecții Postman, servere mock.
„Testați în Sandbox” buton și linii de integrare CI.

22) Siguranță și conformitate

Ediția PII în jurnale, criptarea câmpurilor de repaus, câmpurile PAN numai în formă tokenizată.
RBAC/ABAC pentru panouri operatoare, cel mai puțin principiu privilegiu.
Registrele de consimțământ (GDPR), dreptul de a șterge/porta.
Risc de furnizor și DPIA pentru noi integrări.

23) Planul de implementare (MVP → Scale)

MVP (0-2 luni): Gateway, 1-2 PSP, 1 KYC, 1 agregator de joc, valori inițiale, idempotență, DLQ.
Faza 2 (3-4 luni): autobuz EDA, DevPortal, teste de contract, rutare de rezervă, semnătura cărților web.
Faza 3 (5-6 luni): clustere cu geo-rollover, smart-routing prin SLA, SLO/alerte extinse, autogen SDK, canar.

24) Lista de verificare pre-vânzare

Contracte în Registru, testele de compatibilitate au trecut.
Politicile timeout/retray/breaker sunt stabilite și acoperite cu teste e2e.
IdempotencyKey este inclus în critic POST/PUT.
Semnăturile sunt verificate, reluările sunt configurate, DLQ este monitorizat.
Valorile p95/p99 și rata de eroare corespund SLO, alertele sunt conectate.
Secretele în KMS, testate prin rotație; IP-allowlist/WAF sunt active.
Runbooks/playbooks incident publicat, de gardă programat.
DevPortal și cutii de nisip sunt disponibile pentru parteneri, versiunile sunt documentate.

Rezumat

Un HUB de integrare este un „scut și traducător” industrial între nucleul dvs. și lumea serviciilor externe. Puterea sa constă în contracte stricte, idempotență, autobuz eveniment, versioning controlat și observabilitate. Această arhitectură accelerează îmbarcarea furnizorului, reduce riscul, oferă SLO-uri previzibile și simplifică scalarea pentru vârfurile de trafic și intrarea pe noi piețe.