Комплаенс жана отчеттуулук 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 Frontes/Backends, PSP/aquiring, KYC-провайдерлер, antifrod, CRM, туунду тармактары.

4) Архитектуралык шилтеме

1. Edge/API-шлюз (mTLS, OAuth2/OIDC, rate-limit, WAF).
2. Комплаенс кызматы (бизнес эрежелери, провайдерлерди оркестрлөө, нормалдаштыруу).
3. Shine Events (Kafka/Redpanda) - SIEM/DWH/Archive бир күйөрман.

• Ыкчам (PostgreSQL/ClickHouse) тез суроо-талап/топтоо үчүн.
• Archive (Object Storage + WORM) өзгөрүлбөгөн экспонаттар жана отчеттор үчүн.
• 5. Аудит жана байкоо: OpenTelemetry (trace_id), индекстөө, дашборддор.
• 6. Провайдерлердин коннекторлору: KYC, санкциялар, RG модулдары, электрондук кол тамга менен мамлекеттик порталдар.

5) Негизги эндпоинттер (v1)

5. 1 KYC/KYB жана чаралар

'POST/v1/kyc/check' - KYC текшерүү өтүнүчү (idempotent).
'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 жана Retenshn: WORM-сактоо үчүн отчеттор жана STR; сактоо саясаты 5-7 жыл (рыноктордо).

8) Версия жана шайкештиги

URI версиясы: '/v1 ', '/v2'; майда өзгөрүүлөр - кеңейтилген талаалар аркылуу.
Deprecation-policy: ≥ 6-12 ай колдоо; "Sunset", "Deprecation" аталыштары.
Схемалар: JSON Schema + OpenAPI; контракттар CI менен тастыкталат.
Миграциялар: адаптерлер/feature-желектер, өтүү мезгилине эки тараптуу шайкештик.

9) Ишенимдүүлүк: демпотенттик жана "так бир жолу"

Idempotency-Key in 'POST' (24-72 саат ≥ ачкычтарды сактоо).
At-least-once шиналар аркылуу жеткирүү + кабыл алуу боюнча deduplication (event id/hash).
Outbox/Inbox-үлгү интеграциялоо үчүн, экспоненциалдык тыныгуу жана jitter менен ретрациялоо.
Тартиби: 'user _ id '/' account _ id' партиялаштыруу ачкычтары детерминизм үчүн.

10) Пагинация, чыпкалар, издөө

Pagination: cursor-based ('page _ token', 'limit <= 1000').
Чыпкалар: юрисдикция, мезгил, статус, провайдер, тобокелдик-баалоо боюнча.
Толук текст издөө: аудит/реестрлер үчүн (талаалардын чектелген түрчөсү).
Экспорт: асинхрондук, өлчөм чеги, hash-кол менен архивди даярдоо.

11) Чектөөлөр жана квоталар

Rate-limits per client/route (мисалы, 100 rps бурст, 1000 rpm sustained).
Budget-limits оор отчеттор (кредиттер/күн).
N + 1 коргоо: батч жана бириктирилген EndPoint.
Тарыхый тандоолордун тереңдигин чектөө (мисалы, ≤ 24 ай онлайн, андан ары архив).

12) Dashbord жана SLO

Ingest lag p95 <30 сек; KYC ийгилиги> 99%; STR-SLA - жөнөтүү ≤ 24 саат

API жеткиликтүүлүгү ≥ 99. 9%; Latency p95 <300 ms окуу үчүн; <800 ms жазуу үчүн.
Cost/GB отчетторду сактоо; Ack-rate жөнгө салуучу билдирүүлөр.
Widget: жылуулук карта alert AML, кузов KYC, өлкө боюнча отчетторду чыгаруу, кезек STR.

13) Юрисдикциялар: mapping жана шаблондор

Рыноктор боюнча отчеттордун үлгүлөрү (талаалар, форматтар, жыштык): 'EE', 'LT', 'LV', 'RO', 'MT', 'UK' ж.б.
Mapping терминдер (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 → тесттик кардарлардын генерациясы).
Юрисдикциялар боюнча фикстура топтомдору, отчеттор үчүн алтын 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) Камтылган аудит жана өзгөрбөстүк

Autologisation: 'request _ id', 'trace _ id', чакыруучу кардар, scope.
Отчет топтомдорунун кол тамгасы (SHA-256) + хэш реестри; мезгилдүү анкеринг.
WORM архиви жөнгө салуу жана STR үчүн.
Эрежелердин жана шаблондордун конфигурацияларынын тарыхы (өзгөртүү саясаты журналы).

18) Процесстер жана RACI (кыскача)

R: Compliance Platform командасы (иштеп чыгуу/иш).
A: Compliance/CISO башчысы (саясатчылар, бюджеттер, артыкчылыктар).
C: Юридикалык/DPO, Каржы, Архитектура, маалыматтар.
I: Продукт, колдоо, өнөктөштөр (PSP/KYC).

19) Ишке ашыруунун жол картасы

1. '/v1/kyc/check ', '/v1/aml/transaction', '/v1/reports/generate '(2-3 негизги шаблон).

2. OAuth2 + rate-limit + негизги боштук.

3. Object Storage 'деги отчеттордун архиви.

4. Dashboard SLO жана милдеттерди кезек.

• юрисдикциялык шаблондор (5-8 базарлар), STR/SAR, RG-end-points, DSAR.
• Провайдер-агрегация (KUS/санкциялар), ретраи, dedupe.
• Legal Hold, WORM, Advanced ролдору.

• Rule-as-Code отчеттор/AML-эрежелери үчүн, өзгөртүү симулятору.
• Көп тенанттуулук (B2B2C, бренддер/терилер), квоталар жана биллинг.
• тышкы интеграторлор үчүн Sandbox жана күбөлүк.

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) алдын ала айтууну, текшерүүдөн тез өтүүнү жана негизги рыноктордо тобокелдиктерди азайтууну камсыз кылат.