ინტეგრაციის HUB და API კავშირები

1) HUB როლი და პასუხისმგებლობის სფერო

• ოქმებისა და ფორმატების გაერთიანება;
• უზრუნველყოს საიმედოობა (ხელახალი, რიგები, ტაიმუთის პოლისი, circuit breaker);
• უსაფრთხოების გარანტია (mTLS, OAuth2, JWT, HMAC, IP-allowlist);
• დაკვირვების ცენტრალიზაცია (ლოგოები, მეტრიკები, ტრეკები);
• პროვაიდერის შეცვლის გამარტივება (გადამყვანები + mapping ველები);
• მიეცით სტაბილური კონტრაქტები პროდუქტის გუნდებისთვის.

2) დიზაინის პრინციპები

კომპოზიციური კონტრაქტები: ერთიანი DTO/მოვლენები, მკაცრი სქემა და ვერსია.
Idempotence: მოთხოვნის გასაღებები, დედაპლატაცია, უსაფრთხო გამეორება.
Fail-safe ნაგულისხმევი: Timaut- ის პოლისი, backoff, circuit breaker.
Observability, როგორც ფუნქცია: ყველაფერი იზომება და ტრაქტორი.
ინტეგრაციის განცალკევება დომენისგან: გადამყვანებმა არ იციან ბირთვის ბიზნეს ლოგიკა.
მოვლენა: publish/subscribe ასინქრონული პროცესებისთვის.
ვერსია: SemVer კონტრაქტები და კონტროლირებადი დეკრიმინალიზაცია.

3) მაღალი დონის არქიტექტურა

API Gateway: ავთენტიფიკაცია, rate limits, კანარის გამოშვებები, WAF.
ორკესტრი/Router: მარშრუტი პროვაიდერების გასწვრივ, პრიორიტეტები, failover, smart-routing.
პროვაიდერების გადამყვანები: REST/gRPC/GraphQL/WebSocket, mapping ველები, ადგილობრივი ქეში.
EDA ავტობუსი (Kafka/RabbitMQ/NATS): მოვლენები „შეიქმნა გადახდა“, „KYC დასრულებულია“, „თამაშის სესია დაიწყო“.
კონტრაქტების/სქემების სერვისი: Schema Registry JSON/Avro/Protobuf.
ინტეგრაციის მდგომარეობის საცავი: იდემპოტენტურობის გასაღებები, კორელაცია, სტატუსები.
დაკვირვება: Prometheus/OTel + დაშბორდები და ალერტები.
DevPortal: ინტეგრაციის კატალოგები, OpenAPI/Protobuf, მაგალითები, ქვიშის ყუთები.

4) მონაცემთა და სქემების ხელშეკრულებები

მკაცრი სქემები (JSON Schema/Avro/Protobuf), სავალდებულო შესაბამისობა შესასვლელი/გასასვლელში.
Schema Registry თავსებადობის პოლიტიკასთან.
შეცდომების შესახებ მკაფიო ხელშეკრულებები (კოდის/ნაწილების ერთიანი ფორმატი).

5) მხარდაჭერილი ოქმები

REST (OpenAPI): უნივერსალური, ადვილად დოკუმენტირებული.
GRPC: მაღალი პროდუქტიულობა შიდა ურთიერთობებისთვის.
GraphQL: როდესაც საჭიროა საერთო ნიმუშები.
Webhooks: მოვლენები გარე სისტემებისთვის; HMAC ხელმოწერა, ხელახალი მიწოდება.
SSE/WebSocket: მსუბუქი მოვლენების ნაკადი (პირდაპირი სტატუსები, გარიგებები).

6) უსაფრთხოება და წვდომა

mTLS შიდა სერვისებს შორის.
OAuth2/OIDC გარე მომხმარებლებისთვის, მოკლე ნიშნები.
JWT ოფიციალური იდენტურობის ფედერაციისთვის; Claims აუდიტი.
HMAC ხელმოწერები webhooks/კრიტიკული კოლეგებისთვის.
IP-allowlist, WAF, RASP, ანტიბიოტიკების ფილტრები.
საიდუმლო მენეჯმენტი (KMS/HSM), გასაღების როტაცია, split-knowledge.
GDPR/PCI DSS: პერსონალური და ბარათების მონაცემების შემცირება, ტოკენიზაცია.

7) მარშრუტიზაცია და ორკესტრი

Policy-based routing: geo, ვალუტა, მეტრული უარი, SLA პროვაიდერი.
Failover: PSP/პროვაიდერების თანმიმდევრობა, ავტომატური დეგრადაცია.
Circuit Breaker: სწრაფი დაჟინებული ფილიალები ხშირი შეცდომებით.
Bulkhead: იზოლაცია პროვაიდერების/ტენანტების/ნაკადის გასწვრივ.
საგა/ორკესტრი გრძელი პროცესებისთვის (რეგისტრაცია - KYC - ანაბარი).

8) Idempotence და Exactly-Once (იმდენად, რამდენადაც რეალურია)

Idempotency-Key + ქეში სტატუსი/პასუხი.
მოვლენების დედუპლიკაცია საბურავში (კორელაციის გასაღები).
seen-requests საცავი 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 შეინარჩუნებს შედეგს და განმეორებით დაუბრუნებს იმავე პასუხს.

9) რიგები და მოვლენის საბურავი

Kafka/NATS/RabbitMQ ასინქრონული ნაბიჯებისთვის: KYC შედეგები, გადახდის სტატუსები, თამაშების პროვაიდერის ბალანსი.
თემებს, რომლებსაც აქვთ პლატფორმის გასაღებები: 'tenantId', 'userId' ან 'providerId'.
Retention და DLQ (dead-letter) ავტომატური გადაადგილებით ფიქსაციის შემდეგ.
Outbox შაბლონი ბირთვის სერვისებში, ღონისძიებების გარანტირებული გამოქვეყნებისთვის.

10) ვერსია და თავსებადობა

SemVer კონტრაქტებზე: 'v1', 'v1. 1`, `v2`.
ორი უმცირესობის ვერსიის პარალელური არსებობა, გამოხატვის მკაფიო გრაფიკი.
მიგრაციის გადამყვანები (დროებითი მინდვრის მაპერები) გლუვი გადასასვლელისთვის.

11) დაკვირვება და საიმედოობა

მეტრიკა: latency p50/p95/p99, error rate, throughput, success ratio პროვაიდერებზე, მოვლენების დადასტურების დრო, Time-to-Wallet.
ტრეისი (OTel): 'trace _ id '/' spank _ id' გავლით API ზარიდან პროვაიდერის პასუხამდე.
Logs: სტრუქტურირებული, კორელაციით 'request _ id', შენიღბვა PII/PAN.
SLO: მაგალითად, 99. წარმატებული პასუხების 9% <1. 5 ს კრიტიკული გზებისთვის.
ალერტები: SLO-error budget- ის მიხედვით, DLQ- ის ზრდა, რეტრაის/ტაიმაუტის ანომალიები.

12) ქვიშის ყუთები და ტესტის კონტურები

Sandbox თითოეული პროვაიდერისთვის: ფიქსატორები, პასუხის ემულატორები, მონაცემთა ვერსიები.
Contract-testing (Pact/Buf) და SDK ავტომატური წარმოება.
დატვირთული პროფილები სცენარების მიხედვით „პიკის ტურნირები“, „გადახდის ტალღები“.

13) ინტეგრაციის კატეგორიები (მაგალითი iGaming- ისთვის)

გადახდები/დასკვნები: PSP, A2A/Open Banking, კრიპტო კარიბჭეები.
KYC/AML/რისკი: პიროვნების/მისამართების გადამოწმება, სანქციების სიები, ქცევითი ესკალაცია.
თამაშის პროვაიდერები/აგრეგატორები: სესიების დაწყება, თამაშის ნიშნები, შედეგების საპირისპირო კოლბეკები.
კომუნიკაციები: email/SMS/push/მყისიერი მესინჯერი.
ანალიტიკა/BI: მოვლენების ნაკადი და აგრეგატები.
Frod/Charjbeki: დისპუტაციის ცენტრები, გაფრთხილებები.

14) მულტფილმები და რეგიონალიზმი

TenantId- ის იზოლაცია: დაშიფვრის გასაღებები, კვოტები, ლიმიტები, ნაერთების აუზები.
გეო-შარდინგი: მარშრუტიზაცია უახლოეს ROP/რეგიონში, ადგილობრივი წესების აღრიცხვა.
ლოკალიზებული პროვაიდერები/გადახდის მეთოდები: იურისდიქციის სია და KYC დონე.

15) პროდუქტიულობა და ქეშირება

Tocken Cash (PSP/KYC), მეტამონაცემების პროვაიდერების (TTL) პასუხები.
დაკავშირება აუზის ირმის TLS სესიები.
Async I/O მაღალი RPS- ისთვის; ბატჩინგი ადაპტერებში.
Rate limits კლიენტისა და პროვაიდერის პერიმეტრებზე.

16) სცენარები (მაგალითები)

16. 1 ანაბარი (რუკა)

1. 'POST/payments' (idempotent) - ორკესტრი - PSP # 1.
2. ტაიმუთი 2 ს; при `5xx/timeout` — retry с backoff; დეგრადაციის დროს - PSP # 2.
3. ღონისძიება authorized '- ბალანსის ბირთვი - BI/ანტიფროდი.

16. 2 KYC

1. 'POST/kyc/subit' - KYC პროვაიდერის ადაპტერი.
2. პასუხი async: webhook 'kyc. Result 'ხელს აწერს HMAC; წარუმატებლობის შემთხვევაში - განმეორებითი მიწოდება (N- ჯერ).
3. ღონისძიება 'kyc. verified 'გამოქვეყნებულია საბურავზე.

16. 3 სათამაშო სესია

1. 'POST/games/session' - აგრეგატორის ადაპტერი სესიის ნიშნით.
2. HUB შედეგების/განაკვეთების კოლბეკები იწვევს ხელმოწერას და იდემპოტენტობას.
3. მოვლენა 'game. round. settled 'ითვალისწინებს გადახდებს და ანგარიშებს.

17) შეცდომები და პასუხის ერთიანი ფორმატი

Коды: `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) უსაფრთხო webhooks: ხელმოწერა და გამეორება

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

შეამოწმეთ დროის დრიფტი და მიიღეთ მხოლოდ ახალი შეტყობინებები. განმეორებები - ექსპონენტამდე N, შემდეგ DLQ- ში.

19) ცვლილებებისა და გამოშვებების მენეჯმენტი

კანარის გადამყვანები (ტრეფიკის 1-5%), feature flags per-tenant.
Backward Compatible გამოშვებები: ჯერ გადამყვანები, შემდეგ კონტრაქტები.
გარე პროვაიდერებისთვის CAB/CRQ, უკანა ფანჯრები შეთანხმებულია SLA- ს მიხედვით.

20) SLA / SLO / OLA

SLA პროვაიდერი: აფთიაქი 99. 9%, ack webhooks - 3s, გადახდის ფინალიზაცია - 30s (p95).
SLO HUB: p95 < 1. 5 c კრიტიკულ ენდოინტებზე, error-rate <0. 3%.
OLA შიგნით: რიგის ლიმიტები, რეკრეაციული ბიუჯეტი, მაქსიმალური DLQ დრო.

21) ინტეგრაციისა და DevPortal- ის კატალოგი

პროვაიდერების გვერდები: სტატუსები, გადამყვანების ვერსიები, მინდვრების მოთხოვნები, შემოწმების ფურცლები.
Autogen SDK (OpenAPI/gRPC), მაგალითები, Postman კოლექციები, mock სერვერები.
ღილაკი „Test in Sandbox“ და ინტეგრაციის payplines CI.

22) უსაფრთხოება და შესაბამისობა

PII გამოცემა ლოგოებში, at-rest ველების დაშიფვრა, PAN ველები მხოლოდ ტოკენიზირებული ფორმით.
RBAC/ABAC კამერის პანელებისთვის, მინიმალური შეღავათების პრინციპი.
თანხმობის რეესტრები (GDPR), მოცილების/გადაზიდვის უფლება.
ვენდორის რისკი და DPIA ახალი ინტეგრაციისთვის.

23) განხორციელების გეგმა (MVP-Scale)

MVP (0-2 თვე): Gateway, 1-2 PSP, 1 KYC, 1 თამაშის აგრეგატორი, ძირითადი მეტრიკა, idempotence, DLQ.
Phase 2 (3-4 თვე): EDA ავტობუსი, DevPortal, კონტრაქტის ტესტები, fallback მარშრუტიზაცია, webhooks ხელმოწერა.
Phase 3 (5-6 თვე): მტევანი geo-rollover, SLA ჭკვიანი როტინგი, გაფართოებული SLO/alerts, SDK autogen, canary.

24) ჩეკის სია გაყიდვამდე

კონტრაქტები Registry- ში, თავსებადობის ტესტები დასრულდა.
Polisy Taimauts/retraiv/brakers მოცემულია და დაფარულია e2e ტესტებით.
IdempotencyKey შედის კრიტიკულ POST/PUT.
შემოწმებულია Webhooks- ის ხელმოწერები, კონფიგურაცია ხდება, DLQ აკონტროლებს.
მეტრიკა p95/p99 და error-rate შეესაბამება SLO- ს, ალერტებს უკავშირდება.
საიდუმლოებები KMS- ში, შემოწმებულია როტაცია; IP-allowlist/WAF აქტიურია.
გამოქვეყნებულია Runbooks/playbooks ინციდენტები, არის დახატული.
DevPortal და ქვიშის ყუთები პარტნიორებისთვის ხელმისაწვდომია, ვერსიები დოკუმენტირებულია.

მოკლე დასკვნა

ინტეგრაციის HUB არის ინდუსტრიული „ფარი და მთარგმნელი“ თქვენს ბირთვსა და გარე სერვისების სამყაროს შორის. მისი სიძლიერეა მკაცრი კონტრაქტები, იდემპოტენტობა, ღონისძიების ავტობუსი, კონტროლირებადი ვერსია და დაკვირვება. ასეთი არქიტექტურა აჩქარებს პროვაიდერების ონბორდინგს, ამცირებს რისკებს, იძლევა პროგნოზირებულ SLO- ს და ამარტივებს ტრეფიკის მწვერვალების მასშტაბებს და ახალ ბაზრებზე შესვლას.