Комплаенс және есептілік 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; KMS/CMK арқылы at-rest; Сезімтал өрістер үшін 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. hash-қолтаңбасы бар Object Storage есептер мұрағаты.

4. SLO дашборды және тапсырмалар кезегі.

• Юрисдикциялық үлгілер (5-8 базар), STR/SAR, RG-эндпоинттер, DSAR.
• Провайдер-агрегация (АЕК/санкциялар), ретра, dedupe.
• Legal Hold, WORM саясаты, кеңейтілген рөлдер.

• Есеп/AML ережелері үшін Rule-as-Code, өзгерістер симуляторы.
• Көп теңгелілік (B2B2C, брендтер/терілер), квоталар және биллинг.
• Сыртқы интеграторларға арналған құмсалғыш және сертификаттау.

20) Типтік қателер және оларды болдырмау

Нарықтар бойынша әртүрлі схемалар: орталықтандырылған каталог, auto-lint схемалар.
Сәйкестік жоқ: 'idempotency _ key' және дедупликация терезесін енгізіңіз.
Логтардағы құпиялар: ingest сүзгілері, статикалық талдау.
Ұзақ онлайн есептерді: статус-пуллингпен және хабарламалармен асинхронды жасаңыз.
Әлсіз 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) болжамдылықты, тексерулерден жылдам өтуді және негізгі нарықтардағы тәуекелдерді төмендетуді қамтамасыз етеді.