دليل تكامل GambleHub

1) نظرة عامة ونموذج تفاعل

• مزود واجهة برمجة التطبيقات: يمكنك الاتصال بواجهة برمجة تطبيقات GambleHub (المحفظة والمكافآت والتقارير).
• المزود الخارجي: نسمي خطافات الويب/نقاط النهاية (التوازن، المعاملات، KYC).

1. Edge/API (REST/gRPC، Webhooks)

2. الأحداث (حافلة الحدث: الرهانات/المدفوعات/المحفظة/المحكمة الجنائية الدولية)

3. الإبلاغ (API + S3/SFTP الصادرات)

4. العمليات (الحوادث، وجيش تحرير السودان، وجيش تحرير السودان)

2) البيئات والمجالات والملكية الفكرية

تم تحديد اتفاق SLA التعاقدي في العقد. يتم نشر تحديثات IP مسبقًا. اسمح لـ Allowist.

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 }

يتم فحص النطاقات في كل مكالمة. وبالنسبة للعمليات التي تنطوي على مخاطر عالية (المدفوعات)، تُستخدم الزيادة: نطاق منفصل، ومن الناحية الاختيارية، يكون ملزماً للشبكة المتكاملة/الشبكة.

4) الحرث والتوافق

المسار: '/v1/... "، "/v2/"... (النسخة الرئيسية غير متوافقة).
تغييرات طفيفة ومتزايدة - من خلال توسيع المخطط (مجالات اختيارية جديدة).
التخفيضات - 90 يومًا مع إشعار.
تم تحديث عناوين الويب بعنوان «X-GH-Event-Version: 1».

5) الحدود والحصص والخصوصية

• «X-RateLimit-Limite»، «X-RateLimited-Reset'،» X-RateLimite-Reset'.
• 429 يعود مع «Retry-After» (ثانية).
• تتطلب جميع الطرق غير الآمنة «Idempotency-Key» (TTL 24-72 h). إعادة استفسار متطابق يرجع النتيجة الأصلية ('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 (شظايا 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) عناوين الويب (GambleHub to Partner)

• حدث X-GH: "لاعب. خلقت 'session. بدأت 'bet. وضعت 'bet. استقر 'ممر. تغير 'kyc. تم تحديثه 'rg. تم الإبلاغ عنها '
• "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» للتفريغ.

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) صندوق الرمل وسيناريوهات الاختبار

لاعبو الاختبار: "p _ sbx _'، العملات" بالدولار الأمريكي "CAD'.
يحاكي مزودو اللعبة: الفوز/الخسارة/الفراغ، الخصومات، التأخير.
صندوق رمل KYC: ردود "مراجعة" فاشلة "تم التحقق منها على قوالب جوازات السفر.
صندوق الرمل PSP: تم اختيار статусы «المصرح به» «معكوس».

• الميزانية العمومية Stavka→vyplata→sverka
• جولة التراجع/الفراغ
• الفراغ عند إعادة تقديم العطاءات
• فشل الخط الشبكي مع إعادة التصوير والتفريغ اللاحق
• 429 و "Retry-Aftern' الصحيح
• 5xx مع تراجع أسي من جانب العميل

12) التسويات والإبلاغ

واجهة برمجة التطبيقات للمصالحة

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).
المنطقة الزمنية للإبلاغ: التوقيت العالمي المنسق (ما لم ينص العقد على خلاف ذلك).

13) إمكانية الرصد و SLO

SLI: نجاح API ≥ 99. 95% (28 د), p95 latency for critical methods, webhook delivery success.
تنبيهات الحرق (سريعة/بطيئة) بميزانية خاطئة.
الارتباط النزير: «تتبع _ معرف» في الردود/السجلات، حفر إلى آثار.
صفحة الحالة: مكونات Edge و Wallet و Bets و Webhooks و PSP و KYC.

14) السلامة والامتثال

والتقليل إلى أدنى حد ؛ يُحظر استخدام PAN/الأسرار في السجلات/خطافات الويب.
الإدارة السرية وتناوب المفاتيح.
RG (المقامرة المسؤولة): يجب أن يؤدي الاستبعاد الذاتي/الحد من الأعلام إلى الرفض التلقائي للرهانات/المدفوعات.
AML/KYC: أحداث kyc. تم تحديث '،' aml. ' اتخاذ القرارات في نظامك أو من خلال وحدتنا.
GDPR/DSAR: نقاط النهاية لتحميل/حذف البيانات الشخصية للاعب للطلبات القانونية.
يتم تمكين mTLS و HSTS بشكل افتراضي في بيئة الإنتاج.

15) الأداء والحصص

• RPS: 50 (انفجار 100)
• خطوط الويب المتزامنة: 10
• حجم الجسم: ≤ 256 كيلوبايت (أحداث ألعاب)، ≤ 64 كيلوبايت (محفظة)

اطلب ترقية الخطة من خلال مدير الحساب، مع تحديد توقعات/أحجام RPS.

16) إدارة التغيير والإصدار

تغيير النوافذ: العمل المقرر - في الموعد المحدد، الإخطار ≥ 5 أيام عمل.
هجرات النسخة: ثنائية الكتابة/ثنائية القراءة خلال الفترة الانتقالية.
اختبارات عقد CI: مخطط JSON، الحقول المطلوبة، «خطأ _ رمز» مستقر.
الكناري: تضمين تدريجي لحركة المرور للميزات الجديدة.

17) شهادة التكامل (قائمة التحقق)

• العطاء/تسجيل الأجور/الفراغ
• الخصوصية في جميع نقاط الكتابة والنهاية
• المعالجة الصحيحة 429/5xx + التراجع
• التحقق من توقيع الويب، X-GH-Event-Id Deduplication
• تسوية التوازن بعد سلسلة من الأحداث (الفوز/الخسارة)
• تتفق تقارير التسوية مع بياناتك

• يتم تنفيذ خلوات الويب
• مهلة العميل ≤ 10 ج، إجمالي المحاولة ≤ 30 ج
• قاطع الدائرة على التبعيات

• تخزين الأسرار في المدير السري
• إصدار PII في جذوع الأشجار
• يتم النظر في أعلام RG/AML في الوقت الفعلي

18) السيناريوهات المستخدمة بشكل متكرر

18. 1 تسجيل المعدل مع الخصوصية

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 Fail webhook متبوعًا بالنجاح

1. الخادم الخاص بك غير متوفر → 5xx → back retro.
2. بعد الاسترداد - خذ نفس «X-GH-Event-Id» → ملزمون بتجاهل النسخ المكررة.

18. 3 التدهور الجزئي لمقدم الخدمة

سنقوم برد 503 ؛ كرر مع التراجع.
مع التدهور الطويل - توقف عن وضع علامات على المزود بما في ذلك التوجيه الذكي (إذا كان في العقد).

19) DevEx والدعم

البوابة: المفاتيح، الاستخدام، الخطابات الشبكية، سجلات التسليم، لوحات معلومات SLO، تقارير التصدير.
إعادة تشغيل خطافات الويب: إعادة التسليم حسب نطاق التاريخ/الهوية.
الحوادث: الإنشاء التلقائي لتذكرة، غرفة حرب، تشريح الجثة ≤ 48 ساعة على SEV-1.
الاتصالات: # partners-status channel/mail on-call 24 × 7 (Enterprise).

20) خطة الإقامة (2-4 أسابيع)

1. الأسبوع 1: الإصدار الرئيسي، وصلة الصندوق الرملي، والسيناريوهات الأساسية (الرهان/الدفع/المحفظة).
2. الأسبوع 2: عناوين الويب والتسويات، أعلام RG/KYC، اختبارات الحمل، 429/5xx السلوك.
3. الأسبوع 3: الإبلاغ (المصالحة، التحميلات)، الأمن (التوقيعات، الأسرار)، اختبارات العقد.
4. الأسبوع 4: الشهادة، إدراج الكناري في المبيعات، المراقبة، مصفوفة الاتصال.

21) الأسئلة الشائعة الصغيرة

هل يمكنني الحصول على gRPC ؟

نعم، بناء على الطلب ؛ يتم توفير رسم خرائط رمز خطأ HTTP في المواصفات.

كيف تحصل على البيانات القديمة ؟

عن طريق تقارير «التسوية» (من/إلى التواريخ) أو تحميل S3/SFTP.

كيف يمكنني رفع حدودي ؟

من خلال البوابة/مدير الحساب الذي يشير إلى توقعات RPS/القدرة التنافسية.

ما هو مصدر حقيقة التوازن ؟

سجل معاملات محفظة GambleHub + التسوية اليومية.

المجموع

تم بناء التكامل مع GambleHub على عقد واضح: واجهات برمجة التطبيقات المستقرة والمخططات، وخطوط الويب الموقعة، والحماقة وإعادة التدوير، والحدود الشفافة والإبلاغ، بالإضافة إلى متطلبات الأمن والامتثال. من خلال اتباع هذا الدليل وقوائم التحقق من الشهادات، ستصل بسرعة إلى السوق، وتوفر تدفقات نقدية موثوقة وتقارير متسقة دون تناقضات.