Lippu- ja maksujärjestelmän toiminnallinen määrittely Tuote- ja tariffirajapinta Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy
Sisällysluettelo 1 Osajärjestelmän kuvaus... 1 2 Prosessit... 2 2.1 Tuote-ja tariffirajapinnan liittyminen kokonaisjärjestelmään... 2 2.2 Osajärjestelmän määritelmät... 2 2.2.1 Liikennöitsijän järjestelmä... 2 2.2.2 Urlit... 2 2.3 Toimintolista... 3 2.4 Korttien sulkulista... 5 2.5 Yleiset ohjaukset... 6 2.5.1 Sulkulistastatus ja ohjaus... 6 2.5.2 Päivätyypit... 6 2.5.3 Taksa kalenteri... 7 2.5.4 Kouluryhmä kalenteri... 7 2.5.5 Koulu/Koulukalenteri (lisätty versiossa 1.4)... 7 2.5.6 Asiakasryhmät... 7 2.5.7 Asiakasryhmien ikärajat... 7 2.5.8 Arvon lataus... 8 2.5.9 ALV Ryhmät... 8 2.5.9.1 ALV Tekstit... 8 2.6 Paperiliput... 8 2.6.1 Paperiliput... 9 2.6.1.1 Paperilippujen vaihtoajat... 9 2.6.1.2 Paperilippujen tekstit... 9 2.7 Korttituotteet... 9 2.7.1 Yleiset korttiparametrit... 10 2.7.2 Lipputuotteet korteille... 10 2.7.2.1 Lipputuotteiden vaihtoajat... 11 2.7.2.2 Lipputuotteiden voimassa päivätyypeittäin... 11 2.7.3 Kausilipun ohjaustiedot... 12 2.7.4 Arvolipun ohjaustiedot... 12 2.8 Hinnoittelu... 12 2.8.1 Paperilipun hinnoittelu... 13 2.8.1.1 Vyöhykkeen hinnoittelu... 13 2.8.2 Kausituotteiden hinnoittelu... 14 2.8.3 Arvolipun hinnoittelu... 14 2.9 Kertakorttilippu ja sen hinnoittelu... 14 2.10 Ryhmälippu... 15 3 Käyttötapaukset ja toimijat... 16 4 Käyttöoikeudet ja käyttäjähallinta... 16 5 Käsitemalli... 16 6 Integraatiot... 16 6.1 Liikennöitsijäjärjestelmät... 16 6.2 Tarkastajajärjestelmät... 16 Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy
7 UI demo/proto... 16 8 Muutoshistoria... 17 Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy
Tuote- ja tariffirajapinnan kuvaus 1 Osajärjestelmän kuvaus Waltti määrittelyiden mukainen matka- ja kertakorttisovelluksien käsittely on teknisesti ja sopimuksellisesti mahdollista kaikkien laite- ja ohjelmistovalmistajien toimesta. Määrittelyt ovat avoimet ja toimittajariippumattomat. Waltti ottaa käyttöön avoimen tiedonsiirtorajapinnan, joka mahdollistaa kaikkien laitetoimittajien toteuttaa Waltti korttien käsittelyssä tarvittavien ohjaustietojen noutamisen Waltti palvelimelta. Tiedonsiirtorajapinta toteutetaan Restful Web Servicenä. Ohjaustiedot on jaettu kokonaisuuksiin, joita varten rajapinta tarjoaa omat urlit. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 1(18)
2 Prosessit 2.1 Tuote-ja tariffirajapinnan liittyminen kokonaisjärjestelmään 2.2 Osajärjestelmän määritelmät 2.2.1 Liikennöitsijän järjestelmä Liikennöitsijän tai palveluntuottajan järjestelmän on kyettävä hakemaan tarvittavat ohjaustiedot ja kieltolistat Waltti järjestelmästä sekä välittämään tiedot ajoneuvolaitteille ja/tai myyntilaitteille. Järjestelmän tulee sisältää ominaisuudet, joiden avulla määriteltynä ajankohtana voimaan tulevat ohjaustiedot voidaan välittää etukäteen ajoneuvolaitteille. 2.2.2 Urlit Urlit palauttavat datan application/xml muodossa. Jokaista kokonaisuutta varten on xml-skeemat. Uusi ohjaustieto korvaa aina vanhan kokonaisuudessaan voimaantulohetkestä alkaen. Poikkeuksen tekee tariffitiedot, joita voi olla myös sisäkkäin voimassaolevia versioita. Urlit ja skeemat: Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 2(18)
Parametristo URI Vastauksen skeema Toimintolista /actionlist/{companyid} actionlist.xsd Sulkulista /blacklist/{companyid} blacklist.xsd Yleiset ohjaustiedot /commonparams/{companyid}/{authorityid} commonparams.xsd Paperiliput /singletickets/{companyid}/{authorityid} singleticket.xsd Korttituotteet /cardparams/{companyid}/{authorityid} cardparams.xsd Hinnoittelu /fareparams/{companyid}/{authorityid} fareparams.xsd Matkailijakortit /travelcards/{companyid}/{authorityid} travelcard.xsd Muut liput /othertickets/{companyid}/{authorityid} otherticket.xsd 2.3 Toimintolista Liikennöitsijällä on velvollisuus hakea toimintolista kerran vuorokaudessa verkkopalvelusta ja jakaa tiedot laitteisiin joissa matkakortteja käytetään. Toimintolista voidaan hakea kokonaisuudessaan tai rajata TVVkohtaisesti ja toiminnon tyypin mukaan. Toimintolistalla on vain aktiiviset toiminnot, aktivoidut poistetaan listalta tapahtumien käsittelyn yhteydessä järjestelmän toimesta. Metodi URI Vastauksen skeema GET /actionlist/{companyid}?{authorityid}&{type} actionlist.xsd Parametrit Parametri Tyyppi Selite companyid short Organisaation tunnus, LMJ = 154 authorityid short TVV tunnus (valinnainen), jos halutaan hakea vain tietyn TVV:n toimintolistat type string Toiminnon tyyppi (valinnainen): CUSTOMER_DATA_UPDATE (ei käytössä) PERIOD_TICKET_LOADING STORED_VALUE_LOADING Vastaus: actionlist paramheader paramheadertype 1 Otsikkotiedot actionlistitem actionlistitemtype 0..* Toimintolistan rivi paramheadertype companyid xs:short 1 Yhtiön tunnus LMJ authorityid xs:short 0..1 TVV tunnus generated xs:datetime 1 Aikaleima Parametrit muodostettu actionlistitemtype actionlistidentifier xs:string 1 Tunniste GUID actionlistcounter xs:unsignedint 1 Juoksunumero Verrataan kortin laskuriin TVV xs:unsignedint 1 TVV cardnumber xs:string 1 Kortin numero Ilman tarkistetta Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 3(18)
actionlisttype xs:string 1 Toiminnon tyyppi CUSTOMER_DATA_UPDATE (ei käytössä) PERIOD_TICKET_LOADING STORED_VALUE_LOADING creationdate xs:datetime 1 Luontipäivä actionlistprocessingresult xs:string 1 Tila ACTIVE (vain aktiiviset välitetään rajapinnassa) priceinformation priceinformationtype 1 Hintatiedot periodticket periodtickettype 0..1 Kauden lataus storedvalue xs:unsignedint 0..1 Arvon lataus cardholderinformation cardholderinformationtype 0..1 Asiakastiedot (Ei käytössä) cardholdercompany cardholdercompanytype 0..1 Organisaatiotiedot (Ei käytössä) priceinformationtype totalprice xs:unsignedint 1 Kokonaishinta vatpercentage xs:unsignedint 1 Alv-prosentti vatvalue xs:unsignedint 1 Alv periodtickettype ticketcode xs:unsignedint 1 Tuotteen tunnus validityzone xs:string 1 Vyöhyke duration xs:unsignedint 0..1 Kauden pituus startdate xs:datetime 1 Voimassaolo alkaa 1997-01-01 = ei asetettu productcodetype xs:unsignedint 0..1 Tuotetyypin tunnus 0 kausi 1 joustokausi 2 koululaiset 3 best price TVV xs:unsignedint 0..1 TVV companyorsocietyid xs:string 0..1 Yrityksen/yhteisö esim. koulun tunnus invoicable xs:unsignedint 0..1 Laskutettava tuote 0 Ei, 1 Kyllä invoicableorganization xs:unsignedint 0..1 Laskutettava organisaatio dailytrips xs:unsignedint 0..1 Matkoja päivässä remainingdaysortrips xs:unsignedint 0..1 Jäljellä olevat päivät/matkat Joustokaudelle ja koulutuotteelle validfromtime xs:time 0..1 Voimassa alkaen validtotime xs:time 0..1 Voimassa asti defaultprice xs:int 0..1 Oletushinta laskutettaville tuotteille cardholderinformationtype Ei käytössä personalized xs:unsignedint 1 Personoitu 0 Ei, 1 Kyllä holderid xs:unsignedint 1 Haltijatiedot 0 Ei, 1 Kyllä companyid xs:unsignedint 1 Organisaatiotiedot 0 Ei, 1 Kyllä domicile xs:string 1 Kuntalaisuus JHS110 mukaisesti domicileexpirydate xs:date 0..1 Kuntalaisuuden päättyminen 1997-01-01 Ei asetettu Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 4(18)
languagecode xs:unsignedint 1 Kielikoodi customerprofile xs:unsignedint 1 Asiakasryhmä customerprofileexpirydate xs:date 1 Päättymispäivä 1997-01-01 Ei asetettu newcustomerprofile xs:unsignedint 1 Uusi asiakasryhmä newcustomerprofilefirstdate xs:date 0..1 Alkamispäivä 1997-01-01 Ei asetettu newcustomerprofileexpirydate xs:date 0..1 Voimassa alkaen 1997-01-01 Ei asetettu defaultarea xs:string 0..1 Oletusmatkustusalue defaulttvv xs:unsignedint 1 Oletus TVV cardholdercompanytype Ei käytössä companyorsocietyid xs:string 1 Organisaation Esim. koulu companydepartmentid xs:string 1 Osasto 2.4 Korttien sulkulista Liikennöitsijällä on velvollisuus hakea sulkulista-tiedosto kerran vuorokaudessa verkkopalvelusta ja jakaa sulkulistatiedot matkakortteja käyttäviin laitteisiin. Metodi URI Vastauksen skeema GET /blacklist/{companyid} blacklist.xsd Parametrit Parametri Tyyppi Selite companyid short Organisaation tunnus, LMJ = 154 Vastaus: blacklist paramheader paramheadertype 1 Otsikkotiedot blacklistitem blacklistitemtype 0..* Sulkulistan rivi blacklistitemtype firstcardnumber xs:string 1 Suljettu kortti tai sarjan alaraja Kortin numero, ilman tarkistetta lastcardnumber xs:string 0..1 Sarjan yläraja Kortin numero, ilman tarkistetta blocklevel xs:byte 1 Sulkutaso Koodiston mukaan blockdate xs:date 1 Sulku päivämäärä Sulkulistalle kirjauspäivämäärä vvvv-kk-pp Sulkulistalla voi olla sekä yksittäisiä kortteja että sarjasulkuja, jolloin tietueella on suljettujen korttien ala- ja ylärajat. Ala- ja ylärajan kortit ovat myös suljettuja. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 5(18)
2.5 Yleiset ohjaukset Metodi URI Vastauksen skeema GET /commonparams/{companyid}/{authorityid} commonparams.xsd Parametrit Parametri Tyyppi Selite companyid short Organisaation tunnus, LMJ = 154 authorityid short TVV tunnus Vastaus: commonparams paramheader paramheadertype 1 Otsikkotiedot blacklistcontrol blacklistcontroltype 0..* Sulkulistastatukset datetype parameterdatetype 0..1 Päivätyypit calendarexddate calendarexddatetype 0..1 Poikkeuspäivät calendarschool calendarschooltype 0..1 Koulukalenterit schoolcalendarmapping schoolcalendarmappingtype 0..1 Koulukalenterien linkitys customergroup customergrouptype 0..1 Asiakasryhmät customergroupage customergroupagetype 0..1 Asiakasryhmien ikärajat valueloading valueloadingtype 0..1 Arvonlataus vatgroup vatgrouptype 0..1 Alv-ryhmät 2.5.1 Sulkulistastatus ja ohjaus blacklistcontroltype blocklevel xs:byte 1 Sulkutaso 1=varastettu 2=kadonnut 3=maksuhäiriö usertext xs:string 0..1 Käyttäjän teksti Kuljettajan rahastuslaitteelle operationctrl xs:string 1 Leimauksen hyväksyntä 0= Leimaus estetty 1= Leimaus hyväksytään 2.5.2 Päivätyypit parameterdatetype type xs:byte 1 Tunnus 1=arkipäivä 2=lauantai 3=sunnuntai 4=erikoispäivä1 5=erikoispäivä2 name xs:string 0..1 Päivätyypin nimi nightstart xs:time 0..1 Yötaksa alkaa nightend xs:time 0..1 Yötaksa päättyy Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 6(18)
2.5.3 Taksa kalenteri calendarexddatetype productownerid xs:short 1 TVV-tunnus calendardate xs:date 1 Päivämäärä type xs:byte 1 Taksan päivätyyppi 1-5 0 = ei vaikutusta kalenteriin 2.5.4 Kouluryhmä kalenteri calendarschooltype productownerid xs:short 1 TVV-tunnus schoolcalendarid xs:short 1 Koulukalenterin tunnus koulukortin ohjauksessa (000=oletus kalenteri) year xs:short 1 Vuosi miltä vuodelta kalenteri alloweddates xs:string 1 Sallitut päivät poterot vuoden päiville alkaen vuoden ensimmäisestä päivästä 0=ei matkustusoikeutta 1=on matkustusoikeus 2.5.5 Koulu/Koulukalenteri (lisätty versiossa 1.4) schoolcalendarmappingtype productownerid xs:short 1 TVV-tunnus schoolid xs:int 1 Koulutunnus schoolcalendarid xs:short 1 Koulukalenterin tunnus 2.5.6 Asiakasryhmät customergrouptype customergroupid xs:byte 1 Asiakasryhmän tunnus muutettu versiossa 1.3 0=ei määritelty 1=aikuinen 2=lapsi 3=nuori 4=seniori 5=opiskelija 6=koululainen name xs:string 0..1 Asiakasryhmän nimi 2.5.7 Asiakasryhmien ikärajat Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 7(18)
customergroupagetype productownerid xs:short 1 Tuotteenomistaja TVV-tunnus customergroupid xs:byte 1 Asiakasryhmän tunnus agemin xs:byte 0..1 Alaikäraja 0=ei alarajaa agemax xs:byte 0..1 Yläikäraja 0=ei ylärajaa 2.5.8 Arvon lataus valueloadingtype productcode xs:short 1 Tuotetunnus minload xs:decimal 0..1 Minimilataus Arvon minimilataus loadstep xs:decimal 0..1 Kerrannainen Latauskerrannainen maxvalue xs:decimal 0..1 Maksimiarvo Suurin sallittu saldo kortilla 2.5.9 ALV Ryhmät vatgrouptype vatgroupid xs:short 1 Alv-ryhmän tunnus vatpercentage xs:decimal 1 Alv-prosentti startdate xs:date 0..1 Uusi alv alkaa alv muutos alkaa newvatpercentage xs:decimal 0..1 Uusi prosentti Tuleva alv-prosentti vattext vattexttype 0..* Tekstit Erikieliset tekstit 2.5.9.1 ALV Tekstit vattexttype languagecode xs:byte 1 Kielikoodi 0=suomi 1=ruotsi 2=englanti vattxt xs:string 1 Alv-teksti Arvonlisäveron kuittiin tulostettava teksti 2.6 Paperiliput Metodi URI Vastauksen skeema GET /singletickets/{companyid}/{authorityid} singleticket.xsd Parametrit Parametri Tyyppi Selite companyid short Organisaation tunnus, LMJ = 154 authorityid short TVV tunnus Vastaus: singleticket Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 8(18)
2.6.1 Paperiliput paramheader paramheadertype 1 Otsikkotiedot paperticket papertickettype 0..* Kertalippu papertickettype productownerid xs:short 1 Tuotteenomistaja TVV ticketcode xs:short 1 Lippulaji Lipun tunnus name xs:string 0..1 Tuotteen nimi customergroup xs:byte 0..1 Asiakasryhmä vatgroup xs:short 0..1 Alv-ryhmä transfer xs:boolean 0..1 Vaihto false=ei vaihtoa, true=vaihto sallittu paperticketchangetime changetimetype 0..* Vaihtoajat Taulukko vaihtoajoista papertickettext papertickettexttype 0..* Tekstit Lippulajien tekstit 2.6.1.1 Paperilippujen vaihtoajat changetimetype fromzone xs:byte 1 Vyöhykkeeltä 1-10 tozone xs:byte 1 Vyöhykkeelle 1-10 changetime xs:short 1 Vaihtoaika Minuutteina 2.6.1.2 Paperilippujen tekstit papertickettexttype languagecode xs:byte 1 Kielikoodi 0=suomi 1=ruotsi 2=englanti readertext xs:string 0..1 Lippulajiteksti, IP reporttext xs:string 0..1 Lippulajiteksti, RAP salestext xs:string 0..1 Lippulajiteksti, MYY 2.7 Korttituotteet Metodi URI Vastauksen skeema GET /cardparams/{companyid}/{authorityid} cardparams.xsd Parametrit Parametri Tyyppi Selite companyid short Organisaation tunnus, LMJ = 154 authorityid short TVV tunnus Vastaus: cardparams paramheader paramheadertype 1 Otsikkotiedot Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 9(18)
cardparamcommon cardparamcommontype 0..1 Yleiset korttiparametrit cardticket cardtickettype 0..1 Lipputuotteet korteille periodcontrol periodcontroltype 0..1 Kausilipun ohjaus valuecontrol valuecontroltype 0..1 Arvolipun ohjaus 2.7.1 Yleiset korttiparametrit cardparamcommontype cardapplicationissuer xs:int 1 Kortin Esim. 924610 liikkeellelaskija transactioncardissuer xs:int 1 Kortin Esim. LMJ = 1 liikkeellelaskija tapahtumissa cardtechage xs:byte 0..1 Etäkortin tekninen Vuosia käyttöikä valueaddtime xs:short 0..1 Arvon käyttöaika Päiviä teknisen iän umpeuduttua valuealertlimit xs:decimal 0..1 Arvon hälytysraja Saldo, euroa jäljellä periodalertlimit xs:short 0..1 Kauden hälytysraja Päiviä jäljellä antipasstime xs:short 0..1 Antipass-aika Aika sekunteina Määrittelee kausikorttien yhteydessä ns. antipass ajan. reusetimelimit xs:short 0..1 Uudelleen käytön aikaraja Aika sekunteina Määrittelee arvolipun oston yhteydessä aikarajan jonka sisällä tehty uudelleenleimaus tulkitaan ryhmälipun ostamiseksi. groupincrease xs:boolean 0..1 Ryhmän kasvatus vaihdon 0= ei ole sallittu 1= sallittu yhteydessä errormsgtime xs:int 0..1 Virheilmoituksen aika sekunteina näyttöaika infoscreendelay xs:int 0..1 Infonäyttöön aika sekunteina siirtymisaika cardprice xs:decimal 0..1 Kortin hinta newcardprice xs:decimal 0..1 Uusi hinta newpricestart xs:date 0..1 Uusi hinta alkaen 2.7.2 Lipputuotteet korteille cardtickettype productownerid xs:short 1 Tuotteen omistaja TVV /Liikennöitsijä ticketcode xs:short 0..1 Lippulaji Lipun tunnus Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 10(18)
2.7.2.1 Lipputuotteiden vaihtoajat name xs:string 0..1 Tuotteen nimi productgroup xs:byte 0..1 Tuoteryhmä 1=kausilippu 2=arvolippu 3=matkailijalippu, kertatuote 5=erikoislippu producttype xs:byte 0..1 Tuotetyyppi 0=kausilippu 1=joustolippu 2=koululaislippu 3=bestpricelippu (4=työmatkalippu) 5=opiskelijalippu muutettu versiossa 1.3 16=arvolippu 17=senior lippu 18=kertatuote 19=ryhmätuote personalized xs:boolean 0..1 Personointi false=haltijakohtainen true=henkilökohtainen vatgroup xs:short 0..1 ALV ryhmä Veroprosentit kerrottu ryhmän tiedoissa loadingallowed xs:boolean 0..1 Lataaminen sallittu true=lataaminen sallittu false=vain käyttö sallittu transfer xs:boolean 0..1 Vaihto false=ei sallittu true=on sallittu cardticketchangetime changetimetype 0..* Vaihtoajat Taulukko vaihtoajoista dailyvalidity dailyvaliditytype 0..* Voimassaoloajat Päivätyypeittäin voimassaoloajat, koskee lähinnä koululaislippuja sekä seniorlippuja changetimetype fromzone xs:byte 0..1 Vyöhykkeeltä 1-10 tozone xs:byte 0..1 Vyöhykkeelle 1-10 changetime xs:short 0..1 Vaihtoaika minuutteina 2.7.2.2 Lipputuotteiden voimassa päivätyypeittäin dailyvaliditytype datetype xs:byte 1 Tunnus 1=arkipäivä 2=lauantai 3=sunnuntai 4=erikoispäivä1 5=erikoispäivä2 starttime1 xs:time 0..1 Voimassa alkaen endtime1 xs:time 0..1 Voimassa asti starttime2 xs:time 0..1 Voimassa alkaen seniorilipulla mahdollista Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 11(18)
endtime2 xs:time 0..1 Voimassa asti kahdet voimassaoloajat 2.7.3 Kausilipun ohjaustiedot periodcontroltype productownerid xs:short 1 Tuotteen omistaja TVV / Liikennöitsijä ticketcode xs:short 0..1 Lippulaji perioddays xs:short 0..1 Voimassa Voimassa vuorokausia Myös joustolipun, opiskelijalipun, työmatkalipun sekä bestprice lipun ohjaus periodyear xs:boolean 0..1 Vuoden voimassa false=ei vuosituote true=voimassa vuoden dayperiod xs:boolean 0..1 Annetun ajan false=ei aikarajoitusta true=aikarajoitus (alkaen asti annetaan myynnin yhteydessä) startdate xs:date 0..1 enddate xs:date 0..1 periodtrip xs:short 0..1 Matkapäivät/Matkojen määrä Joustolipun matkapäivät Työmatkalipun matkojen määrä kaudella valueticket xs:short 0..1 Arvolippu Lippulaji Bestprice lipun käytettävä arvolipun hinnoittelu maxtripday xs:byte 0..1 Maksimi matkat/päivä 0=ei rajoitettu, käytössä koululaislipulla 2.7.4 Arvolipun ohjaustiedot valuecontroltype 2.8 Hinnoittelu productownerid xs:short 1 Tuotteen omistaja TVV / Liikennöitsijä ticketcode xs:short 0..1 Lippulaji valueticket xs:short 0..1 Arvolipun tunnus Voimassaoloajan ulkopuolella käytettävän arvolipun hinnoittelu koskee lähinnä seniorilippua Vastauksessa palautetaan voimassaolevan tariffin tuotteet ja hinnat. Vastaus voi sisältää myös seuraavan voimaanastuvan tariffin tuotteet ja hinnat. Voimassa oleva tariffi tulee tarkistaa tariffituotteen kentistä validstartdatetime ja validenddatetime. Tariffiversio on voimassa olevilla tuotteilla aina sama, joten tapahtumille tariffiversion tunnus voidaan ottaa ensimmäisen tapahtuman yhteydessä, jossa tariffia käytetään. Metodi URI Vastauksen skeema Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 12(18)
GET /fareparams/{companyid}/{authorityid}?{saleschannelcode} fareparams.xsd Parametrit Parametri Tyyppi Selite companyid short Organisaation tunnus, LMJ = 154 authorityid short TVV tunnus saleschannelcode short Myyntikanavan tunnus. Jos tunnusta ei anneta, tai sille ei löydy hinnoittelua, palautetaan voimassaoleva oletustariffi Vastaus: fareparams fareheader fareheadertype 1 paperticketfare paperticketfaretype 0..1 Paperilipun hinnoittelu periodticketfare periodticketfaretype 0..1 Kausituotteiden hinnoittelu valuecardticketprice valuecardticketpricetype 0..1 Arvolipun hinnoittelu fareheadertype companyid xs:short 1 Organisaatio LMJ=154 authorityid xs:short 1 TVV generated xs:datetime 1 Muodostettu saleschannelid xs:short 0..1 Myyntikanavan tunnus 2.8.1 Paperilipun hinnoittelu paperticketfaretype productownerid xs:short 1 Tuotteen omistaja TVV /Liikennöitsijä ticketcode xs:short 1 Lippulaji Lipun tunnus tariffversion xs:short 1 Tariffiversio Palautuu tapahtumassa validstartdatetime xs:datetime 1 Voimassaolon alku validenddatetime xs:datetime 0..1 Voimassaolon loppu customergroup xs:byte 1 Asiakasryhmä 1=aikuinen 2=lapsi 3=nuori paperticketzoneprice zonepricetype 0..* Hinnat vyöhykkeittäin Vyöhykkeeltä vyöhykkeelle 2.8.1.1 Vyöhykkeen hinnoittelu zoneprice fromzone xs:byte 1 Vyöhykkeestä 1-n (maksimi tvv:n tiedoista) tozone xs:byte 1 Vyöhykkeeseen 1-n (maksimi tvv:n Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 13(18)
2.8.2 Kausituotteiden hinnoittelu tiedoista) price xs:decimal 1 Normaali hinta normaalihinta nightprice xs:decimal 0..1 Yöllä veloitettava hinta Arvotuotteella veloitettava hinta tai kausituotteen lisäksi veloitettava hinta. 0=ei yöveloitusta, veloitetaan normaalihinta. periodticketfare productownerid xs:short 1 Tuotteen omistaja TVV / Liikennöitsijä ticketcode xs:short 1 Lippulaji tariffversion xs:short 1 Tariffiversio Palautuu tapahtumassa validstartdatetime xs:datetime 1 Voimassaolon alku validenddatetime xs:datetime 0..1 Voimassaolon loppu customergroup xs:byte 1 Asiakasryhmä 1= aikuinen 2= lapsi 3= nuori 4=seniori 5= opiskelija 6= koululainen cardticketzoneprice zonepricetype 0..* Hinnat vyöhykkeittäin Vyöhykkeeltä vyöhykkeelle 2.8.3 Arvolipun hinnoittelu valuecardticketpricetype productownerid xs:short 1 Tuotteen omistaja TVV / Liikennöitsijä ticketcode xs:short 1 Lippulaji tariffversion xs:short 1 Tariffiversio Palautuu tapahtumassa validstartdatetime xs:datetime 1 Voimassaolon alku validenddatetime xs:datetime 0..1 Voimassaolon loppu customergroup xs:byte 1 Asiakasryhmä 1= aikuinen 2= lapsi 3= nuori 4= seniori valueticketzoneprice zonepricetype 0..1 Hinnat vyöhykkeittäin Vyöhykkeeltä vyöhykkeelle 2.9 Kertakorttilippu ja sen hinnoittelu Metodi URI Vastauksen skeema GET /travelcards/{companyid}/{authorityid}?{saleschannelcode} travelcard.xsd Parametrit Parametri Tyyppi Selite Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 14(18)
companyid short Organisaation tunnus, LMJ = 154 authorityid short TVV tunnus saleschannelcode short Myyntikanavan tunnus. Jos tunnusta ei anneta, tai sille ei löydy hinnoittelua, palautetaan voimassaoleva oletustariffi Vastaus: travelcard fareheader fareheadertype 1 travelticket traveltickettype 1 traveltickettype productowner xs:short 1 Tuotteen omistajai TVV ticketcode xs:short 1 Lippulaji child xs:boolean 1 Asiakasryhmä 1= aikuinen 2= lapsi tariffversion xs:short 1 Versio Palautuu tapahtumassa validstartdatetime xs:datetime 1 Voimassaolon alku validenddatetime xs:datetime 0..1 Voimassaolon loppu starttype xs:byte 1 Lipun voimassaolon alun tyyppi 0= lipun voimassaolo annettu 1= lipun voimassaolo ensimmäisestä käyttöönotosta validitytype xs:byte 1 Voimassaoloajan tyyppi 3=päiviä validitylength xs:short 1 Voimassaoloajan pituus Päivien lukumäärä travelticketzoneprice zonepricetype 0..* Hinnat vyöhykkeittäin Vyöhykkeeltä vyöhykkeelle 2.10 Ryhmälippu Metodi URI Vastauksen skeema GET /othertickets/{companyid}/{authorityid} otherticket.xsd Parametrit: Parametri Tyyppi Selite companyid short Organisaation tunnus, LMJ = 154 authorityid short TVV tunnus Vastaus: otherticket paramheader paramheadertype 1 groupticket grouptickettype 1 grouptickettype productowner xs:short 1 Tuotteen omistajai TVV Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 15(18)
3 Käyttötapaukset ja toimijat N/A ticketcode xs:short 1 Lippulaji tariffversion xs:short 1 Versio Palautuu tapahtumassa validstartdatetime xs:datetime 1 Voimassaolon alku validenddatetime xs:datetime 0..1 Voimassaolon loppu groupsize xs:byte 1 Max ryhmän koko Maksimi ryhmän koko 4 Käyttöoikeudet ja käyttäjähallinta N/A 5 Käsitemalli N/A 6 Integraatiot 6.1 Liikennöitsijäjärjestelmät Tuote- ja tariffihallinta liittyy liikennöitsijäjärjestelmiin Tuote- ja Tariffirajapinnan kautta. Osajärjestelmä tarjoaa liikennöitsijäjärjestelmille tuote- ja tariffitiedot. 6.2 Tarkastajajärjestelmät Tuote- ja tariffihallinta liittyy tarkastajajärjestelmään Tuote- ja Tariffirajapinnan kautta. Osajärjestelmä tarjoaa tarkastajajärjestelmälle tuote- ja tariffitiedot. 7 UI demo/proto N/A Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 16(18)
8 Muutoshistoria Versio Päiväys Tekijä Tarkistaja Hyväksyjä Muutoshistoria V0.1 3.11.2013 Arto Rantanen V0.2 7.11.2013 Arto Rantanen V0.3 17.11.2013 Arto Rantanen Ensimmäinen versio Palaverin 6.11.2013 aikana esiin tulleet asiat Lisätty työmatkalipun ohjaus sekä tieto KELA-lipusta V1.0 12.12.2013 Ari Hätinen Yhdistetty kuvaus, käyttötapaukset ja käyttöliittymä yhteen dokumenttiin. V1.1 19.2.2014 Jan Forsberg Tehty skeemat ja samassa yhteydessä korjailtu ja muuteltu tietojen nimiä V1.2 21.2.2014 Arto XML testiesimerkkien teon yhteydessä havaitut korjaukset ja muutokset blacklistcontrol laitettu commonparams elementtiin Tietojen arvoalueiden täsmennystä, asiakasryhmät, tuoteryhmät Poistettu Liikennöitsijä tuote, Kelalippu, Tuotteen pakollisuus, Käytettävä koulukalenteri (ei voi sitoa lippulajiin) Lisätty voimassaolo 2 eri aikarajaa per viikonpäivä V1.3 7.4.2014 Arto customergroupid arvot muutettu productid arvot muutettu ja arvoja lisätty productgroup arvoja lisätty paperilipun tekniset tunnisteet v1.4 15.4.2014 Arto/Pasi Koulun liittäminen koulukalenteriin Kortin hinta lisätty Yleiset korttiparametrit Lipputuotteiden vaihtoajat ja voimassa päivätyypeittäin Lipputuotteen tietoihin v1.5 9.5.2014 Arto Tägien nimiä korjattu vastaamaan scheemaa (calendarschool) v1.6 19.09.2014 pk Muutettu tietotyypit W3C tyyppisiksi. Lisätty urlit ja skeemojen nimet. v1.7 10.10.2014 pk Lisätty transactioncardissuer korttiparametreihin. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 17(18)
Versio Päiväys Tekijä Tarkistaja Hyväksyjä Muutoshistoria Korjatt company ja authority parametrien nimet REST-urleihin v1.8 08.01.2015 pk Lisätty uusi elementti valueloading yleisiin parametreihin. Siirretty arvonlatausrajat arvotuotteilta valueloading-elementtiin. v1.9 19.02.2015 pk Tarkennettu hinnoittelun tariffiversiota. v1.10 13.03.2015 pk Muutettu koulukalenterin koulutunnus xs:short -> xs:int. Tarkennettu yötaksaa. v1.12 10.04.2015 pk Toimintolistaan lisätty hakuparametriksi toiminnon tyyppi. Toimintolistan elementtien puuttuvia kenttiä lisätty. v1.13 27.04.2015 pk Lisätty customerdataupdate toimintolistalle. Tyyppien nimiä korjattu. v1.14 23.06.2015 pk Lisätty loadingallowed kortin tuoteparametreihin v1.15 2.10.2015 as Vaihdettu Piletti-termit Waltiksi ja siirretty LMJ-pohjaan Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 18(18)