No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
Excel VBA Fixed multiscore speculation Sep 29, 2017
Python login url updated Apr 4, 2017
doc toto proposal request examples Sep 14, 2017
README.md Removed affiliateId from login. Feb 1, 2018

README.md

Veikkaus pelirobotti -referenssitoteutus

Tämän dokumentin tarkoitus on kuvata 'Veikkaus pelirobotti -referenssitoteutuksen' toiminta. Kyseisen robotin tarkoituksena on kuvata ja demonstroida, kuinka automaattiset sovellukset (robotit) voivat käyttää Veikkauksen JSON-rajapintaa toiminnassaan.

Lisenssisopimus Veikkauksen referenssitoteutuksille

Lisenssisopimus

Usein kysyttyjä kysymyksiä

UKK

Veikkauksen JSON-rajapinta

Veikkaus tarjoaa JSON-formaattiin perustuvan REST-rajapinnan, jonka päälle on mahdollista toteuttaa erillaisia Veikkauksen palveluja käyttäviä ohjelmia. Yksi käyttätapaus on robotit, joiden tarkoitus on pelata suuria määriä yksittäisiä pelitapahtumia Veikkauksen järjestelmään.

Alla olevat kappaleet kuvaavat ne osat Veikkauksen JSON-rajapinnasta jotka ovat oleellisia pelaamisen kannalta.

HTTP-otsikkotietueet (Headers)

Header Kuvaus
X-ESA-API-Key: ROBOT Pakollinen otsikkotietue. Automaattisilleohjelmille otsikkotietueen arvon tulee olla ROBOT.
Content-Type: application/json Tietueella määritellään, että Veikkaukselle lähetettävä data tulee JSON-muodossa.
Accept: application/json Tietueella määritellään, että Veikkaukselta tulevan vastauksen odotetaan olevan JSON-muodossa.

Esimerkki: Arvontatietojen haku cURL-ohjelmalla:

$ curl --compressed \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-ESA-API-Key: ROBOT' \
	'https://www.veikkaus.fi/api/v1/sport-games/draws?game-names=MULTISCORE'

Keksit (Cookies)

Jotta automaattiset ohjelmat toimisivat moitteettomasti, tulee niiden selaimen lailla hyväksyä kaikki Veikkauksen palvelun keksit. Veikkauksen palvelun käyttämät keksit saattavat muuttua ilman erillistä ilmoitusta, ja näin onkin tärkeää, että ohjelmat toteutetaan niin, että ne hyväksyvät keksit ilman erillistä määrittelyä.

Referenssi-toteutuksessa käytetään Requests-kirjastoa, joka tarjoaa automaattisen sessiohallinnan. Tämä on erittäin suositeltu tapa, koska näinollen keksien hallinta hoituu automaattisesti.

Mikäli käyttämäsi kirjasto ei tue keksien/session automaattista käsittelyä, tulee sellainen toteuttaa ohjelmaan itse.

Esimerkki: Session luominen python-kielellä käyttäen Requests-kirjastoa

# Vaaditut otsikkotietueet
headers = {
	'Content-type':'application/json',
	'Accept':'application/json',
	'X-ESA-API-Key':'ROBOT'
}

# Sisäänkirjautuminen Veikkauksen tilille, palauttaa sessio-objektin
def login (username, password):
	s = requests.Session()
	login_req = {"type":"STANDARD_LOGIN","login":username,"password":password}
	r = s.post("https://www.veikkaus.fi/api/bff/v1/sessions", data=json.dumps(login_req), headers=headers)
	if r.status_code == 200:
		return s
	else:
		raise Exception("Authentication failed", r.status_code)

# Main-funktio.
# 1. Kirjautuu sisää.
# 2. Hakee monivedon tulevat kohteet (kirjautuneena käyttäjänä)
# 3. Tulostaa vastauksen
def main():
	s = login('esimerkki','salasana')
	r = s.get('https://www.veikkaus.fi/api/v1/sport-games/draws?game-names=MULTISCORE', headers=headers)
	print r.text

Rajapinnan kuvaus

Kirjautuminen

Sisäänkirjautuminen aloittaa asiakkaan session. On tärkeää, että sisäänkirjautuminen tehdään vain kerran, ja kaikki kirjautumisen vaativat pyynnöt tehdään samalla sessiolla.

Pyyntö:

POST /api/bff/v1/sessions

Data:

{"type":"STANDARD_LOGIN","login":"esimerkki","password":"salasana"}

Vastaus:

Tyhjä JSON dokumentti.

Esimerkki: Kirjautuminen sisään cURL-komennolla:

$ curl --compressed \
	-X POST \
	-d '{"type":"STANDARD_LOGIN","login":"esimerkki","password":"salasana"}' \
	-H 'Accept: application/json' \
	-H 'Content-Type: application/json' \
	-H 'X-ESA-API-Key: ROBOT' \
	'https://www.veikkaus.fi/api/bff/v1/sessions'

Esimerkki: Kirjautuminen sisään käyttäen Requests-kirjastoa:

s = requests.Session()
login_req = {"type":"STANDARD_LOGIN","login":"esimerkki","password":"salasana"}
r = s.post("https://www.veikkaus.fi/api/bff/v1/sessions", data=json.dumps(login_req), headers=headers)
if r.status_code == 200:
	print "Loging successful"

Pelikohteiden tiedot

Tällä pyynnöllä voidaan hakea pelikohteiden tiedot urheilupelikohteille, poislukien live-veto.

Pyyntö:

GET /api/v1/sport-games/draws

Parametrit:

Pyynnölle voidaan antaa game-names -parametri, jolla voidaan määritellä vain halutut pelit. Pelien nimet ovat:

MULTISCORE Moniveto
SCORE Tulosveto
SPORT Vakio
WINNER Voittajavedot
PICKTWO Päivän pari
PICKTHREE Päivän trio
PERFECTA Superkaksari
TRIFECTA Supertripla
EBET Pitkäveto
RAVI Moniveikkaus

Vastaus: doc/sport-draws-reply.json

Arvonnat listatataan draws listassa. Lista sisältää oletuksena sekä avoimet (status OPEN) että tulevat kohteet (status FUTURE, vain Vakio). Yksittäisen pelikohteen oleellisimmat tiedot ovat sen numero id kentässä, sekä kuvaus rows listauksessa (vain avoimille pelikohteille). Kohteen kuvauksen formaatti riippuu pelistä.

Kohteen kuvauksessa pelikohde on kuvattu vaihtoehtoisesti joko competitors, outcome tai score listauksilla.

competitor listausta käytetään mm. voittajavedoissa ja moniveikkauksessa, outcome listausta mm. vakiossa ja pitkävedossa, ja score listausta mm. tulosvedossa ja monivedossa.

Esimerkki: Pelikohdetietojen haku monivetokohteille cURL-komennolla:

$ curl --compressed \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-ESA-API-Key: ROBOT' \
	'https://www.veikkaus.fi/api/v1/sport-games/draws?game-names=MULTISCORE'

Pelaaminen

Pelaamiseen liittyen Veikkaus tarjoaa kaksi eri API kutsua. Ns. check-pyynnöllä voidaan tarkistaa merkkitietojen oikeellisuus. Varsinainen pelin jättäminen järjestelmään tapahtuu ilman '/check' osuutta URL:ssa.

Tällä pyynnöllä voidaan pelata urheilupelikohteita, poislukien live-veto.

Pyyntö:

POST /api/v1/sport-games/wagers/check
POST /api/v1/sport-games/wagers

Data:

  • doc/multiscore-wager-request.json
  • doc/sport-wager-request.json

Pelit lähetetään järjestelmään listana, eli useamman pelitapahtuman voi lähettää kerralla. Tämän on myös suositeltu tapa jos tarkoituksena on pelata esimerkiksi useita yksittäisiä rivejä.

Yksittäisessä pyynnössä voi lähettää maksimissaa 25 pelitapahtumaa kerralla.

Vaikka pelit lähetetään yhdessä pyynnössä, hyväksyy järjestelmä ne yksitellen. Tämä tarkoittaa että pelit näkyvät pelitilillä yksittäisinä peliveloituksina, ja järjestelmä saattaa hylätä yksittäisen pelin (esimerkiksi rahojen loppuessa pelitililtä) muiden samassa pyynnössä olevien pelien tullessa hyväksytyksi.

Yksittäisessä pelissä oleelliset kentät ovat drawId ja gameName, sillä nämä määrittelevät mitä pelikohdetta ollaan pelaamassa. drawId on pelikohteen numero id, ja gameName pelin tekninen nimi (esim. SPORT). Pelin panos tulee määritellä 'stake' kenttään, mutta pelin kokonaishinnan(price) voi jättää halutessaan määrittelemättä. Mikäli pelin kokonaishinnan kuitenkin määrittelee, tarkistaa järjestelmä että hinta vastaa pelin oikeaa hintaa. Hinnan ollessa väärä, järjestelmä ei hyväksy pelitapahtumaa.

Pelin merkkitiedot määritellään selections-listaukseen, ja merkkitietojen rakenne riippuu pelistä. Esimerkiksi vakiossa merkkitiedot käytetään rakennetta, jossa valitut merkit määritellään outcomes-listaukseen, kun taas monivedossa käytetään score-elementtejä valittujen tuloksien määrittelyssä.

Pitkävedossa tuetut pelityypit on listattu alla ja esimerkit löytyy doc/ hakemistosta.

Tyyppi Kuvaus
NORMAL Normaali
FREEFORM Vapaa
SINGLE Singlet
DOUBLE Tuplat
TRIO Triplat
QUARTET Neloset
QUINTET Vitoset
SEXTET Kutoset
SEPTET Seiskat
OCTET Kasit
NONET Ysit
ks. peliohjeet Veikkauksen sivuilla.

Vastaus: Vastauksena pelipyyntöön tulee käytännässä lähetetty JSON-data, johon on lisätty seuraavat kentät:

Kenttä Arvo
status ACCEPTED/REJECTED
serialNumber hyväksytyn pelin sarjanumero
price pelin kokonaishinta
transactionTime pelitapahtuman ajankohta

Hylätyille peleille vastauksessa on myös error-elementti, joka kertoo‚ miksi peliä ei hyväksytty. Esimerkki:

"error":{"code":"DRAW_NOT_PLAYABLE"}

Esimerkki: ks. referenssitoteutus, robot.py

Saldokysely

Tällä pyynnöllä voidaan pyytää pelitilin saldo ja tieto mahdollisista kate- varauksista.

Pyyntö:

GET /api/v1/players/self/account

Vastaus: Vastaus sisältää sisältää balances ja CASH elementit, joiden sisällä on sekä pelitilin saldo(balance) sekä mahdollisten katevarausten summa(frozenBalance).

{
	"status":"ACTIVE",
	"balances":{
		"CASH":{
			"type":"CASH",
			"balance":4200,
			"frozenBalance":0,
			"currency":"EUR"
		}
	}
}

Katevaraukset pyritään käsittelemään mahdollisimman pian, mutta pisimmillään niiden käsittely jää seuraavaan päivään (puolen yän jälkeen). Katevaraukseen liittyvät pelitapahtumat eivät näy pelatuissa peleissä, ja kyseisten pelitapahtumien hyväksyntä ei ole varmaa.

Pelitilin saldosta on käytettävissä vain saldon ja katevarausten erotus.

Esimerkki: saldo kysely käyttäen Requests kirjastoa

s = requests.Session()
login_req = {"type":"STANDARD_LOGIN","login":"esimerkki","password":"salasana"}
r = s.post("https://www.veikkaus.fi/api/bff/v1/sessions", data=json.dumps(login_req), headers=headers)
if r.status_code == 200:
	r = s.get("https://www.veikkaus.fi/api/v1/players/self/account", headers=headers)
	j = r.json()
	print "saldo=%.2f, katevaraukset=%.2f" % (j['balances']['CASH']['balance'], j['balances']['CASH']['frozenBalance'])
else:
	print "kirjautuminen epäonnistui: " + r.text

Pelatuimmuusprosentit ja Voitto-osuudet

Veikkaus tarjoaa useille peleille voitto-osuustiedot ladattavina tiedostoina. Tämä onkin suositeltava tapa aina vain kun tiedostojen käyttäminen on mahdollista.

Alla kuvaus pelatuimmuusprosenttien ja voitto-osuuksien kysymiselle Vakio pelille.

Pyyntö:

	GET /api/v1/sport-games/draws/SPORT/{drawId}/popularity
	POST /api/v1/sport-games/draws/SPORT/{drawId}/winshares

Data/Parameterit: Pyynnöissä {drawId} tulee korvata pelikohteen tunnisteella. ks. liite: doc/sport-winshare-request.json

Mikäli voitto-osuustietoja kysellään yli 100 kombinaation kokoiselle järjestelmälle, tulee pyynnöt pilkkoa useampaan osaan. Käytännössä jokaiseen pyyntöön lähetetään sama kombinaatio, mutta pyynnön page-kentällä voidaan määritellä monettako "sivua" ollaan pyytämässä.

Vastaus: ks. liite doc/sport-winshare-response.json. Vastauksen 'hasNext' kenttä kertoo onko seuraava sivu olemassa.

Monivedon kerroinlistat ladattavina tiedostoina:

Moniveto 1 zip
Moniveto 2 zip
Moniveto 3 zip
Moniveto 4 zip
Moniveto 5 zip
Moniveto 6 zip
Moniveto 7 zip
Moniveto 8 zip
Moniveto 9 zip
Moniveto 10 zip
Moniveto 11 zip
Moniveto 12 zip

Toto pelit

Tässä esitetään lyhyesti Toto-pelien kohteiden haku ja pelaaminen.

Rajapinnassa käytettyjä termejä:

  • card - tapahtuma
  • race - lähtö
  • runner - kilpailija
  • pool - pelikohde
  • odds - kertoimet

Pelikohteiden haku

Seuraavilla kyselyillä saa listauksen ravitapahtumista.

GET /api/toto-info/v1/cards/today            # kuluvan päivän tapahtumat
GET /api/toto-info/v1/cards/future           # tulevien päivien tapahtumat
GET /api/toto-info/v1/cards/active           # kuluvan ja tulevien päivien tapahtumat
GET /api/toto-info/v1/cards/date/2017-04-18  # annetun päivän tapahtumat

Tapahtumalistauksesta löytyy myös tietoja bonus ja jackpot -rahoista. Tapahtuman tunnistetta (cardId) käytetään tapahtumaan liittyvien tietojen hakuun.

GET /api/toto-info/v1/card/{cardId}/pools    # tapahtuman kaikki pelikohteet
GET /api/toto-info/v1/card/{cardId}/races    # tapahtuman lähdöt
GET /api/toto-info/v1/race/{raceId}/runners  # lähdön osallistujat
GET /api/toto-info/v1/race/{raceId}/pools    # yhden lähdön pelikohteet

Pelikohteiden kertoimet löytyvät JSON-muodossa kyselyllä

GET /api/toto-info/v1/pool/{poolId}/odds      # pelikohteen kertoimet

T-peleihin pelatut yhdistelmät on saatavilla ainoastaan XML-muodossa. "cards.xml" -tiedostossa luetellaan kuluvan päivän kohteet sekä niihin liittyvät kerroin- ja yhdistelmätiedostot.

GET /api/toto-info/v1/xml/cards.xml
GET /api/toto-info/v1/xml/{n_ddmmyyyy_Rn_txx}.xml.zip

Pelaaminen

Toto-pelien pelaamien etenee neljässä vaiheessa:

  1. Peliehdotuksen lähetys
POST /api/toto-wager/v1/bet/{poolId}

Data: doc/t5-proposal-request.json
Yhdessä peliehdotuksessa voi olla pelejä vain yhteen toto-pelikohteeseen. Useamman pelin yhdistäminen yhteen peliehdotukseen nopeuttaa pelien hyväksyntää merkittävästi. Pelien maksimimäärää ei ole rajoitettu, mutta palvelin voi hylätä erittäin suuria peliehdotuksia tai liian usein toistuvia yrityksiä. Peliehdotus näkyy pelitilillä yhtenä peliveloituksena. Jos pelitilin saldo ei riitä kaikkien peliehdotuksen sisältämien pelien pelaamiseen, hylätään koko peliehdotus kaikkine peleineen.

  1. Peliehdotuksen tarkastuksen odottelu
GET /api/toto-wager/bet/{proposalId}
  • 200 - peliehdotuksen tarkastus kesken
  • 201 - peliehdotus tarkastettu ja tallennettu (doc/t5-proposal-response.json)
  1. Peliehdotuksen pelaaminen
PUT /api/toto-wager/bet/{proposalId}

Vaiheessa 1 tarkastettu peliehdotus on tallennettu palvelimelle ja säilyy siellä korkeintaan 10 minuuttia. Jos vaihetta 3 ei aloiteta tässä ajassa, on pelaaminen aloitettava uudestaan vaiheesta 1. Useamman peliehdotuksen pelaaminen rinnakkain yhdeltä pelitililtä ei nopeuta toto-pelien hyväksyntää.

  1. Pelien hyväksymisen odottelu
GET /api/toto-wager/ticket/{ticketId}
  • 200 - pelien hyväksyminen kesken, vastauksesta ilmenee kuinka pelaaminen on edennyt
  • 201 - pelit pelattu

Toto pelien tuotenimet

VOI Toto: Voittaja
SIJ Toto: Sija
VS Toto: Voittaja+Sija
KAK Toto: Kaksari
KPR Toto: Kaksari ristiin
EKS Toto: Eksakta
EKR Toto: Eksakta ristiin
SPA Toto: Sijapari
SPR Toto: Sijapari ristiin
TRO Toto: Troikka
TRR Toto: Troikka ristiin
DUO Toto: Päivän Duo
T4 Toto: Toto4
T5 Toto: Toto5
T54 Toto: Toto54
T6 Toto: Toto6
T64 Toto: Toto64
T65 Toto: Toto65
T7 Toto: Toto7
T75 Toto: Toto75
T76 Toto: Toto76
T8 Toto: Toto8
T86 Toto: Toto86
T87 Toto: Toto87

Muuta

Datan pakkaus

Veikkauksen palvelu pyrkii palauttamaan datan pakattuna aina, kun se on mahdollista. Tästä syystä palvelun käyttämistä helpottaa mikäli käytössä on kirjasto, joka osaa purkaa gzip pakatut vastaukset automaattisesti. Esimerkiksi cURL-ohjelmalla tämä onnistuu antamalla --compressed optio ohjelmalle.

Esimerkeissä käytetty Requests-kirjasto käsittelee pakatun datan automaattisesti.

Tieto siitä, onko vastaus pakattu vai ei, löytyy vastauksen HTTP otsikkotietueista:

	Content-Encoding: gzip

Suorituskyky

Mikäli automaattiset ohjelmat tukevat moniajoa/säikeistystä, tulee rinnakkain ajettavien prosessien määrä rajoittaa maksimissaan viiteen. Tämän tulisi taata riittävän tehokas pyyntöjen käsittely, vaikka pelattavia pelejä olisi erittäin paljon. Eikä yksittäinen ohjelma näin ollen käytä kohtuuttomasti resursseja.

Kuten edellä on mainittu, tulee ohjelma hyväksyä kaikki palvelun tarjoamat keksit. Tämä on oleellista myös ohjelman suorituskyvyn kannalta.

Useamman pelipyynnön yhdistäminen yksittäiseen pyyntöön parantaa pelien hyväksyntää huomattavasti. Huomio kuitenkin, että yksittäisessä pyynnössä voi olla kerrallaan maksimissaan 25 pelitapahtumaa.