Интеграциялык HUB жана API

1) HUB ролу жана жоопкерчилик аймагы

• протоколдорду жана форматтарды унификациялоо;
• ишенимдүүлүгүн камсыз кылуу (retry, кезек, Police таймаут, circuit breaker);
• коопсуздук кепилдик (mTLS, OAuth2, JWT, HMAC, IP-allowlist);
• байкоону борборлоштуруу (логи, метрика, трассировка);
• провайдерди алмаштырууну жөнөкөйлөтүү (адаптерлер + талаалар);
• продукт командалары үчүн туруктуу контракттарды берүү.

2) Дизайн принциптери

Консистенттик келишимдер: бирдиктүү DTO/окуялар, катуу схема жана версия.
Идемпотенттүүлүк: суроо-талаптын ачкычтары, дедупликация, коопсуз кайталоолор.
Fail-safe демейки: Police таймаут, 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 өттү", "оюн сессиясы башталды".
Контракттар/схемалар кызматы: JSON/Euro/Protobuf үчүн Schema Registry.
Интеграциялардын абалынын сактагычы: демпотенттүүлүктүн ачкычтары, корелляция, статустар.
Байкоо: Prometheus/OTel + дашборддор жана алерталар.
DevPortal: интеграция каталогдору, OpenAPI/Protobuf, мисалдар, Sandbox.

4) Маалыматтар контракттары жана схемалар

Катуу схемалар (JSON Schema/Euro/Protobuf), кирүү/чыгууда милдеттүү валидация.
Шайкештик саясаты менен Schema Registry (backward-compatible).
Каталар жөнүндө так макулдашуулар (коддун/деталдардын бирдиктүү форматы).

5) Колдогон протоколдор

REST (OpenAPI): универсалдуу, документтештирүү оңой.
gRPC: ички байланыштар үчүн жогорку аткаруу.
GraphQL: чогултулган үлгүлөрү керек болгондо.
Webhooks: тышкы системаларга окуялар; кол HMAC, кайра жеткирүү.
SSE/WebSocket: Live-окуялар агымы (Live-статустар, бүтүмдөр).

6) Коопсуздук жана жеткиликтүүлүк

mTLS ички кызматтардын ортосунда.
тышкы кардарлар үчүн OAuth2/OIDC, кыска мөөнөттүү токендер.
JWT кызматтык иденттүүлүк федерациясы үчүн; аудит claims.
HMAC кол webhooks/маанилүү Коллбек үчүн.
IP-allowlist, WAF, RASP, анти-бот чыпкалар.
Secret Management (KMS/HSM), ачкычтарды айлантуу, split-knowledge.
GDPR/PCI DSS: жеке жана карта маалыматтарын минималдаштыруу, tokenization.

7) Багыттоо жана оркестр

Policy-based routing: гео, акча, ийгиликсиз метрика, SLA провайдер.
Failover: PSP/провайдерлер ырааттуулугу, автоматтык деградация.
Circuit Breaker: тез бузулууга туруктуу бутактары көп ката.
Bulkhead: берүүчүлөр/тенанттар/көлмө агымдары боюнча обочолонуу.
Saga/узак жараяндар үчүн оркестр (каттоо → KYC → депозиттик).

8) Idempotentity жана Exactly-Once (абдан реалдуу)

Idempotency-Key + статус/жооп кэш.
Шинадагы окуялардын дедупликациясы (корелляциянын ачкычы).
TTL менен "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 натыйжаны сактап калат жана кайталаганда ошол эле жоопту кайтарып берет.

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 боюнча провайдерлер, тастыктоо убактысы, "Убакыт-коштомо".
Trace (OTel): аркылуу 'trace _ id '/' span _ id' API чакыруудан провайдердин жообуна чейин.
Логи: структураланган, 'request _ id', PII/PAN жашыруу.
SLO: мисалы, 99. 9% ийгиликтүү жооптор <1. критикалык жолдор үчүн 5s.
Алерталар: SLO-error budget, DLQ өсүшү, ретрайлардын/таймауттардын аномалиялары боюнча.

12) Кум жана тесттик контурлар

Ар бир провайдер үчүн Sandbox: фикстуралар, жооп эмуляторлору, маалыматтарды версиялоо.
Contract-testing (Pact/Buf) жана SDK автогенерация.
"Эң жогорку турнирлер", "төлөм толкундары" сценарийлери боюнча жүктөө профилдери.

13) Интеграция категориялары (iGaming үчүн мисал)

Төлөмдөр/корутундулар: PSP, A2A/Open Banking, крипто-шлюздар.
KYC/AML/Тобокелдик: инсанды/даректерди текшерүү, санкциялык тизмелер, жүрүм-турум эсеби.
Оюн провайдерлери/Агрегаторлор: сессияларды баштоо, оюн токендери, тескери жыйынтыктар.
Байланыш: email/SMS/push/мессенджерлер.
Analytics/BI: агымы окуялар жана агрегаттар.
Фрод/Чарджбеки: диспут борборлору, эскертүүлөр.

14) Көп тенанттуулук жана регионалдык

tenantId боюнча изоляция: шифрлөө ачкычтары, квоталар, лимиттер, байланыш пулдары.
Гео-шардинг: жакынкы РОР/регионго багыттоо, жергиликтүү эрежелерди эсепке алуу.
Жергиликтүү провайдер/төлөм ыкмалары: юрисдикция жана KYC-деңгээл боюнча тизме.

15) Аткаруу жана кэш

Токендердин кэши (PSP/KYC), провайдерлердин мета-маалымат жооптору (TTL).
Connection pooling иreuse TLS сессиялар.
жогорку RPS үчүн Async I/O; адаптерлерде батчинг.
Кардар жана провайдер периметрлеринде Rate limits.

16) Толук сценарийлер (мисалдар)

16. 1 Депозит (карта)

1. 'POST/payments' (idempotent) → Оркестратор → PSP # 1.
2. Убакыт 2с; при `5xx/timeout` — retry с backoff; бузулганда - PSP # 2.
3. Окуя 'payment. authorized '→ баланс өзөгү → BI/антифрод.

16. 2 KYC

1. 'POST/kyc/submit' → KYC провайдер адаптер.
2. Жооп async: webhook 'kyc. result 'HMAC тарабынан кол коюлат; ийгиликсиз болгон учурда - кайра жеткирүү (N эсеге чейин).
3. Иш-чара 'kyc. verified 'шинага жарыяланган.

16. 3 Оюн сессиясы

1. 'POST/games/session' → агрегатор адаптер → сессиянын белгиси.
2. Colbeky натыйжалары/коюмдар → 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

убакыт drift текшерүү жана гана жаңы билдирүүлөрдү кабыл алуу. Кайталоо - экспонент боюнча N чейин, андан кийин DLQ.

19) Өзгөрүүлөрдү башкаруу жана релиздер

Канар адаптерлер (1-5% жол), feature flags per-tenant.
Backward-compatible релиздер: биринчи адаптерлер, андан кийин келишимдер.
Тышкы провайдерлер үчүн CAB/CRQ, деплой терезелери SLA боюнча макулдашылган.

20) SLA / SLO / OLA

Провайдердин SLA: аптайм ≥ 99. 9%, ack webhooks ≤ 3с, төлөм аяктоо ≤ 30с (p95).
SLO HUB: p95 < 1. Критикалык эндпоинттерге 5с, error-rate <0. 3%.
OLA ичинде: кезек лимиттери, retrains бюджети, максималдуу DLQ-жолу.

21) Интеграция каталогу жана DevPortal

Провайдерлердин беттери: статустар, адаптерлердин версиялары, талааларга талаптар, чек баракчалары.
Autogen SDK (OpenAPI/gRPC), мисалдар, Postman жыйнактары, mock-серверлер.
"Test in Sandbox" баскычы жана CI интеграциялык бөлүштүрүү.

22) Коопсуздук жана комплаенс

Логдордо PII редакциясы, ат-rest талааларын шифрлөө, PAN талаалары токендештирилген түрдө гана.
Оператордук панелдер үчүн RBAC/ABAC, минималдуу артыкчылыктар принциби.
Макулдук регистрлери (GDPR), алып салуу/таштоо укугу.
Жаңы интеграциялар үчүн сатуучу-тобокелдик жана DPIA.

23) ишке ашыруу планы (MVP → Scale)

MVP (0-2 ай.): Gateway, 1-2 PSP, 1 KYC, 1 оюн агрегатору, негизги метриктер, боштук, DLQ.
Phase 2 (3-4 ай.): EDA-шина, DevPortal, келишим-тесттер, fallback-багыттоо, webhooks-кол коюу.
Phase 3 (5-6 ай.): гео-rollover менен кластер, SLA Smart-Routing, SLO/Alerts, SDK Autogene, canary.

24) Азык-түлүктүн алдындагы чек-тизме

Registry келишимдер, шайкештик тесттер өттү.
Таймауттардын/ретрайлардын/брейкерлердин полиси белгиленген жана e2e-тесттер менен капталган.
IdempotencyKey критикалык POST/PUT киргизилген.
Кол webhooks текшерилген, кайталоо конфигурацияланган, DLQ мониторинг.
p95/p99 жана error-rate өлчөмдөрү SLO менен дал келет, алерталар туташтырылган.
KMS сырлары, айлануу текшерилген; IP-allowlist/WAF активдүү.
Runbooks/playbook окуялар жарыяланган, on-call белгиленген.
DevPortal жана кумдук өнөктөштөр үчүн жеткиликтүү, нускалары документтештирилген.

Кыскача корутунду

Интеграциялык HUB - бул сиздин өзөгүңүз менен тышкы кызматтардын дүйнөсүнүн ортосундагы өнөр жайлык "калкан жана котормочу". Анын күчү - катуу келишимдер, идемпотенттүүлүк, окуя шиналар, башкарылуучу чыгаруу жана байкоо. Мындай архитектура провайдерлердин онбордингин тездетет, тобокелдиктерди азайтат, болжолдонгон SLOларды берет жана трафиктин туу чокусуна чейин масштабдоону жана жаңы рынокторго чыгууну жеңилдетет.