API комплаенса и отчетности

1) Назначение

• Сбора и валидации событий (игровые/платежные/аутентификация) для AML/Responsible Gaming (RG).
• Проведения проверок (KYC/KYB, санкции/PEP, источники средств, возраст).
• Формирования регуляторной отчетности (периодической и 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` — санкционный/PEP скрининг.
`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.
• Провайдер-агрегация (KYC/санкции), ретраи, 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) обеспечивает предсказуемость, быстрое прохождение проверок и снижение рисков на ключевых рынках.