راهنمای ادغام گمبل هاب

1) مدل بررسی و تعامل

• ارائه دهنده API: شما با GambleHub API تماس می گیرید (کیف پول، پاداش، گزارش).
• ارائه دهنده خارجی: ما وب سایت ها/نقاط پایانی خود را (تعادل، معاملات، KYC) می نامیم.

1. لبه/API (REST/gRPC، وب سایت ها)

2. رویدادها (اتوبوس رویداد: شرط/پرداخت/کیف پول/ICC)

3. گزارش (API + S3/SFTP صادرات)

4. عملیات (حوادث، SLO، اعتبارات SLA)

2) محیط ها، دامنه ها و IP

SLA قراردادی در قرارداد ثابت شده است. به روز رسانی IP در پیش منتشر شده است. اجازه دهید Allowlist.

3) احراز هویت و مجوز

• OAuth2 اعتبار مشتری: سرور به سرور («دامنه»: «کیف پول: خواندن»، «کیف پول: نوشتن»، «شرط بندی: نوشتن»، «گزارش: خواندن»).
• JWT (صادر کننده = GambleHub): امضای RS256، کلید در نقطه پایانی JWKS.
• mTLS: احراز هویت متقابل TLS در سطح ورودی (به درخواست انطباق).

POST /oauth2/token grant_type=client_credentials&scope=wallet:write bet:write
→ { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

دامنه ها در هر تماس بررسی می شوند. برای عملیات با خطر بالا (پرداخت)، گام به گام استفاده می شود: یک دامنه جداگانه و، به صورت اختیاری، اتصال به IP/ASN.

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

مسیر: '/v1/... ', '/v2/...' (نسخه اصلی ناسازگار است).
تغییرات جزئی و در حال گسترش - از طریق گسترش طرح (زمینه های اختیاری جدید).
تخفیف - 90 روز با اطلاع قبلی.
کتاب های وب با عنوان «X-GH-Event-Version: 1» نسخه می شوند.

5) محدودیت ها، سهمیه ها و idemotency

• 'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reset'.
• ۴۲۹ با «Retry-After» (ثانیه) باز می گردد.
• تمام روش های ناامن نیاز به «Idempotency-Key» (TTL 24-72 ساعت) دارند. تکرار یک پرس و جو یکسان نتیجه اصلی را برمی گرداند ("409 IDEMP_REPLAY' در درگیری).

6) استانداردهای خطا

json
{
"type": "https://docs. gamblehub. io/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"trace_id": "a1b2c3...",
"retriable": false,
"errors": [{"field":"amount","code":"min","message":"Must be >= 1"}]
}

قابل بازیابی: 5xx/ 503/504/429 (с 'Retry-After'). غیر قابل بازیابی: 400/401/403/404/409/ 422/410/415/412.

7) طرح های داده (هسته)

7. 1 بازیکن

json
{
"player_id": "p_123",
"country": "CA",
"currency": "CAD",
"rg_flags": {"self_excluded": false, "limits": {"daily_loss": 100}},
"kyc_status": "verified    pending    failed"
}

7. 2 جلسه

json
{
"session_id": "s_789",
"player_id": "p_123",
"started_at": "2025-11-03T17:55:00Z",
"ip": "203. 0. 113. 5",
"device": {"ua":"...", "os":"Android", "model":"..."}
}

7. 3 کیف پول/معاملات

json
{
"txn_id": "t_001",
"player_id": "p_123",
"type": "deposit    withdrawal    bet    win    bonus    adjustment",
"amount": "12. 34",
"currency": "EUR",
"balance_after": "123. 45",
"metadata": {"provider":"psp_x","request_id":"r_456"}
}

7. 4 نرخ/پرداخت

json
{
"bet_id": "b_456",
"player_id": "p_123",
"game_id": "g_777",
"stake": "1. 50",
"currency": "EUR",
"placed_at": "2025-11-03T17:58:10Z",
"round_id": "rnd_aa1",
"provider": "StudioX"
}

json
{
"settlement_id": "st_456",
"bet_id": "b_456",
"win_amount": "3. 75",
"settled_at": "2025-11-03T17:59:02Z",
"outcome": "win    lose    void"
}

7. 5 پاداش

json
{
"bonus_id": "bo_900",
"player_id": "p_123",
"type": "freespin    cash    wagered",
"state": "issued    active    expired    consumed",
"wagering": {"target": "100. 00","progress":"45. 20","currency":"EUR"}
}

8) REST API (قطعات OpenAPI)

yaml paths:
/v1/wallet/balance/{player_id}:
get:
summary: Get wallet balance security: [{ oauth2: [wallet:read] }]
responses:
'200': { description: OK }
'401': { $ref: '#/components/responses/Problem' }
'404': { $ref: '#/components/responses/Problem' }

/v1/wallet/transactions:
post:
summary: Create wallet transaction security: [{ oauth2: [wallet:write] }]
parameters:
- name: Idempotency-Key in: header required: true schema: { type: string }
responses:
'201': { description: Created }
'409': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }

/v1/bets:
post:
summary: Register bet security: [{ oauth2: [bet:write] }]
responses:
'201': { description: Created }
'422': { $ref: '#/components/responses/Problem' }

9) Webhooks (گمبل هاب به شریک)

• 'X-GH-Event': 'بازیکن. ایجاد شده است. شروع شد. قرار داده است. سر و سامان گرفت. تغییر کرد. به روز شد. دست و پا میزد
• «X-GH-Event-Id»: UUID منحصر به فرد
• 'X-GH-Signature': 'sha256 = '
• «X-GH-Retry»: تلاش بدون
• «X-GH-Event-Version»: «1»

json
{
"event": "bet. settled",
"occurred_at": "2025-11-03T18:00:12Z",
"data": {
"settlement_id": "st_456",
"bet_id": "b_456",
"player_id": "p_123",
"win_amount": "3. 75",
"currency": "EUR",
"outcome": "win"
}
}

پاسخ میزبان - تنها 2xx موفقیت آمیز است. در غیر این صورت - retrai: عقب نشینی نمایشی (1s، 3s، 10s، 30s، 2m، 10m، 30m ؛ (حداکثر 24 ساعت) از «X-GH-Event-Id» برای deduplication استفاده کنید.

text expected = base64(hmac_sha256(request_body, SHARED_SECRET))
header  = split(X-GH-Signature, '=')[1]
assert header == expected

10) سفارش جریان نقدی (جریان کیف پول)

1. سپرده (PSP → کیف پول. اعتبار)

2. شرط (نگه دارید/اجازه или بدهی مستقیم)

3. حل و فصل (نگه انتشار ؛ 'برنده '/' از دست دادن '/' از درجه اعتبار ساقط')

4. برداشت وجه (کیف پول) بدهی → PSP)

تعادل نگه دارید و چند کیف پول (واقعی/پاداش) پشتیبانی می شوند.

11) Sandbox و سناریوهای تست

بازیکنان تست: 'p _ sbx _'، ارزهای' EUR 'USD' CAD '.
ارائه دهندگان بازی تقلید: برنده/از دست دادن/از درجه اعتبار ساقط, تخفیف, تاخیر.
سندباکس KYC: پاسخهای "بازبینی" ناموفق "تأیید شده در الگوهای گذرنامه.
PSP sandbox: статусы 'مجاز' ضبط شده 'جمع آوری شده'.

• ترازنامه استاوکا → vyplata → sverka
• دور عقب/خالی
• عدم توانایی در پیشنهاد مجدد
• شکست webhook با retrays و deduplication پس از آن
• 429 و تصحیح «بازگشت»
• 5xx با عقب نشینی نمایی مشتری

12) آشتی و گزارش

API آشتی

yaml
GET /v1/reports/reconciliation? from=...&to=...&scope=wallet    bets
→ CSV/JSON: { player_id, bet_id, stake, win, currency, balance_delta, provider }

خلاصه روزانه: گردش، GGR/NGP، ارائه دهندگان، تجزیه جغرافیایی/ارز.
صادرات: S3/SFTP با مانیفست های امضا شده و هش فایل (SHA256).
گزارش منطقه زمانی: UTC (مگر اینکه در قرارداد مشخص شده باشد).

13) قابلیت مشاهده و SLO

SLI: موفقیت API ≥ 99. 95٪ (28d)، تاخیر p95 برای روش های بحرانی، موفقیت تحویل وب سایت.
سوزاندن هشدار (سریع/آهسته) در بودجه اشتباه است.
همبستگی ردیابی: 'trace _ id' در پاسخ/سیاهههای مربوط، drilldown به ردیابی.
صفحه وضعیت: Edge، Wallet، Bets، Webhooks، PSP، اجزای KYC.

14) ایمنی و انطباق

به حداقل رساندن PII ؛ PAN/اسرار در سیاهههای مربوط/webhooks ممنوع است.

مدیریت مخفی و چرخش کلید

RG (قمار مسئول): خود حذفی/پرچم حد باید در انکار خودکار شرط/پرداخت شود.
AML/KYC: رویدادهای «kyc». به روز شده، aml. هشدار 'با اشتراک در دسترس هستند ؛ تصمیم گیری در سیستم خود و یا از طریق ماژول ما.
GDPR/DSAR: نقاط پایانی برای آپلود/حذف اطلاعات شخصی بازیکن برای درخواست های قانونی.
mTLS و HSTS به طور پیش فرض در محیط تولید فعال می شوند.

15) عملکرد و سهمیه

• RPS: 50 (پشت سر هم 100)
• صفحات وب همزمان: 10
• اندازه بدن: ≤ 256 کیلوبایت (رویدادهای بازی)، ≤ 64 کیلوبایت (کیف پول)

درخواست ارتقاء طرح از طریق مدیر حساب، مشخص کردن پیش بینی/حجم RPS.

16) مدیریت تغییر و انتشار

تغییر ویندوز: کار برنامه ریزی شده - در برنامه، اطلاع رسانی ≥ 5 روز کاری.
مهاجرت نسخه: دوگانه نوشتن/دوگانه خواندن در طول دوره انتقال.
آزمون قرارداد CI: طرح JSON، فیلدهای مورد نیاز، stable 'error _ code'.
Canary: شامل تدریجی ترافیک برای ویژگی های جدید.

17) صدور گواهینامه ادغام (چک لیست)

• پیشنهاد/پرداخت ثبت نام/از درجه اعتبار ساقط
• Idempotency در تمام نقاط نوشتن پایان
• درست 429/5xx + پردازش برگشت
• Webhook تأیید امضا، X-GH-Event-Id Deduplication
• آشتی تعادل پس از سری از حوادث (برنده/از دست دادن)
• گزارش های آشتی با داده های شما موافق است

• عقب نشینی Webhook اجرا می شود
• زمان بندی مشتری ≤ 10c، تلاش کل ≤ 30c
• قطع کننده مدار در وابستگی ها

• ذخیره اسرار در مدیر مخفی
• نسخه PII در سیاهههای مربوط
• پرچم RG/AML در زمان واقعی در نظر گرفته

18) سناریوهای اغلب استفاده شده

18. 1 ثبت نام نرخ با idemotency

POST /v1/bets
Idempotency-Key: bet-p_123-rnd_aa1-1

{ "player_id":"p_123","game_id":"g_777","stake":"1. 50","currency":"EUR","round_id":"rnd_aa1" }
→ 201 Created { "bet_id":"b_456" }

18. 2 شکست webhook به دنبال موفقیت

1. سرور شما در دسترس نیست → 5xx → backoff retro.
2. پس از بهبودی - همان «X-GH-Event-Id» را بگیرید → موظف به نادیده گرفتن موارد تکراری هستند.

18. 3 تخریب جزئی ارائه دهنده

ما 503 را بازپرداخت خواهیم کرد تکرار با عقب نشینی

با تخریب طولانی - توقف مارک ارائه دهنده و شامل مسیریابی هوشمند (اگر در قرارداد).

19) DevEx و پشتیبانی

پورتال: کلید، استفاده، webhooks، سیاهههای مربوط تحویل، داشبورد SLO، گزارش صادرات.
Webhooks پخش: redelivery با محدوده تاریخ/ID.
حوادث: ایجاد خودکار بلیط، اتاق جنگ، پس از مرگ ≤ 48 ساعت در SEV-1.
ارتباطات: # partners-status channel/mail on-call 24 × 7 (Enterprise).

20) برنامه ریزی (2-4 هفته)

1. هفته 1: صدور کلید، اتصال sandbox، سناریوهای پایه (شرط/پرداخت/کیف پول).
2. هفته 2: Webhooks و آشتی، پرچم RG/KYC، تست بار، رفتار 429/5xx.
3. هفته 3: گزارش (آشتی، آپلود)، امنیت (امضا، اسرار)، تست قرارداد.
4. هفته 4: صدور گواهینامه، canary-inclusion در فروش، نظارت، ماتریس تماس.

21) مینی سوالات متداول

آیا می توانم gRPC داشته باشم ؟

بله، بنا به درخواست ؛ نقشه برداری کد خطای HTTP در مشخصات ارائه شده است.

چگونه می توان داده های یکپارچهسازی با سیستمعامل را دریافت کرد ؟

از طریق گزارش های «آشتی» (از/به تاریخ) و یا آپلود S3/SFTP.

چگونه محدودیت هایم را برطرف کنم ؟

از طریق مدیر پورتال/حساب نشان می دهد پیش بینی RPS/رقابت.

چه چیزی منبع حقیقت تعادل محسوب می شود ؟

گزارش تراکنش کیف پول GambleHub + آشتی روزانه.

مجموع

ادغام با GambleHub بر اساس یک قرارداد واضح ساخته شده است: API های پایدار و طرح ها، وب سایت های امضا شده، idempotency و retrays، محدودیت های شفاف و گزارش، و همچنین الزامات امنیتی و انطباق. با پیروی از این راهنما و چک لیست های صدور گواهینامه، شما به سرعت به بازار می رسید، جریان های نقدی قابل اعتماد و گزارش های سازگار بدون اختلاف را ارائه می دهید.