API комплаєнсу та звітності

1) Призначення

• Збір та валідація подій (ігрові/платіжні/автентифікація) для AML/Responsible Gaming (RG).
• Проведення перевірок (KYC/KYB, санкції/РЕР, джерела коштів, вік).
• Формування регуляторної звітності (періодичної та ad-hoc) по ринках.
• Ведення аудит-журналів та виконання Legal Hold.
• Обміну даними з провайдерами (PSP, KYC-біржі, санкційні списки) і гос-порталами.

Результат: знижується операційне навантаження, прискорюється підготовка звітів, забезпечується трассируемость і відповідність локальним нормам.

2) Область охоплення (scope)

Ідентифікація та верифікація: KYC/KYB статуси, рівні перевірки, документи.
AML/санкції/PEP: скринінг, моніторинг транзакцій, STR/SAR, алерти.
Відповідальна гра (RG): ліміти, самовиключення, «cool-off», поведінкові шкали ризику.
Платежі та операції: депозити/висновки, chargeback, бонусні механіки.
Звітність: GGR/податки, реєстри гравців/сесій, маркетингові обмеження, інциденти безпеки.
Аудит та зберігання: незмінні логи (WORM), Legal Hold, DSAR/RTBF.

3) Споживачі та виробники даних

Споживачі: регулятори, внутрішній Compliance/Risk, BI/DWH, SecOps, фінанси.
Виробники: фронти/бекенди iGaming, PSP/аквайрінг, KYC-провайдери, антифрод, CRM, афіліат-мережі.

4) Архітектурний референс

1. Edge/API-шлюз (mTLS, OAuth2/OIDC, rate-limit, WAF).
2. Сервіс комплаєнсу (бізнес-правила, оркестрація провайдерів, нормалізація).
3. Шина подій (Kafka/Redpanda) - фан-аут в SIEM/DWH/архів.

• Оперативне (PostgreSQL/ClickHouse) для швидких запитів/агрегацій.
• Архів (Object Storage + WORM) для незмінних артефактів і звітів.
• 5. Аудит і спостережуваність: OpenTelemetry (trace_id), індексація логів, дашборди.
• 6. Конектори провайдерів: KYC, санкції, RG-модулі, держ-портали з e-підписом.

5) Основні ендпоінти (v1)

5. 1 KYC/KYB і санкції

'POST/v1/kyc/check'- запит перевірки KYC (ідемпотентний).
'GET/v1/kyc/{ user _ id }/status'- поточний рівень і термін дії.
'POST/v1/sanctions/screen'- санкційний/РЕР скринінг.
'GET/v1/sanctions/{ user _ id }/hits'- збіги/ескалації.

5. 2 AML і моніторинг транзакцій

'POST/v1/aml/transaction'- відправлення події (deposit/withdraw/bet/payout).
`GET /v1/aml/alerts? state = open'- відкриті алерти/кейси.
'POST/v1/aml/str'- формування і подача STR/SAR (по ринку).

5. 3 Responsible Gaming (RG)

'POST/v1/rg/self-exclusion'- установка/зняття самовиключення.
'GET/v1/rg/limits/{ user _ id}'- ліміти (депозит/ставка/час).
'POST/v1/rg/assess'- оцінка ризику поведінки.

5. 4 Звітність та реєстри

'POST/v1/reports/generate'- генерація звіту (тип, період, юрисдикція).
'GET/v1/reports/{ report _ id}'- статус, завантаження артефакту (PDF/CSV/JSON), hash.
'GET/v1/registries/{ type}'- реєстри (гравці, сесії, бонуси, GGR) з пагінацією.

5. 5 Аудит і правові операції

'GET/v1/audit/events'- вибірка подій (фільтр по полях ECS/OCSF).
'POST/v1/legal/hold'- установка/зняття Legal Hold по об'єкту/папці.
'POST/v1/privacy/dsar'- запуск DSAR, статуси, експорт пакетів.

6) Моделі даних (скорочено)

6. 1 Подія транзакції (JSON)

json
{
"idempotency_key": "trx-8b1a9953",
"timestamp": "2025-11-01T16:02:11Z",
"user": {"id":"U-12345","dob":"1999-04-21","country":"EE"},
"transaction": {
"id": "T-778899",
"type": "deposit",
"amount": {"value": 200. 00, "currency": "EUR"},
"method": "card",
"psp_ref": "PSP-222-ABC"
},
"context": {
"ip": "198. 51. 100. 10",
"device_id": "d-9af0",
"session_id": "s-2233",
"trace_id": "f4c2..."
},
"labels": {"market": "EE", "affiliate": "A-77"}
}

6. 2 Результат KYC

json
{
"user_id": "U-12345",
"level": "L2",
"status": "verified",
"expires_at": "2026-04-21",
"checks": [
{"type":"document","result":"pass"},
{"type":"liveness","result":"pass"},
{"type":"pep_sanctions","result":"no_hit"}
],
"provider": {"name":"KYCX","reference":"KYCX-4455"}
}

6. 3 Опис звіту

json
{
"report_id": "RPT-EE-GGR-2025Q3",
"type": "ggr_quarterly",
"jurisdiction": "EE",
"period": {"from":"2025-07-01","to":"2025-09-30"},
"status": "ready",
"artifact": {
"format": "CSV",
"size_bytes": 183442,
"sha256": "c9b1f...e21",
"download_url": "urn:reports:RPT-EE-GGR-2025Q3"
},
"notes": "Rounded to cents; FX=ECB daily"
}

7) Безпека та доступ

Автентифікація: OAuth2/OIDC (client credentials, JWT), опціонально mTLS.
Авторизація: RBAC/ABAC; окремі scopes по доменах ('aml:write`, `kyc:read`, `reports:generate`).
Шифрування: TLS 1. 2+ in-transit; at-rest через KMS/CMK; JWE для чутливих полів.
PII-мінімізація: зберігати мінімум; маскувати PAN/IBAN; псевдонімізація'user. pseudo_id`.
Журнал доступу: аудит всіх читань «чутливих» ендпоінтів, алерти на масові вивантаження.
Legal Hold і ретеншн: WORM-сховище для звітів і STR; політики зберігання 5-7 років (по ринках).

8) Версіонування та сумісність

URI-версіонування: `/v1`, `/v2`; мінорні зміни - через розширювані поля.
Deprecation-policy: ≥ 6-12 місяців підтримки; заголовки «Sunset», «Deprecation».
Схеми: JSON Schema + OpenAPI; контракти валідуються в CI.
Міграції: адаптери/feature-прапори, двостороння сумісність на період переходу.

9) Надійність: ідемпотентність і «рівно-одного разу»

Idempotency-Key в'POST'( зберігати ключі ≥ 24-72 год).
At-least-once доставка через шину + дедуплікація на прийомі (event id/hash).
Outbox/Inbox-pattern для інтеграцій, ретраї з експоненціальною паузою і jitter.
Порядок: ключі партіонування'user _ id '/' account _ id'для детермінізму.

10) Пагінація, фільтри, пошук

Пагінація: cursor-based (`page_token`, `limit <= 1000`).
Фільтри: по юрисдикції, періоду, статусу, провайдеру, ризик-оцінці.
Повнотекстовий пошук: для аудиту/реєстрів (обмежена підмножина полів).
Експорт: асинхронно, ліміт розміру, підготовка архіву з hash-підписом.

11) Обмеження та квоти

Rate-limits per client/route (наприклад, 100 rps burst, 1000 rpm sustained).
Budget-limits на важкі звіти (кредити/добу).
Захист від N + 1: батчі та агреговані ендпоінти.
Обмеження глибини історичних вибірок (наприклад, ≤ 24 міс онлайн, далі архів).

12) Дашборди і SLO

Ingest lag p95 <30 сек; Успіх KYC> 99%; STR-SLA - відправка ≤ 24 год.
Доступність API ≥ 99. 9%; Latency p95 <300 мс для читання; <800 мс для запису.
Cost/GB зберігання звітів; Ack-rate повідомлень регуляторам.
Віджети: тепло-карта алертів AML, воронка KYC, випуск звітів по країнах, черга STR.

13) Юрисдикції: мапінг і шаблони

Шаблони звітів по ринках (поля, формати, частота): `EE`, `LT`, `LV`, `RO`, `MT`, `UK`, и т.д.
Маппінг термінів (GGR/NGR, бонуси, ліміти депозитів, віковий контроль).
Локалізація таймзон/календарів; фіксація джерела FX; мітка DST впливу.
Каталог схем: `reports/{jurisdiction}/{type}/{version}.schema. json`.

14) Обробка помилок (єдиний формат)

json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"request_id": "req-7f91",
"hint": "Reduce RPS or request higher quota",
"retry_after": 30
}
}

Часті коди: `INVALID_SCHEMA`, `NOT_AUTHORIZED`, `LEGAL_HOLD_ACTIVE`, `PROVIDER_TIMEOUT`, `REPORT_NOT_READY`.

15) Тестування та сертифікація

Контрактні тести (OpenAPI → генерація тест-клієнтів).
Набори фікстур по юрисдикціях, golden-files для звітів.
«Чорні списки» PII-полів в логах; статичний аналіз витоків секретів.
Регулярні DR-навчання з відновлення архівів звітів.

16) Приклади

16. 1 Генерація звіту

Запит

http
POST /v1/reports/generate
Content-Type: application/json
Authorization: Bearer <token>

json
{
"type": "ggr_monthly",
"jurisdiction": "EE",
"period": {"from":"2025-10-01","to":"2025-10-31"},
"format": "CSV",
"notify": ["compliance@company"],
"parameters": {"include_bonus_breakdown": true}
}

Відповідь

json
{"report_id":"RPT-EE-GGR-2025-10","status":"processing","eta_seconds":120}

16. 2 STR/SAR відправка

json
{
"case_id": "AML-2025-0091",
"user_id": "U-12345",
"reason": "Structuring deposits under threshold",
"evidence": ["txn:T-778899","txn:T-778900"],
"attachments": ["urn:doc:kyc:U-12345:v3"],
"jurisdiction": "EE"
}

16. 3 Самовиключення

json
{
"user_id":"U-12345",
"type":"national_register",
"action":"enable",
"effective_from":"2025-11-01",
"effective_to":"2026-11-01"
}

17) Вбудований аудит і незмінюваність

Автологування: 'request _ id','trace _ id', викликає клієнт, scope.
Підпис пакетів звітів (SHA-256) + реєстр хешів; Періодичний анкеринг.
WORM-архів для регуляторних вивантажень і STR.
Історія конфігурацій правил і шаблонів (журнал змін політик ↔ лінк).

18) Процеси і RACI (коротко)

R: Команда Compliance Platform (розробка/операції).
A: Head of Compliance/CISO (політики, бюджети, пріоритети).
C: Legal/DPO, Фінанси, Архітектура, Data.
I: Продукт, Підтримка, Партнери (PSP/KYC).

19) Дорожня карта впровадження

1. '/v1/kyc/check', '/v1/aml/transaction', '/v1/reports/generate'( 2-3 ключових шаблони).

2. OAuth2 + rate-limit + базова ідемпотентність.

3. Архів звітів в Object Storage з hash-підписом.

4. Дашборд SLO і черги завдань.

• Юрисдикційні шаблони (5-8 ринків), STR/SAR, RG-ендпоінти, DSAR.
• Провайдер-агрегація (КУС/санкції), ретраї, dedupe.
• Політики Legal Hold, WORM, розширені ролі.

• Rule-as-Code для звітів/AML-правил, симулятор змін.
• Мульти-тенантність (B2B2C, бренди/скіни), квоти і білінг.
• Пісочниця та сертифікація для зовнішніх інтеграторів.

20) Типові помилки і як їх уникнути

Різнобій схем по ринках: централізований каталог, auto-lint схем.
Немає ідемпотентності: вводите'idempotency _ key'і вікно дедуплікації.
Секрети в логах: фільтри на ingest, статичний аналіз.
Довгі звіти online: робіть асинхронно з статус-пулінгом і повідомленнями.
Слабкий RBAC: рознесіть'read _ reports','generate _ reports','admin'.
Валюта/таймзона: фіксуйте'fx _ source','timezone', зберігайте UTC.

21) Глосарій (коротко)

KYC/KYB - ідентифікація фіз./юр. осіб.
AML/STR/SAR - протидія відмиванню/підозріла активність/повідомлення.
RG - відповідальна гра.
GGR/NGR - валова/чиста виручка від ігор.
WORM - незмінне зберігання (write-once).
Rule-as-Code - правила як код з тестами/версіонуванням.

22) Підсумок

API комплаєнсу і звітності - це стійкий, безпечний і стандартизований шар між операціями iGaming і вимогами регуляторів. Дотримання принципів з цієї статті (суворі схеми, безпечна інтеграція, ідемпотентність, незмінний аудит, юрисдикційні шаблони і SLO) забезпечує передбачуваність, швидке проходження перевірок і зниження ризиків на ключових ринках.