BetBalancer Betting Platform API v2.4

Il documento contiene le specifiche tecniche d’integrazione delle api betting in modalità iframe del software di gioco di BetBalancer.

Il sistema si basa su una serie di chiamate HTTP che forniscono un output formattato in JSON.

Ogni richiesta viene autenticata in modo stateless mediante un hash di sicurezza che viene inviato con la stessa usando un sistema di chiave pubblica e privata.

Struttura di una richiesta

Ogni richiesta http viene strutturata con due set di dati:

• Dati GET (via URL): riguardano le informazioni necessarie alla validazione della richiesta.
• Dati POST (form urlencoded): dati specifici per il metodo invocato.

Endpoint

https://..betbalancer-service-host../api/webservice/

Parametri GET spetiti via URL

es.: /api/webservice/?public=test&op=users.auth&time=1537871253&hmac=af091…

Calcolo dell’hash hmac

Per la generazione dell’hash è necessario disporre della chiave privata fornita in coppia quella pubblica. Tale informazione è quello che garantisce la sicurezza della richiesta e deve pertanto essere archiviata in modo sicuro.

L’hash hmac viene calcolato con l’algoritmo sha256 a cui vanno forniti in ingresso i parametri op, time e il payload POST della richiesta e utilizzando come chiave quella fornita.

Queste informazioni vanno concatenate tra loro come stringa senza alcun carattere separatore. Lo pseudocodice rappresentativo della codifica è il seguente:

hmac = HMAC.SHA256( 

     op + time + postdata, 

      privatekey 

)

Importante: l’hash deve essere fornito come rappresentazione esadecimale lowercase.

Struttura di una risposta

Tutte le risposte del servizio arrivano in forma di stringa JSON contenente i parametri:

Metodi Webservice

POST users.auth

INPUT

Questo metodo si occupa della creazione di una sessione utente sul servizio. Se l’utente non esiste sarà creato automaticamente. Se la struttura a cui appartiene l’utente non esiste sarà creata automaticamente.

NB: Una volta creato un utente e uno shop, i loro dati non potranno essere modificati. In assenza di shopid e shopname, l’utente sarà creato sotto lo shop di default e non sarà possibile spostarlo al di sotto di un altro shop.

I dati POST accettati dalla richiesta sono i seguenti:

OUTPUT

I dati forniti in risposta da questo metodo sono i seguenti:

POST users.logout

INPUT

Questo metodo si occupa di invalidare uno specifico token, forzando in questo modo il logout dell’utente a cui è associato.

I dati POST della richiesta sono tutti obbligatori e sono i seguenti:

OUTPUT

Il nodo “data” di questo metodo sarà sempre null. Per verificarne l’esito si deve fare unicamente riferimento al valore del parametro status

POST shop.create

INPUT

Permette di creare una struttura Shop sotto cui poter iscrivere gli utenti.

I dati POST accettati dalla richiesta sono i seguenti:

Nota: per poter avere utenti di valuta differente sul servizio bisogna creare degli shop appositi con quella precisa valuta sotto cui iscrivere gli utenti.

OUTPUT

Il nodo “data” di questo metodo sarà sempre null. Per verificarne l’esito si deve fare unicamente riferimento al valore del parametro status

POST ticket.cancel

INPUT

Permette di annullare un ticket entro 3 minuti dal suo piazzamento.

I dati POST accettati dalla richiesta sono i seguenti:

OUTPUT

Il nodo “data” di questo metodo sarà sempre null. Per verificarne l’esito si deve fare unicamente riferimento al valore del parametro status

POST ticket.place

INPUT

Permette di verificare se il ticket non supera i limiti configurati e può essere giocato regolarmente.

I dati POST accettati dalla richiesta sono i seguenti:

Struttura di esempio di ticketbody

[ 

  { 

     “id”:”12345678-123-1″, 

     “event”: { 

        “name”:”Roma – Lazio”, 

        “date”:”2020-03-05T19:00:00.000Z”, 

        “sport”:”Calcio”, 

        “category”:”Italia”, 

        “tournament”:”Serie A”, 

        “eventid”:12345678, 

        “sportid”:123, 

        “categoryid”:123, 

        “tournamentid”:123 

  }, 

 “outcome”: { 

    “name”:”1″, 

    “market”:”1X2″, 

    “result”:”Match”, 

    “odd”:”4.37″, 

    “rule”:”1-20″, 

    “type”:”P”, 

    “fixed”:false, 

    “marketid”:123, 

    “outcomeid”:1, 

    “gamephase”: “1st Half”, 

    “gametimer”: “65”, 

    “gamescore”: “1-1” 

  } 

}, //… 

]

Struttura di esempio di ticketsystem

{ 

   “combinations”:[ 

      { 

         “type”:1, 

         “count”:3, 

         “import”:3, 

         “fullOdd”:13.32, 

         “bonus”:false, 

          “max_win”:”39.96″ 

}, { 

         “type”:2, 

         “count”:3, 

         “import”:3, 

         “fullOdd”:43.2564, 

         “bonus”:false, 

         “max_win”:”129.77″ 

 }, { 

        “type”:3, 

        “count”:1, 

        “import”:3, 

        “fullOdd”:40.323008, 

        “bonus”:false, 

        “Max_win”:”120.97″

      }, //… 

   ] 

}

Codici Rappresentanti la tipologia di ticket (tickettype)

OUTPUT

I dati forniti in risposta da questo metodo sono i seguenti:

Codici di esito dell’operazione

Caricamento Interfaccia e Autenticazione Utente

Endpoint

https://..betbalancer-service-host../api/auth/{token}/{lang}/{page}?public={publickey}

Descrizione

Il caricamento dell’interfaccia e l’autenticazione dell’utente al servizio avvengono tramite una url che va fatta aprire via IFRAME all’interno del sito del partner.

Bisogna passsare alla url il token di sessione ricevuto dalla chiamata al metodo users.auth e il codice a due lettere della lingua scelta per la visualizzazione (es: it, en, fr etc..)

Callback URL: Piazzamento Ticket

Il partner dovrà fornire una URL di Callback su cui riceverà in tempo reale i ticket giocati dagli utenti e dovrà fornire una risposta nel body che servirà a stabilire il rifiuto o l’accettazione del ticket. L’output di risposta deve essere formattato in JSON.

La sicurezza del messaggio viene garantita tramite la firma con hash hmac inviato seguendo le stesse modalità descritte nei capitoli 1-2 e 1-3, con op valorizzato sempre come “cbplace”. E’ onere del partner assicurarsi della validità della firma digitale prima di eseguire l’operazione di piazzamento.

I seguenti parametri saranno passati alla url di callback col metodo HTTPS POST come dati form/urlencoded:

Struttura di esempio di ticketbody

[ 

 { 

     “id”:”12345678-123-1″, 

     “event”: { 

         “name”:”Roma – Lazio”, 

         “date”:”2020-03-05T19:00:00.000Z”, 

         “sport”:”Calcio”, 

         “category”:”Italia”, 

         “tournament”:”Serie A”, 

         “qbetcode”:”1544″, 

         “eventid”:12345678, 

         “sportid”:123, 

         “categoryid”:123, 

         “tournamentid”:123 

    }, 

      “outcome”: { 

          “name”:”1″, 

          “market”:”1X2″, 

          “result”:”Match”, 

          “odd”:”4.37″, 

          “rule”:”1-20″, 

          “type”:”P”, 

          “fixed”:false, 

          “spread”:null, 

          “marketid”:123, 

          “outcomeid”:1 

     } 

  }, //… 

]

Struttura di esempio di ticketsystem

{ 

    “combinations”:[ 

       { 

          “type”:1, 

          “count”:3, 

          “import”:3, 

          “fullOdd”:13.32, 

          “bonus”:false, 

          “max_win”:”39.96″ 

       }, {  

          “type”:2, 

          “count”:3, 

          “import”:3, 

          “fullOdd”:43.2564, 

          “bonus”:false, 

          “max_win”:”129.77″ 

       }, { 

          “type”:3, 

          “count”:1, 

          “import”:3, 

          “fullOdd”:40.323008, 

          “bonus”:false, 

          “max_win”:”120.97″ 

       }, //… 

    ] 

}

• type rappresenta la tipologia di combinazione:
  • 1 → Singole
  • 2 → Doppie
  • 3 → Triple etc..
• count rappresenta il numero di sviluppi per la data combinazione
• import rappresenta l’importo giocato per singolo sviluppo della combinazione
• fullOdd rappresenta la quota della combinazione dal valore più alto

Struttura di risposta

La risposta della callback URL deve essere formattata in json ed è composta da:

esempio:

{“status”:”A”, “method”:”cbplace”, “msg”:”Scommessa Accettata”}

Codici Rappresentanti la tipologia di ticket (tickettype)

Codici Status di risposta

Callback URL: Refertazione Ticket

Ad intervalli regolari il servizio contatterà un endpoint fornita dal partner a cui saranno inviati i referti dei ticket giocati.

La sicurezza del messaggio viene garantita tramite la firma con hash hmac inviato seguendo le stesse modalità descritte nei capitoli 1-2 e 1-3, con op valorizzato sempre come “cbdefine”.

E’ onere del partner assicurarsi della validità della firma digitale prima di eseguire l’operazione di definizione dei tickets.

N.B. Nel messaggio di comunicazione dei referti dei ticket, si potrà ricevere il referto di più giocate contemporaneamente fino ad un massimo di 200 giocate per messaggio .

I seguenti parametri saranno passati alla url di callback col metodo HTTPS POST come dati form/urlencoded:

Struttura di risposta

Non è prevista nessuna risposta formattata per questa chiamata: se la richiesta termina con codice di stato http 200 viene considerata riuscita, altrimenti viene tentato il reinvio dell’ultimo pacchetto di refertazione fino alla sua riuscita.

Struttura di esempio di ticketstatus

[ 

     { 

        “username”:”johnsmith”, 

        “ticketId”:1234, 

        “ticketCurrency”:”USD”, 

        “ticketBet”:10.00, 

        “ticketWin”:43.70, 

        “ticketOdd”:4.37, 

        “cashoutTime”:false, 

        “status”:”W”, 

        “outcomes”: [ 

           { 

               “id”:”1234-123-1″, 

               “status”:”W”, 

               “odds”:2.18, 

               “cashout”:false, 

               “results”: { 

                    “HT”:”1:0″, 

                    “FT”:”2:0″ 

               } 

           }, //… 

        ] 

     }, //… 

]

Codici Status di un ticket

Codici Status di un outcome

Results di un outcome

Il nodo “results” di ogni outcomes contiene il risultato dell’evento di riferimento. Il suo invio non viene garantito in quanto subordinato alle informazioni fornite dal provider e nel caso verrà inviato come valore NULL nel momento in cui il dato non sia disponibile.

Qualora disponibile il dato sarà spedito come nell’esempio in precedenza.

Nota: TUTTI i parametri che possono apparire nel nodo results sono facoltativi, pertanto prima di utilizzare un dato valore bisogna sempre accertarsi che sia presente. Al momento vengono serviti solo il Calcio e il Tennis.

Callback URL: Fondi Utente

Metodo Facoltativo. Se implementato permette di stabilire al momento del piazzamento di un ticket se la user dispone del credito necessario per l’operazione velocizzando alcuni controlli e impedendo sul nascere ritardi al rifiuto di ticket dovuti all’insufficienza di fondi utente.

La sicurezza del messaggio viene garantita tramite la firma con hash hmac inviato seguendo le stesse modalità descritte nei capitoli 1-2 e 1-3, con op valorizzato sempre come “cbfunds”. E’ onere del partner assicurarsi della validità della firma digitale prima di eseguire l’operazione di piazzamento.

I seguenti parametri saranno passati alla url di callback col metodo HTTPS POST come dati form/urlencoded:

Struttura di risposta

La risposta della callback URL deve essere formattata in json ed è composta da:

esempio:

{“status”:”M”, “method”:”cbfunds”, “msg”:null}

Codici Status di risposta