انطباق و گزارش API

1) هدف

• جمع آوری و اعتبار از حوادث (بازی/پرداخت/احراز هویت) برای AML/بازی مسئول (RG).
• بازرسی (KYC/KYB، تحریمها/PEP، منابع مالی، سن).
• گزارش نظارتی (دوره ای و موقت) توسط بازار.
• حفظ سیاهه های حسابرسی و اجرای هلدینگ حقوقی
• تبادل اطلاعات با ارائه دهندگان (مبادلات PSP، KYC، لیست تحریم ها) و پورتال های دولتی.

نتیجه: کاهش سربار عملیاتی، گزارش سریعتر، ردیابی و انطباق محلی.

2) محدوده

شناسایی و تأیید: وضعیت KYC/KYB، سطح تأیید، اسناد.
AML/تحریم/PEP: غربالگری، نظارت بر معاملات، STR/SAR، هشدار.
بازی مسئولانه (RG): محدودیت ها، خود حذفی، «خنک کردن»، مقیاس خطر رفتاری.
پرداخت ها و معاملات: سپرده ها/برداشت ها، بازپرداخت، مکانیک پاداش.
گزارش: GGR/مالیات، بازیکن/ثبت جلسه، محدودیت های بازاریابی، حوادث امنیتی.
ممیزی و ذخیره سازی: سیاهههای مربوط تغییر ناپذیر (WORM)، حقوقی نگه دارید، DSAR/RTBF.

3) مصرف کنندگان و تولید کنندگان داده

مصرف کنندگان: تنظیم کننده ها، انطباق داخلی/ریسک، BI/DWH، SecOps، امور مالی.
تولید کنندگان: جبهه/backends iGaming، PSP/aquiring، ارائه دهندگان KYC، ضد تقلب، CRM، شبکه های وابسته.

4) مرجع معماری

1. لبه/API- шлюз (mTLS، OAuth2/OIDC، محدودیت نرخ، WAF).
2. خدمات انطباق (قوانین کسب و کار، ارکستراسیون ارائه دهنده، عادی سازی).
3. اتوبوس رویداد (کافکا/Redpanda) - فن از در SIEM/DWH/آرشیو.

• آنلاین (PostgreSQL/ClickHouse) برای پرس و جو/جمع آوری سریع.
• بایگانی (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' - غربالگری تحریم/PEP.
'GET/v1/sanctions/{ user _ id }/hits' - مسابقات/تشدید.

5. 2 AML و نظارت بر معاملات

'POST/v1/aml/transaction' - ارسال یک رویداد (سپرده/درون/شرط/پرداخت).
GET/v1/aml/هشدارها ؟ state = open '- هشدارها/موارد را باز کنید.
'POST/v1/aml/str' - تشکیل و ارسال STR/SAR (توسط بازار).

5. 3 بازی مسئولانه (RG)

'POST/v1/RG/خود حذفی' - تنظیم/حذف خود حذفی.
'GET/v1/rg/limits/{ user _ id}' - محدودیتها (واریز/نرخ/زمان).
«POST/v1/rg/assessment» - ارزیابی ریسک رفتار.

5. ۴ گزارش و ثبت

'POST/v1/reports/generate' - تولید گزارش (نوع، دوره، صلاحیت).
GET/v1/reports/{ report _ id} - وضعیت، دانلود مصنوع (PDF/CSV/JSON)، هش.
'GET/v1/registers/{ type}' - ثبت (بازیکنان، جلسات، پاداش، GGR) با صفحه بندی.

5. 5 حسابرسی و معاملات قانونی

'GET/v1/audit/events' - انتخاب رویدادها (فیلدهای ECS/OCSF را فیلتر کنید).
'POST/v1/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 (اعتبار مشتری، JWT)، mTLS اختیاری.
مجوز: RBAC/ABAC ؛ دامنه های جداگانه توسط دامنه ('aml: write'، 'kyc: read'، 'reports: generate').
رمزگذاری: TLS 1. 2 + در حمل و نقل ؛ در حالت استراحت از طریق KMS/CMK ؛ JWE برای زمینه های حساس.
حداقل PII: حداقل فروشگاه ؛ ماسک PAN/IBAN aliasing 'user. pseudo_id' است.
ورود به سیستم دسترسی: حسابرسی از تمام خواندن «حساس» نقاط پایانی، هشدار برای آپلود توده.
نگهداری و نگهداری قانونی: ذخیره سازی WORM برای گزارش ها و STR ؛ سیاست های نگهداری 5-7 ساله (بر اساس بازار).

8) نسخه و سازگاری

نسخهبندی URI: '/v1 '، '/v2' ؛ تغییرات جزئی - از طریق زمینه های قابل گسترش.
سیاست استهلاک: ≥ 6-12 ماه پشتیبانی ؛ عناوین «غروب آفتاب»، «کاهش ارزش».
طرحوارهها: طرحوارۀ JSON + OpenAPI ؛ قراردادها در CI تایید می شوند.
مهاجرت: آداپتورها/ویژگی های پرچم، سازگاری دو طرفه برای دوره انتقال.

9) قابلیت اطمینان: idemotency و «دقیقا یک بار»

Idempotency-کلید در 'POST' (کلید فروشگاه ≥ 24-72 ساعت).
حداقل یک بار تحویل از طریق اتوبوس + دریافت deduplication (شناسه رویداد/هش).
Outbox/Inbox-pattern برای ادغام، retray با مکث نمایی و لرزش.
سفارش: user _ id/account _ id کلید پارتیشن بندی برای جبرگرایی.

10) صفحه بندی، فیلتر، جستجو

صفحه بندی: مبتنی بر مکان نما ('page _ token'، 'limit <= 1000').
فیلترها: توسط صلاحیت، دوره، وضعیت، ارائه دهنده، ارزیابی ریسک.
جستجوی متن کامل برای حسابرسی/ثبت (زیر مجموعه محدود از زمینه ها).
صادرات: ناهمزمان، محدودیت اندازه، تهیه آرشیو با امضای هش.

11) محدودیت ها و سهمیه ها

محدودیت نرخ در هر مشتری/مسیر (به عنوان مثال،. 100 دور در ثانیه پشت سر هم، 1000 دور در دقیقه پایدار).
محدودیت بودجه در گزارش های سنگین (اعتبار/روز).
حفاظت N + 1: دسته ها و نقاط پایانی جمع شده.
محدودیت عمق نمونه های تاریخی (به عنوان مثال، ≤ 24 ماه آنلاین، از این پس به عنوان آرشیو نامیده می شود).

12) داشبورد و SLO

تاخیر مصرف p95 <30 ثانیه ؛ موفقیت KYC> 99٪ ؛ STR-SLA - ارسال ≤ 24 ساعت.
API ≥ 99 در دسترس بودن. 9%; تاخیر p95 <300 میلی ثانیه برای خواندن ؛ <800 میلی ثانیه برای ضبط.
ذخیره سازی هزینه/GB گزارش ؛ اطلاعیه های Ack-rate به تنظیم کننده ها.
ابزارک ها: نقشه گرمای هشدار AML، قیف KYC، انتشار گزارش کشور، صف STR.

13) حوزه های قضایی: نقشه برداری و الگوهای

قالب گزارش بازار (زمینه ها، فرمت ها، فرکانس): 'EE'، 'LT'، 'LV'، 'RO'، 'MT'، 'UK'، و غیره

نقشه برداری مدت (GGR/NGR، پاداش، محدودیت سپرده، کنترل سن).
محلی سازی منطقه زمانی/تقویم ؛ رفع منبع FX تاثیر DST برچسب.
دایرکتوری طرح: 'reports/{ jurisdiction }/{ type }/{ version} .schema. جی سون...

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 → ایجاد مشتریان تست).
مجموعه های ثابت توسط صلاحیت، فایل های طلایی برای گزارش.
«لیست سیاه» از زمینه های 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) ساخته شده در حسابرسی و غیر قابل تغییر

Autologation: 'request _ id'، 'trace _ id'، فراخوانی مشتری، دامنه.
امضای بسته های گزارش (SHA-256) + رجیستری هش ؛ لنگر انداختن دوره ای.
بایگانی WORM برای آپلودهای نظارتی و STR.
تاریخچه تنظیمات قانون و قالب (ورود به سیستم تغییر سیاست ↔ لینک).

18) فرآیندها و RACI (به طور خلاصه)

R: تیم پلت فرم پذیرش (توسعه/عملیات).
A: رئیس انطباق/CISO (سیاست ها، بودجه ها، اولویت ها).
C: حقوقی/DPO، امور مالی، معماری، داده ها.
I: محصول، پشتیبانی، شرکا (PSP/KYC).

19) پیاده سازی نقشه راه

1. '/v1/kyc/check ', '/v1/aml/transaction', '/v1/reports/generate '(2-3 الگوهای کلیدی).

2. OAuth2 + rate-limit + idempotency پایه.

3. بایگانی گزارش ها در Object Storage با امضای هش.

4. داشبورد SLO و صف های کار.

• قالب های قضایی (5-8 بازار)، STR/SAR، RG-endpoints، DSAR.
• تجمع ارائه دهنده (CUS/تحریم ها)، retrai، dedupe.
• سیاست های نگهداری قانونی، WORM ها، نقش های گسترده.

• قانون به عنوان کد برای گزارش/قوانین AML، شبیه ساز تغییر دهید.
• چند اجاره (B2B2C، مارک ها/پوست)، سهمیه و صدور صورت حساب.
• Sandbox و صدور گواهینامه برای انتگرال های خارجی.

20) اشتباهات معمول و نحوه اجتناب از آنها

واگرایی طرح های بازار: دایرکتوری متمرکز، طرح های خودکار.
بدون idempotency - نوع 'idempotency _ key' و پنجره deduplication.
اسرار در سیاهههای مربوط: فیلتر مصرف، تجزیه و تحلیل استاتیک.
گزارش های آنلاین طولانی: انجام ناهمگام با وضعیت کشیدن و اطلاعیه ها.
RBAC ضعیف: پست 'read _ reports', 'generate _ reports', 'admin'.
ارز/منطقه زمانی: رفع 'fx _ source'، 'منطقه زمانی'، فروشگاه UTC.

21) واژه نامه (کوتاه)

KYC/KYB - شناسایی اشخاص حقیقی/حقوقی.
AML/STR/SAR - فعالیت/گزارش ضد پولشویی/مشکوک.
RG یک بازی مسئولانه است.
GGR/NGR - درآمد ناخالص/خالص بازی.
WORM - ذخیره سازی یکبار نوشتن.
Rule-as-Code - قوانین به عنوان کد با تست/نسخه.

22) خط پایین

انطباق و گزارش API یک لایه پایدار، امن و استاندارد بین عملیات iGaming و الزامات قانونی است. پیروی از اصول این مقاله (طرح های دقیق، ادغام امن، بی نظمی، حسابرسی غیر قابل تغییر، قالب های قضایی و SLO) تضمین پیش بینی، عبور سریع از ممیزی و کاهش خطر در بازارهای کلیدی است.