Интеграциялық HUB және API-байланыс

1) HUB жауапкершілігінің рөлі мен аймағы

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

2) Дизайн қағидаттары

Консистенттік келісімшарттар: бірыңғай DTO/оқиғалар, қатаң схема және нұсқа.
Теңсіздік: сұрау кілттері, дедупликация, қауіпсіз қайталаулар.
Әдепкі Fail-safe: таймаут өрістері, backoff, circuit breaker.
Обсервабилити функция ретінде: бәрі өлшенетін және трассаланатын.
Интеграцияның доменнен бөлінуі: адаптерлер өзектің бизнес-логикасын «білмейді».
Оқиғалар: асинхрондық процестер үшін publish/subscribe.
Нұсқалау: SemVer келісімшарттары және басқарылатын деприкация.

3) Жоғары деңгейлі сәулет

API Gateway: аутентификация, rate limits, канареялық релиздер, WAF.
Оркестратор/Router: провайдерлер бойынша маршруттау, басымдықтар, failover, smart-routing.
Провайдерлер адаптері: REST/gRPC/GraphQL/WebSocket, өріс маппингі, жергілікті кэштер.
EDA-шина (Kafka/RabbitMQ/NATS): «төлем жасалды», «KYC өтті», «ойын сессиясы басталды» оқиғалары.
Келісімшарттар/схемалар сервисі: JSON/Euro/Protobuf үшін Schema Registry.
Интеграцияның жай-күйін сақтау қоймасы: идемпотенттілік, корелляция, мәртебе кілттері.
Байқалуы: Prometheus/OTel + дашбордтар мен алерталар.
DevPortal: интеграция каталогтары, OpenAPI/Protobuf, мысалдар, құмсалғыштар.

4) Деректер келісімшарттары мен схемалары

Қатаң схемалар (JSON Schema/Avro/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, анти-бот сүзгілері.
Құпия-менеджмент (KMS/HSM), кілттерді ротациялау, split-knowledge.
GDPR/PCI DSS: жеке және карточкалық деректерді барынша азайту, токенизация.

7) Маршруттау және оркестрлеу

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

8) Теңсіздік және 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 провайдерлер бойынша, оқиғаларды растау уақыты, «Time-to-Wallet».
Трейсинг (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/мессенджерлер.
Талдау/BI: оқиғалар стримингі және агрегаттар.
Фрод/Чарджбеки: диспут-орталықтар, хабарландыру.

14) Мульти-тенанттық және аймақтық

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

15) Өнімділік және кэштеу

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

16) Жалғаспалы сценарийлер (мысалдар)

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

1. 'POST/payments' (іспеттес) → Оркестратор → 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. 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

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 ішінде: кезектегі лимиттер, ретрайлардың бюджеті, ең көп DLQ-уақыттар.

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

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

22) Қауіпсіздік және комплаенс

Логтардағы PII-редакция, at-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 ай): гео-ролловері бар кластер, SLA бойынша smart-routing, кеңейтілген SLO/алерталар, SDK автогені, canary.

24) Азық-түлік алдындағы чек-парағы

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

Қысқаша қорытынды

Интеграциялық HUB - бұл сіздің өзегіңіз бен сыртқы сервистер әлемі арасындағы өнеркәсіптік «қалқан және аудармашы». Оның күші - қатаң келісімшарттарда, теңсіздікте, оқиғалық шинада, басқарылатын нұсқада және бақылауда. Мұндай сәулет провайдерлердің онбордингін жеделдетеді, тәуекелдерді төмендетеді, болжамды SLO береді және трафикті шыңдау мен жаңа нарықтарға шығуды жеңілдетеді.