Οδηγός ενσωμάτωσης GambleHub

1) Επισκόπηση και μοντέλο αλληλεπίδρασης

• Πάροχος API: καλείτε API GambleHub (πορτοφόλι, μπόνους, αναφορές).
• Εξωτερικός πάροχος: ονομάζουμε webhooks/τελικά σημεία (υπόλοιπο, συναλλαγές, KYC).

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

2. Εκδηλώσεις (λεωφορείο εκδήλωσης: στοιχήματα/πληρωμές/πορτοφόλι/ΔΠΔ)

3. Υποβολή εκθέσεων (API + S3/SFTP εξαγωγές)

4. Λειτουργίες (συμβάντα, πιστωτικά μόρια SLO, SLA)

2) Περιβάλλοντα, τομείς και ΔΙ

Το συμβατικό SLA καθορίζεται στη σύμβαση. Οι επικαιροποιήσεις ΔΙ δημοσιεύονται εκ των προτέρων. Επιτρεπόμενος κατάλογος.

3) Εξακρίβωση της γνησιότητας και αδειοδότηση

• Client Credentials: server-to-server ('scope' s: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• 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 ημέρες με προειδοποίηση.
Τα Webhooks έχουν τον τίτλο «X-GH-Event-Version: 1».

5) Όρια, ποσοστώσεις και ιδιαιτερότητα

• «Όριο ορίων X- », «Όριο X- που απομένει», «Όριο X- ».
• Το 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) ΞΕΚΟΥΡΑΣΗ 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)

• 'X-GH-Event': 'player. δημιουργήθηκε 'session. ξεκίνησε 'bet. τοποθετημένο 'bet. τακτοποιημένο 'wallet. άλλαξε 'kyc. επικαιροποιημένο 'rg. flagged "
• "X-GH-Event-I : μοναδική UUID
• Υπογραφή X-GH: '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 θεωρείται επιτυχία. Διαφορετικά - ρετράι: εκθετική εφεδρική (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. διακανονισμός (ισχύς απελευθέρωσης· «win »/« lose »/« void»)

4. απόσυρση (πορτοφόλι. χρέωση → PSP)

Υποστηρίζονται ισοζύγια κράτησης και πολυ-πορτοφόλια (πραγματικό/μπόνους).

11) Αμμώδες κουτί και σενάρια δοκιμών

Δοκιμαστικοί παίκτες: 'p _ sbx _', νομίσματα' EUR 'USD' CAD '.
Οι πάροχοι παιχνιδιών μιμούνται: νίκη/απώλεια/κενό, εκπτώσεις, καθυστερήσεις.
KYC sandbox: «επαληθευμένη» αποτυχημένη «αναθεώρηση» απαντήσεων στα υποδείγματα διαβατηρίων.
PSP sandbox: статусы 'εγκεκριμένο' captured 'declined' reversed '.

• Ισολογισμός Stavka→vyplata→sverka
• Σφυρηλάτηση/κενό στρογγυλό
• Ιδιαιτερότητα κατά την εκ νέου προσφορά
• Βλάβη του webhook με retrays και επακόλουθη απενεργοποίηση
• 429 και σωστό 'Retry-After'
• 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, πάροχοι, ανάλυση geo/νόμισμα.
Εξαγωγή: S3/SFTP με υπογεγραμμένα δηλωτικά και hashes αρχείων (SHA256).
Ζώνη ώρας αναφοράς: UTC (εκτός εάν ορίζεται διαφορετικά στη σύμβαση).

13) Παρατηρησιμότητα και SLO

SLI: επιτυχία του API ≥ 99. 95% (28d), p95 καθυστέρηση για κρίσιμες μεθόδους, επιτυχία παράδοσης webhook.
Προειδοποιήσεις καύσης (γρήγορες/αργές) σε εσφαλμένο προϋπολογισμό.
Συσχέτιση ίχνους: 'trace _ id' σε απαντήσεις/κούτσουρα, τρυπάνι σε ίχνη.
Σελίδα κατάστασης: Edge, Wallet, Bets, Webhooks, PSP, στοιχεία KYC.

14) Ασφάλεια και συμμόρφωση

ελαχιστοποίηση PII· Τα PAN/μυστικά απαγορεύονται σε αρχεία καταγραφής/webhooks.
Μυστική διαχείριση και εναλλαγή κλειδιού.
RG (υπεύθυνα τυχερά παιχνίδια): οι σημαίες αυτοαποκλεισμού/περιορισμού πρέπει να οδηγούν σε αυτόματη άρνηση στοιχημάτων/πληρωμών.
AML/KYC: «kyc» events. επικαιροποιημένο ',' aml. η καταχώριση "διατίθεται με συνδρομή· λαμβάνει αποφάσεις στο σύστημά σας ή μέσω της ενότητάς μας.
GDPR/DSAR: καταληκτικά σημεία για την αποστολή/διαγραφή προσωπικών δεδομένων του παίκτη για νομικά αιτήματα.
Οι mTLS και HSTS ενεργοποιούνται εξ ορισμού στο περιβάλλον παραγωγής.

15) Επιδόσεις και ποσοστώσεις

• 50 (διάρρηξη 100)
• Παράλληλα webhooks: 10
• Μέγεθος σώματος: ≤ 256 KB (εκδηλώσεις τυχερών παιχνιδιών), ≤ 64 KB (πορτοφόλι)

Ζητήστε αναβάθμιση του σχεδίου μέσω του διαχειριστή λογαριασμού, προσδιορίζοντας την πρόβλεψη/τους όγκους της RPS.

16) Διαχείριση αλλαγών και αποδεσμεύσεων

Αλλαγή παραθύρων: προγραμματισμένες εργασίες - σύμφωνα με το χρονοδιάγραμμα, κοινοποίηση ≥ 5 εργάσιμες ημέρες.
Μετάβαση στην έκδοση: διπλή γραφή/διπλή ανάγνωση κατά τη διάρκεια της μεταβατικής περιόδου.
Δοκιμές σύμβασης CI: σχήμα JSON, απαιτούμενα πεδία, σταθερό 'error _ code'.
Κανάριος: σταδιακή συμπερίληψη της κυκλοφορίας για νέα χαρακτηριστικά.

17) Πιστοποίηση ενσωμάτωσης (Κατάλογος ελέγχου)

• Καταχώριση/κενό προσφοράς/πληρωμής
• Ευεξία σε όλα τα τελικά σημεία
• Διόρθωση 429/5xx + εφεδρική επεξεργασία

Επαλήθευση υπογραφής Webhook, X-GH-Event-Id

• Συμφωνία ισορροπίας μετά από σειρά γεγονότων (νίκη/απώλεια)
• Οι εκθέσεις συμφιλίωσης συμφωνούν με τα δεδομένα σας

• Υλοποιούνται υποχωρήσεις Webhook

Timeouts πελατών ≤ 10c, συνολική προσπάθεια ≤ 30c

• Διακόπτης κυκλώματος σε εξαρτήσεις

• Αποθήκευση μυστικών στον μυστικό διαχειριστή
• Έκδοση 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 Αποτυχία webhook ακολουθούμενη από επιτυχία

1. Ο διακομιστής σας δεν είναι διαθέσιμος → 5xx → backoff retro.
2. Μετά την ανάκτηση - πάρτε το ίδιο «X-GH-Event-Id» → υποχρεούνται να αγνοούν τα αντίγραφα.

18. 3 Μερική υποβάθμιση του παρόχου

Θα επιστρέψουμε 503. επαναλάβετε με backoff.
Με μεγάλη υποβάθμιση - διακοπή της σήμανσης του παρόχου και συμπεριλαμβανομένης της έξυπνης δρομολόγησης (εάν περιλαμβάνεται στη σύμβαση).

19) DevEx και υποστήριξη

Πύλη: κλειδιά, χρήση, webhooks, ημερολόγια παράδοσης, ταμπλό SLO, αναφορές εξαγωγών.
Επανάληψη Webhooks: ανακατανομή ανά σειρά ημερομηνιών/ταυτότητα.
Περιστατικά: αυτόματη δημιουργία εισιτηρίου, αίθουσα πολέμου, μεταθανάτια ≤ 48 ώρες σε SEV-1.
Επικοινωνίες: # partners-status channel/mail on-call 24 × 7 (Enterprise).

20) Σχέδιο επιβίβασης (2-4 εβδομάδες)

1. Εβδομάδα 1: έκδοση κλειδιού, σύνδεση με αμμοκιβώτιο, βασικά σενάρια (ποντάρισμα/πληρωμή/πορτοφόλι).
2. Εβδομάδα 2: Webhooks and Reconcilations, RG/KYC Flags, Load Tests, 429/5xx Συμπεριφορά.
3. Εβδομάδα 3: υποβολή εκθέσεων (συμφιλίωση, ανεβάσεις), ασφάλεια (υπογραφές, μυστικά), δοκιμές συμβάσεων.
4. Εβδομάδα 4: πιστοποίηση, συμπερίληψη καναρινιών στις πωλήσεις, παρακολούθηση, πίνακας επαφής.

21) Mini-FAQ

Μπορώ να έχω gRPC

Ναι, κατόπιν αιτήματος· Η απεικόνιση κωδικών σφάλματος HTTP παρέχεται στις προδιαγραφές.

Πώς να πάρετε ρετρό δεδομένα

Μέσω εκθέσεων «συμφιλίωσης» (από/σε ημερομηνίες) ή αποστολής S3/SFTP.

Πώς μπορώ να άρω τα όριά μου

Μέσω της πύλης/διαχειριστή λογαριασμού που υποδεικνύει την προβλεπόμενη RPS/ανταγωνιστικότητα.

Ποια θεωρείται η πηγή της αλήθειας της ισορροπίας

Ημερολόγιο συναλλαγών πορτοφολιών GambleHub + ημερήσια συμφωνία.

Σύνολο

Η ενσωμάτωση με το GambleHub βασίζεται σε μια σαφή σύμβαση: σταθερά API και συστήματα, υπογεγραμμένα webhooks, ταυτότητα και retrays, διαφανή όρια και υποβολή εκθέσεων, καθώς και απαιτήσεις ασφάλειας και συμμόρφωσης. Ακολουθώντας αυτόν τον οδηγό και τους καταλόγους πιστοποίησης, θα φτάσετε γρήγορα στην αγορά, παρέχοντας αξιόπιστες ταμειακές ροές και συνεπείς εκθέσεις χωρίς ασυμφωνίες.