Zgodność i sprawozdawczość API

1) Cel

• Zbieranie i zatwierdzanie zdarzeń (gry/płatności/uwierzytelniania) dla AML/Responsible Gaming (RG).
• Inspekcje (KYC/KYB, sankcje/PEP, źródła funduszy, wiek).
• Sprawozdawczość regulacyjna (okresowa i doraźna) według rynku.
• Prowadzenie dzienników audytu i wykonywanie blokady prawnej.
• Wymiana danych z dostawcami (PSP, wymiana KYC, listy sankcji) i portale państwowe.

Wynik: zmniejszenie kosztów operacyjnych, szybsze raportowanie, identyfikowalność i lokalna zgodność.

2) Zakres stosowania

Identyfikacja i weryfikacja: statusy KYC/KYB, poziomy weryfikacji, dokumenty.
AML/sankcje/PEP: kontrola bezpieczeństwa, monitorowanie transakcji, STR/SAR, wpisy.
Odpowiedzialna gra (RG): ograniczenia, samodzielne wykluczenie, „cool-off”, skala ryzyka behawioralnego.
Płatności i transakcje: wpłaty/wypłaty, obciążenie zwrotne, mechanika bonusowa.
Raportowanie: GGR/podatki, rejestry graczy/sesji, ograniczenia marketingowe, incydenty bezpieczeństwa.
Audyt i przechowywanie: immutable logs (WORM), Legal Hold, DSAR/RTBF.

3) Konsumenci i producenci danych

Konsumenci: Regulatorzy, Wewnętrzna Zgodność/Ryzyko, BI/DWH, SecOps, Finanse.
Producenci: fronty/backendy iGaming, PSP/aquiting, dostawcy KYC, przeciwdziałanie oszustwom, CRM, sieci partnerskie.

4) Odniesienie architektoniczne

1. Krawędź/API-млиz (mTLS, OAuth2/OIDC, tempo-limit, WAF).
2. Usługa zgodności (zasady biznesowe, orkiestra dostawcy, normalizacja).
3. Autobus imprezowy (Kafka/Redpanda) - wentylator w SIEM/DWH/archiwum.

• Online (PostgreSQL/ClickHouse) dla szybkich zapytań/agregacji.
• Archiwum (Storage Object + WORM) dla niezmiennych artefaktów i raportów.
• 5. Audyt i obserwowalność: OpenTelemetry (trace_id), dzienniki indeksowania, deski rozdzielcze.
• 6. Złącza dostawcy: KYC, sankcje, moduły RG, portale państwowe z e-podpisem.

5) Główne punkty końcowe (v1)

5. 1 KYC/KYB i sankcje

„POST/v1/kyc/check” - żądanie sprawdzenia KYC (idempotent).
„GET/v1/kyc/{ user _ id }/status” - bieżący poziom i data ważności.
„POST/v1/sankcje/ekran” - kontrola sankcji/PEP.
„GET/v1/sanctions/{ user _ id }/hits” - matches/escalations.

5. 2 AML i monitorowanie transakcji

„POST/v1/aml/transaction” - wysyłanie zdarzenia (depozyt/within/bet/payout).
"GET/v1/aml/alerts? state = open '- otwarte wpisy/przypadki.
„POST/v1/aml/str” - tworzenie i składanie STR/SAR (według rynku).

5. 3 Odpowiedzialne gry (RG)

„POST/v1/rg/self-exclusion” - set/remove self-exclusion.
„GET/v1/rg/limits/{ user _ id}” - limity (deposit/rate/time).
„POST/v1/rg/assessment” - ocena ryzyka zachowań.

5. 4 Sprawozdawczość i rejestry

„POST/v1/reports/generate” - generowanie raportów (rodzaj, okres, jurysdykcja).
„GET/v1/reports/{ report _ id}” - status, artefakt download (PDF/CSV/JSON), hash.
'GET/v1/registers/{ type}' - rejestry (gracze, sesje, bonusy, GGR) z paginacją.

5. 5 Audyt i transakcje prawne

„GET/v1/audit/events” - wybór zdarzeń (filtr według pól ECS/OCSF).
'POST/v1/legal/hold' - set/remove Legal Hold on the object/folder.
„POST/v1/privacy/dsar” - start DSAR, statusy, pakiety eksportowe.

6) Modele danych (skrócone)

6. 1 Zdarzenie transakcyjne (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. Wynik 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 Opis sprawozdania

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) Bezpieczeństwo i dostęp

Uwierzytelnianie: OAuth2/OIDC (poświadczenia klienta, JWT), opcjonalny mTLS.
Autoryzacja: RBAC/ABAC; oddzielne zakresy według domeny ('aml: write', 'kyc: read', 'reports: generate').
Szyfrowanie: TLS 1. 2 + w tranzycie; odpoczynku przez KMS/CMK; JWE dla wrażliwych pól.
Minimalizacja PII: minimum przechowywania; Maska PAN/IBAN aliasing 'user. pseudo_id'.
Dziennik dostępu: audyt wszystkich odczytów „wrażliwych” punktów końcowych, wpisy dotyczące przesyłania zbiorczego.
Prawne trzymanie i zatrzymywanie: magazynowanie WORM do raportów i STR; 5-7-letnia polityka zatrzymywania (według rynku).

8) Wersioning i kompatybilność

Weryfikacja URI: '/v1 ', '/v2'; drobne zmiany - poprzez pola rozszerzalne.
Polityka deprecjacji: ≥ 6-12 miesięcy wsparcia; nagłówki „Zachód słońca”, „Deprecacja”.
Schematy: JSON Schema + OpenAPI; umowy są zatwierdzane w CI.
Migracje: adaptery/flagi funkcji, kompatybilność dwukierunkowa dla okresu przejściowego.

9) Niezawodność: idempotencja i „dokładnie raz”

Idempotency-Key in 'POST' (klawisze przechowywania ≥ 24-72 godziny).
Co najmniej raz dostawa za pośrednictwem autobusu + odbierać deduplication (event id/hash).
Skrzynka odbiorcza/skrzynka odbiorcza-wzór dla integracji, retrai z wykładniczą przerwą i jitter.
Zamówienie: user _ id/account _ id partyturing keys for determinism.

10) Paginacja, filtry, wyszukiwanie

Paginacja: na podstawie kursora ('page _ token', 'limit <= 1000').
Filtry: według jurysdykcji, okresu, statusu, dostawcy, oceny ryzyka.
Pełny tekst wyszukiwania audytu/rejestrów (ograniczony podzbiór pól).
Eksport: asynchroniczny, limit wielkości, przygotowanie archiwum z podpisem hash.

11) Ograniczenia i kwoty

Limity stawek na klienta/trasę (np. 100 rps pęknięcie, 1000 obr/min podtrzymane).
Limity budżetowe na ciężkie sprawozdania (kredyty/dzień).
Ochrona N + 1: partie i zagregowane punkty końcowe.
Ograniczenie głębokości próbek historycznych (na przykład ≤ 24 miesiące online, zwane dalej archiwum).

12) Deski rozdzielcze i układy SLO

Ingest lag p95 <30 sek; Sukces KYC> 99%; STR-SLA - wysyłka ≤ 24 godziny.
API ≥ 99 dostępność. 9%; Latency p95 <300 ms do odczytu; <800 ms do nagrywania.
Koszt/GB przechowywania raportów; Powiadomienia regulatorów o stopie akcyzy.
Widżety: mapa ciepła alarmowa AML, lejek KYC, wydanie raportów krajowych, kolejka STR.

13) Jurysdykcje: Mapowanie i wzorce

szablony raportów rynkowych (pola, formaty, częstotliwość): „EE”, „LT”, „LV”, „RO”, „MT”, „UK” itp.
Mapowanie terminów (GGR/NGR, premie, limity depozytów, kontrola wieku).
Lokalizacja kamieni czasowych/kalendarzy; Napraw etykietę FX source Impact DST.
Katalog schematów: 'reports/{ jurisdiction }/{ type }/{ version} .schema. json '.

14) Obsługa błędów (jednolity format)

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) Testowanie i certyfikacja

Testy kontraktowe (OpenAPI → generowanie klientów testowych).
Zestawy opraw według jurysdykcji, złote pliki do raportowania.
„Czarne listy” pól PII w dziennikach; statyczna analiza tajnych przecieków.
Regularne ćwiczenia DR w celu przywrócenia archiwów raportów.

16) Przykłady

16. 1 Generowanie raportów

Zapytanie

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}
}

Odpowiedź

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

16. 2 STR/SAR wysłać

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 Samodzielne wykluczenie

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

17) Wbudowany audyt i niezmienność

Autologia: 'request _ id',' trace _ id', klient wywołujący, zakres.
Podpisywanie pakietów raportów (SHA-256) + rejestr hash; okresowe kotwiczenie.
Archiwum WORM do przesyłania danych regulacyjnych i STR.

Historia konfiguracji reguł i szablonów (dziennik zmian zasad,

18) Procesy i RACI (w skrócie)

R: Zespół ds. platform zgodności (rozwój/operacje).
A: szef ds. zgodności/CISO (polityki, budżety, priorytety).
C: Legal/DPO, Finance, Architecture, Data.
I: Produkt, Wsparcie, Partnerzy (PSP/KYC).

19) Plan działania w zakresie wdrażania

1. '/v1/kyc/check ', '/v1/aml/transaction', '/v1/reports/generate '(2-3 wzorce kluczy).

2. OAuth2 + limit szybkości + początkowa idempotencja.

3. Archiwum raportów w Magazyn obiektów z podpisem hash.

4. Deska rozdzielcza SLO i kolejki zadań.

• Wzory jurysdykcyjne (5-8 rynków), STR/SAR, punkty końcowe RG, DSAR.
• Agregacja dostawców (CUS/sankcje), retrai, dedupe.
• Polityka prawna Hold, WORM, rozszerzone role.

• Reguła-as-Code dla raportów/zasady AML, zmiana symulatora.
• Wielopłatowość (B2B2C, marki/skórki), kwoty i rachunki.
• Piaskownica i certyfikat dla zewnętrznych integratorów.

20) Typowe błędy i sposób ich unikania

Rozbieżność systemów według rynku: scentralizowany katalog, systemy auto-lint.
No idempotence - Type 'idempotence _ key' i okno deduplication.
Sekrety w dziennikach: filtry połykania, analiza statyczna.
Długie raporty online: wykonaj asynchronicznie z ciągnięciem statusu i powiadomieniami.
Słabe RBAC: post 'read _ reports', 'generate _ reports', 'admin'.
Waluta/timezon: naprawić 'fx _ source', 'timezon', przechowywać UTC.

21) Słownik (krótki)

KYC/KYB - identyfikacja osób fizycznych/prawnych.
AML/STR/SAR - przeciwdziałanie praniu pieniędzy/podejrzane działanie/sprawozdanie.
RG to odpowiedzialna gra.
GGR/NGR - Dochody z gier brutto/netto.
WORM - przechowywanie zapisu raz.
Rule-as-Code - reguły jako kod z testami/wersioning.

22) Linia dolna

API zgodności i raportowania jest stabilna, bezpieczna i znormalizowana warstwa między operacjami iGaming i wymogami regulacyjnymi. Przestrzeganie zasad zawartych w tym artykule (ścisłe systemy, bezpieczna integracja, idempotencja, niezmienne audyty, szablony jurysdykcyjne i SLO) zapewnia przewidywalność, szybkie przejście audytów i ograniczanie ryzyka na kluczowych rynkach.