מדריך אינטגרציה GamBlehub

1) סקירה ומודל אינטראקציה

• ספק API: אתה קורא API GambleHub (ארנק, בונוסים, דוחות).
• ספק חיצוני: אנו מכנים את קובצי האינטרנט/נקודות הקצה שלכם (שיווי משקל, עסקאות, KYC).

1. Edge/API (Rest/gRPC, Webhooks)

2. אירועים (אוטובוס אירועים: הימורים/תשלום/ארנק/ICC)

3. דיווח (API + S3/SFTP ייצוא)

4. מבצעים (תקריות, SLO, קרדיטים SLA)

2) סביבות, תחומים ואיי ־ פי

ה-SLA החוזי קבוע בחוזה. עדכוני IP מתפרסמים מראש. הרשה רשימת כל.

3) אימות ואישור

• OAuth2 הרשאות ללקוח: שרת לשרת ("scope": "arket:" read "," arket: write "," with: write "," report: read ").
• JWT (issuer = GambleHub): חתימה RS256, מפתחות בקצה JWKS.
• אימות 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) מגבלות, מכסות ואידמפוטנטיות

• 'X-Extlimite-Limit', 'X-Extlimit-Lessons',' X-Extlimit-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 (lember '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) מנוחה 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 (GambleHub to Partner)

• אקס-ג 'י-אייץ': שחקן. נוצר "Session. התחיל 'bet. ממוקמת במקום. התיישב 'wallet. החלפתי בגדים. מעודכן 'rg. flagged&fs
• "X-GH-אירוע-Id': UUID ייחודי
• 'X-GH-חתימה': 'sh256 = "
• אקס-ג 'י-אייץ' ריטרי: ניסיון לא
• 'X-GH-Event-Version': '1 &fospos

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 נחשב להצלחה. אחרת - רטריי: גיבוי מעריכי (1, 3, 10, 30, 2 מ ', 10 מ', 30 מ '; 24 שעות מקסימום). השתמש 'X-GH-אירוע-Id' לביטול.

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

10) הזמנת תזרים מזומנים (תזרים ארנק)

1. (PSP = ארנק. אשראי)

2. הימור (hold/לאשר חיוב ישיר)

3. התיישבות (hold שחרור; 'win '/' lose '/' void')

4. גמילה (ארנק. debit PSP)

החזיקו מאזנים וריבוי ארנקים (אמיתי/בונוס) נתמכים.

11) ארגז חול ותרחישי מבחן

נגני מבחן: "p _ sbx _', מכניס" EUR 'USd' CAD ".
ספקי משחקים מחקים: ניצחון/הפסד/חלל, הנחות, עיכובים.
ארגז חול: "מאומת" נכשל "תגובות ביקורת על תבניות דרכון.
ארגז חול: ”PSP” imported 'capted' decled 'reserved.

• שיווי משקל Stavka * vyplata @ sverka
• מסירה/חלל עגול
• אידמפוטנטיות בהצעה מחדש
• כישלון בבדיקת רשת עם מגשים מחודשים ושכפול לאחר מכן
• 429 ותיקון 'Retry-After &pos
• 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

הצלחה של API/99. 95% (28d), p95 latency עבור שיטות קריטיות, webhook הצלחה מסירה.
כוויית התראות (מהיר/איטי) בתקציב שגוי.
מתאם עקבות: "trace _ id' בתגובות/לוגים, drilldown לעקבות.
עמוד מצב: Edge, Wallet, Bets, Webhooks, PSP, KYC רכיבים.

14) בטיחות וציות

מזעור PII; סודות פאן/פאן אסורים ביומנים/קובצי אינטרנט.
ניהול סודי וסבב מפתח.
RG (הימורים אחראיים): הרחקה עצמית/הגבלה של דגלים צריכה לגרום להכחשה אוטומטית של הימורים/תשלומים.
אירועים של קייק. מעודכן, 'aml. התראה "זמינים על ידי מנוי; לקבל החלטות במערכת שלך או דרך המודול שלנו.
GDPR/DSAR: נקודות סוף להעלאה/מחיקת נתונים אישיים של שחקן עבור בקשות משפטיות.
MTLS ו ־ HSTS מופעלים כברירת מחדל בסביבת הייצור.

15) ביצועים ומכסות

• RPS: 50 (פרץ 100)
• קורות מקוונות: 10
• גודל הגוף: 256 KB (אירועי משחקים), סימון 64 KB (ארנק)

מבקש שדרוג של התוכנית באמצעות מנהל החשבון, המפרט את תחזית ה ־ RPS/כרכים.

16) שינוי וניהול שחרור

שינוי חלונות: עבודה מתוכננת - בלוח זמנים, הודעה על 5 ימי עבודה.
הגירת גרסה: כתיבה כפולה/קריאה כפולה בתקופת המעבר.
בדיקות חוזה CI: סכימת JSON, שדות דרושים, stable 'error _ code'.
קנרית: הכללה הדרגתית של תנועה לתכונות חדשות.

17) הסמכת אינטגרציה (בדוק-רשימה)

[ ] הצעת מחיר/רישום תשלום/ריק

[ ] אידמפוטנטיות בכל נקודות סוף כתיבה

[ ] תיקון 429/5xx + גיבוי עיבוד

[ ] אימות חתימת Webhook, X-GH-Event-ID Detuplication

[ ] איזון פיוס לאחר סדרת אירועים (win/lose)

[ ] דיווחי פיוס מסכימים עם הנתונים שלך

[ נסיגות ] Webhook מיושמות

[ ] פסקי זמן לקוח 10c, סך הכל ניסיון 30c

[ ] מפסק מעגל על תלות

[ ] לאחסן סודות במנהל הסודי

[ ] מהדורת מח "ש ביומנים

דגלי 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 להיכשל webhook ואחריו הצלחה

1. השרת שלך לא זמין. פי 5xx. רטרו אחורי.
2. לאחר ההחלמה - קחו את אותו 'X-GH-Event-Id'.

18. 3 השפלה חלקית של הספק

אנחנו נחזיר 503; אני חוזר עם גיבוי.
עם השפלה ארוכה - תפסיקו לסמן את הספק ואת הניתוב החכם (אם בחוזה).

19) Devex ותמיכה

פורטל: מפתחות, שימוש, פתקי אינטרנט, רישומי משלוחים, לוחות מחוונים, דוחות ייצוא.
שידור חוזר: Redelivery by date range/id.
תקריות: יצירת כרטיס אוטומטי, חדר מלחמה, לאחר המוות 48 שעות על SEV-1.
תקשורת: # Partner-status channel/mail on-call 24 × 7 (Enterprise).

20) תוכנית עליה למטוס (2-4 שבועות)

1. שבוע 1: הנחת מפתח, חיבור ארגז חול, תרחישי בסיס (הימור/תשלום/ארנק).
2. שבוע 2: Webhooks and Reconciliations, RG/KYC Flags, Load Tess, 429/5xx.
3. שבוע 3: דיווח (פיוס, העלאות), אבטחה (חתימות, סודות), בדיקות חוזה.
4. שבוע 4: הסמכה, הכללת כנריות במכירות, ניטור, מטריצת מגע.

21) מיני ־ FAQ

אני יכול לקבל GRPC?
כן, לפי בקשה; מיפוי קוד שגיאות HTTP מסופק במפרט.

איך להשיג נתוני רטרו?
באמצעות 'דיווחי פיוס' (מ/עד תאריכים) או להעלות S3/SFTP.

איך אני מרים את הגבולות שלי?
דרך מנהל הפורטל/חשבון המציין תחזית RPS/תחרותיות.

מה נחשב למקור אמיתות האיזון? ‏

יומן עסקת הארנק של GambleHub + פיוס יומי.

סך הכל

אינטגרציה עם GambleHub בנויה על חוזה ברור: API יציב ותוכניות, ספרי אינטרנט חתומים, אידמפוטנטיות ומגשים מחדש, גבולות שקופים ודיווח, כמו גם דרישות אבטחה וציות. על ידי מעקב אחר מדריך זה ורשימות הסמכה, תוכל להגיע במהירות לשוק, לספק זרימות מזומנים אמינות ודוחות עקביים ללא סתירות.