Загальні протоколи взаємодії

1) Навіщо екосистемі єдині протоколи

Екосистема складається з операторів, студій/RGS, агрегаторів, PSP/APM, KYC/AML-провайдерів, афіліатів та аналітичних сервісів. Загальні протоколи взаємодії виключають «зоопарк» інтеграцій, прискорюють онбординг, знижують вартість підтримки і ризики інцидентів, а ще - забезпечують сумісність при масштабуванні (горизонтальному, вертикальному і діагональному).

Цілі: сумісність «з коробки», передбачувані SLO, безпека даних, відтворювані міграції.

2) Шар транспорту і формати

HTTP/2/3, gRPC - для синхронних API з низькою латентністю; WebSocket - для потокових подій/лідербордів; WebRTC (SRTP/QUIC) - для аудіо/відео лайв-контенту.

• JSON - зовнішні B2B API і вебхуки (читаність).
• Protobuf/Avro - внутрішня шина/глибокі інтеграції (стиснення/еволюція схем).
• Стиснення/біндинг: gzip/br для JSON; zstd для Protobuf/Avro.
• Локаль/час: ISO-8601 в UTC, суми - в мінімальних грошових одиницях (integer).

3) Автентифікація, авторизація, довіра

OAuth2/OIDC для клієнтських/партнерських додатків (short-lived токени, PKCE, scopes).
mTLS для S2S між довіреними зонами; JWS/HMAC - підпис запитів і вебхуків.
RBAC/ABAC: ролі та атрибути (юрисдикція, тенант, ризик-рівень).
Ключі та ротація: KMS/Vault, короткий термін життя, автоматична ротація (в т.ч. JWKS).
Egress-контроль, allow-list доменів і ASN, DNSSEC/DoT/DoH в чутливих зонах.
Tenant isolation: per-tenant ключі, квоти, ліміти, namespace-и в шині.

4) Контракти API (REST/gRPC) - каноніка

Версіонування: '/v {n}'в URI для REST;'package. vN'для gRPC. Minor-еволюція - безломна; breaking-зміни - через нову major. Депрекація з політики (див. § 12).
Ідемпотентність: 'Idempotency-Key'на POST/PUT/PATCH грошових/критичних операцій; збереження на N годин.
Пагінація: курсори ('nextPageToken'), не'offset/limit'; консистентні сортування.
Ліміти: '429 Too Many Requests'+ заголовки квот ('X-RateLimit-'), джиттер в ретраях.
Помилки: машиночитні коди/підкоди,'correlationId', карта полів валідації.
Таймаути і ретраї: експоненціальна затримка + джиттер; не ретраїти небезпечні помилки.
Політика сумісності: незмінність сенсу полів; нові поля - опціональні.

5) Подієва модель і шина (EDA)

Реєстратор схем (Schema Registry): контракт на кожну подію, еволюція з backward-сумісністю.

• `click`, `session`, `bet`/`spin`, `round_start`/`round_result`,
• `deposit`/`withdrawal`, `psp_auth`, `kyc_status`, `fraud_signal`,
• `reward_granted`, `leaderboard_update`, `feature_toggle`.
• Ключі партій: 'playerId','campaignId','tableId','operatorId'( вибір по домену).
• Доставка: at-least-once c бізнес-ідемпотентністю; для грошових підсумків - сага/txn-outbox.
• Порядок: «гарантований порядок всередині ключа», крос-ключі - через оркестрацію.
• Семантика часу: `eventTime` + `ingestTime`; дедуп по'( eventId'idempotencyKey)'.

6) Вебхукі та гарантії доставки

Підпис: JWS/HMAC з't'( timestamp) і'kid', перевірка вікна ± 5 хвилин, відтворюваність заборонена.
Ретраї: backoff з джитером до T хвилин, фіксація спроб, перевідправлення тільки при 5xx/timeout.
Ідемпотентність: 'eventId'+ підпис тіла; обробка «принаймні один раз».
Реєстр подій вебхуків: повторна вибірка історії при розсинхронізації.
Безпека: mTLS по мірі можливості, allow-list IP/ASN, CSRF не застосовується до серверних колбеків.

7) Дані та приватність (Privacy-by-Design)

PII-мінімізація: токенізація ідентифікаторів ('playerId'псевдонімізується), розділення доменів даних.
Контракти даних: DPA/DPIA, цілі, терміни зберігання, транскордонні потоки (Whitelist країн).
Політики аудиту/лінійджа: хто/коли/навіщо; незмінні логи (WORM).
Правила RG/етики: заборона агресивних офферів для вразливих сегментів; чітка правова база.

8) Узгодженість і транзакції

Сильна консистентність - гаманець/баланси/виплати.
Eventual - вітрини, лідерборди, телеметрія.
Саги для розподілених бізнес-транзакцій; компенсації для відмін.
Exactly-once за бізнес-змістом: ідемпотентні ключі та детерміновані обробники.

9) Спостережуваність і SLO

Трейсинг: наскрізний'traceId'від кліка/вебхука до виплати/нагороди; propagation (`W3C traceparent`).
Метрики: p50/p95/p99 API, лаг брокера, CR платежів/КУС, лідерборди E2E.
Логи: структуровані, без ПДн; маскування токенів/ключів.
SLO-листи: логін p95 ≤ 300-500 мс; депозит p95 ≤ 1. 5–2. 0 с; ставка/спін p95 ≤ 150-250 мс; доставка подій ≥ 99. 9%.

10) Продуктивність, квоти, захист від шторму

Rate limiting (token/leaky bucket) на L7 і в меш-політиках.
Backpressure: черги перед крихкими апстрімами (PSP/KYC).
Outlier-ejection: автоматичне «охолодження» нестабільних бекендів.
Circuit-breaker: закриття потоку при перевищенні порогів помилок/латентності.
Fair-share: квоти по тенанту/каналу/регіону; пріоритет критичних доменів.

11) Сумісність SDK і тест-критерії

Набір SDK: HTTP/gRPC клієнти, підпис запитів, ретраї з джиттером, ідемпотентність, курсори.
Контрактні тести: Postman/Newman/gRPC-conformance, симулятори PSP/KYC/студій.
Матриця сумісності: версії API/SDK, підтримувані схеми, політики депрекації.
Синтетика: генератори подій і транзакцій, «чорні скриньки» 24/7 для моніторингу.

12) Версіонування та депрекації (Change Management)

Major-релізи раз на N місяців, з паралельним вікном ≥ 6-12 міс.
Minor-зміни - додавання опціональних полів/методів безломно.
Депрекація: анонс → попередження в заголовках/відповідях → прапор в метриках → вимкнення за планом.
Міграції схем подій: стратегія «розширення» (add-only) + проксі-адаптери на кордонах.

13) Безпека протоколів

Zero Trust: mTLS скрізь, короткоживучі креди, принципи найменших привілеїв.
Секрет-скоупи: розділення ключів читання/запису/адміністрування.
Захист від повторів: nonce/тимчасове вікно в підписах; заборона перевикористання.
WAF/бот-фільтри: захист від скрейпінгу/клік-фроду; низький false positive.
Вендор-зони: мікросегментація, окремі VPC/namespace-и, egress-allow-list.

14) Інциденти і DR

War-room-процедури: стоп-кнопка для доменів (контент/PSP/KYC), RACI, SLA на трейс-пакет.
DR-сценарії: актив-актив вхідні точки (Anycast/GSLB), cut-over ≤ 60-90 с, щоквартальні навчання.
RCA: шаблони без пошуку винних, зв'язок L3↔L7, апдейти в протокол/SDK/Runbook.

15) Метрики успіху протоколів

Сумісність: частка партнерів, які пройшли conformance-тести; час онбордингу (TTO).
Надійність: uptime інтеграцій, p95 API/шини, частка успішних вебхуків.
Безпека: інциденти ПДн = 0, час ротації ключів, частка mTLS-трафіку.
Економіка: cost per rps/txn/event, зниження Cost-to-Serve, час міграцій.
Продукт: FTD/ARPU/LTV uplift від стандартизації (менше протікань КУС/платежів).

16) Анти-патерни

«Вільна форма» подій: відсутність схем і версій → роз'їзд вітрин і аналітики.
Єдиний L7-шлюз без N + 1: SPOF і вузьке горло для вебхуків/PSP.
Ретраї без лімітів/джиттера: трафік-шторм, дубль транзакцій.
Сирі ПДн в обміні: без токенізації/DPIA → регуляторні ризики.
Offset-пагінація: пропуски/дублікати під навантаженням.
Секрети «назавжди» і статичні IP без egress-контролю.
Breaking-зміни без паралельного вікна і адаптерів.

17) Чек-лист впровадження

1. Прийняти каноніку API (версіонування, ідемпотентність, пагінація, помилки).
2. Ввести Schema Registry і доменну карту топіків/ключів партій.
3. Зобов'язати mTLS + JWS/HMAC для S2S і вебхуків; автоматизувати ротацію ключів/JWKS.
4. Налаштувати ліміти/ретраї/CB/outlier-ejection і квоти per-tenant.
5. Розгорнути трейсинг/метрики/логи з єдиним'traceId'; затвердити SLO-листи.
6. Підписати DPA/DPIA, включити токенізацію і політики зберігання/видалення.
7. Створити SDK і conformance-набір; зафіксувати політику депрекації.
8. Провести DR/chaos-навчання і war-room-ритуали; «чорний старт» на мінімальному наборі.
9. Впровадити каталог протоколів (портал партнера): спек, приклади, симулятори, пісочниця.

18) Дорожня карта еволюції

v1 (Foundation): каноніка REST/gRPC, базові схеми подій, підписи вебхуків, mTLS.
v2 (Integration): конвеєр міграцій, conformance-тести, SDK, rule-engine для квот/ретраїв.
v3 (Automation): автодозування по SLI, self-service пісочниці/симулятори, адаптери між версіями.
v4 (Networked Governance): міжпартнерський комітет протоколів, загальні SLO/кредити/пенальті, спільні PoP/edge-політики.

Коротке резюме

Загальні протоколи взаємодії - це «мова» екосистеми: єдині контракти API і подій, сувора безпека (mTLS/JWS), ідемпотентність і гарантії доставки, спостережуваність і SLO, керовані міграції і DR. слідуючи каноніці, учасники швидше онбордяться, рідше падають, простіше масштабуються і передбачувано зростають - при дотриманні приватності і вимог юрисдикцій.