Come funziona un'API di feed quote, dallo snapshot all'esito

Una schermata di scommesse sembra statica: un elenco di partite, una colonna di quote. Sotto, un feed quote è un flusso di migliaia di piccoli cambiamenti, e il compito dell’operatore è applicarli tutti nell’ordine giusto. Questa guida ripercorre quel flusso dalla prima richiesta alla scommessa liquidata.

1. Il modello dati

Quasi tutti i feed usano la stessa gerarchia:

• Sport: calcio, tennis, esports.
• Torneo o campionato: Premier League, ATP Tokyo, League of Legends Worlds.
• Evento: una partita, con orario d’inizio e partecipanti.
• Mercato: una domanda sull’evento, come 1X2, over/under 2,5 gol o handicap sulla mappa.
• Esito: una risposta, con una quota e uno stato (attivo, sospeso, liquidato).

Ogni elemento ha un identificativo stabile. La maggior parte dei bug di integrazione nasce dal trattare i nomi come identificativi: i nomi delle squadre cambiano grafia, gli ID no.

2. Prima lo snapshot, poi i delta

All’avvio il client chiede uno snapshot: lo stato attuale completo. Da quel momento riceve delta, piccoli messaggi che dicono “questa quota si è mossa”, “questo mercato è sospeso”, “questo evento è iniziato”.

I buoni feed numerano i delta. Nocturn Sport, ad esempio, descrive il proprio feed come uno snapshot completo più delta con versione. Se il client ha la versione N e riceve la N+2, sa che un messaggio è andato perso e ricarica invece di mostrare una quota superata. I feed senza versioni costringono il client a indovinare, ed è indovinando che i book finiscono per offrire le quote di ieri.

3. Push e pull

Il calcio live può cambiare quota più volte al minuto, quindi i feed live di solito inviano i messaggi in push su una connessione persistente. Le quote pre-match si muovono abbastanza lentamente da rendere spesso sufficiente un pull via HTTP ogni pochi secondi. Molti operatori usano entrambi: pull per il palinsesto pre-match, push per il live.

4. Sospensioni

Una sospensione è il feed che dice “non accettare scommesse su questo adesso”. Tra i fattori scatenanti ci sono un gol, un rigore, un break, la fine di una mappa o la perdita della fonte dati da parte del fornitore. Il client deve applicare le sospensioni più rapidamente di qualsiasi altra cosa; una quota accettata nei secondi successivi a un gol è il modo classico di perdere denaro.

Anche i mercati pre-match chiudono prima del calcio d’inizio. Nocturn Sport, ad esempio, li chiude un minuto prima dell’inizio.

5. Piazzare la scommessa

Se l’API va oltre la pubblicazione delle quote, il piazzamento segue uno schema:

1. Il client invia la selezione, la quota mostrata e la puntata, con un ID richiesta univoco.
2. Il server verifica che la quota sia ancora valida e il mercato aperto.
3. Accetta, rifiuta o propone una nuova quota.
4. Se la rete cade, il client reinvia con lo stesso ID richiesta, e il server restituisce la risposta originale invece di creare una seconda scommessa.

Quest’ultimo passaggio, l’idempotenza, protegge sia il saldo del giocatore sia i conti dell’operatore.

6. Liquidazione

Quando l’evento finisce, il feed pubblica i risultati per esito: vinto, perso, annullato, oppure mezzo vinto e mezzo perso sulle linee divise come gli handicap asiatici. La piattaforma liquida ogni scommessa su questa base. Le correzioni capitano: un risultato può essere modificato dopo una revisione, quindi il processo di liquidazione deve poter riliquidare in modo pulito.

7. Cosa testare prima di andare live

• Interrompere la connessione a metà partita e verificare il recupero.
• Riprodurre un delta fuori ordine e verificare che il client se ne accorga.
• Piazzare due volte la stessa scommessa con un solo ID richiesta.
• Liquidare una multipla in cui una selezione è annullata.

Un feed che supera questi quattro test è pronto per un sabato pomeriggio.