Lippu- ja maksujärjestelmän toiminnallinen määrittely

Transkriptio

1 Lippu- ja maksujärjestelmän toiminnallinen määrittely Tuote- ja tariffirajanta 2014 TVV lippu- ja maksujärjestelmä Oy

2 Sisällysluettelo 1 Osajärjestelmän kuvaus Prosessit Tuote-ja tariffirajannan liittyminen kokonaisjärjestelmään Osajärjestelmän määritelmät Liikennöitsijän järjestelmä Siirtotiedostot Korttien sulkulista (Blacklist.xml) Yleiset ohjaukset (CommonParams.xml) Sulkulistastatus ja ohjaus Päivätyyt Taksa kalenteri Kouluryhmä kalenteri Koulu/Koulukalenteri (lisätty versiossa 1.4) Asiakasryhmät Asiakasryhmien ikärajat ALV Ryhmät ALV Tekstit Paperiliput (Singleticket.xml) Kertalippu (tekniset käytettävät tunnisteet productgroup=4 productid=20) Kertalippujen vaihtoajat Paperilippujen tekstit Korttituotteet (Cardparams.xml) Yleiset korttiparametrit Lipputuotteet korteille Lipputuotteiden vaihtoajat Lipputuotteiden voimassa päivätyypeittäin Kausilipun ohjaustiedot Arvolipun ohjaustiedot Hinnoittelu (Fareparams.xml) Paperilipun hinnoittelu Paperilippujen hinnat vyöhykkeittäin Kausituotteiden hinnoittelu Kausilippujen hinnat vyöhykkeittäin Arvolipun hinnoittelu Arvolipun hinnat vyöhykkeittäin Kertakorttilippu ja sen hinnoittelu (travelcard.xml) Kertakorttilipun hinnat vyöhykkeittäin Ryhmälippu (Otherticket.xml) Käyttötapaukset ja toimijat Käyttöoikeudet ja käyttäjähallinta Käsitemalli Integraatiot Liikennöitsijäjärjestelmät Tarkastajajärjestelmät TVV lippu- ja maksujärjestelmä Oy

3 7 UI demo/proto Muutoshistoria TVV lippu- ja maksujärjestelmä Oy

4 Tuote- ja tariffirajannan kuvaus 1 Osajärjestelmän kuvaus Piletti määrittelyiden mukainen matka- ja kertakorttisovelluksien käsittely on teknisesti ja somuksellisesti mahdollista kaikkien laite- ja ohjelmistovalmistajien toimesta. Määrittelyt ovat avoimet ja toimittajariippumattomat. Piletti ottaa käyttöön avoimen tiedonsiirtorajannan, joka mahdollistaa kaikkien laitetoimittajien toteuttaa Piletti korttien käsittelyssä tarvittavien ohjaustietojen noutamisen Piletti palvelimelta. Sähköistä tiedonsiirtoa varten perustetaan verkkopalvelu. Siirtotiedostoja voidaan hakea palvelusta joko manuaalisesti selainkäyttöliittymän kautta tai automaattisesti, jolloin yhteydenottava järjestelmä lähettää kyselyn, jonka vastauksena saadaan ko. hetkellä olevat uudet siirtotiedostot. Sanomaliikenteellä tarkoitetaan asynkronisia ja synkronisia https protokollan lä välitettäviä sanomia. Yleisesti ottaen kyselysanomat (ohjaustietojen haku) voidaan toteuttaa synkronisina TVV lippu- ja maksujärjestelmä Oy 1(13)

5 2 Prosessit 2.1 Tuote-ja tariffirajannan liittyminen kokonaisjärjestelmään 2.2 Osajärjestelmän määritelmät Liikennöitsijän järjestelmä Liikennöitsijän tai palveluntuottajan järjestelmän on kyettävä hakemaan tarvittavat ohjaustiedot ja kieltolistat Piletti 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 Siirtotiedostot Siirtotiedostot ovat XML-dokumentteja, joiden schemat on kuvattu erikseen. Uusi ohjaustieto korvaa aina vanhan kokonaisuudessaan voimaantulohetkestä alkaen. Poikkeuksen tekee tariffitiedot, joita voi olla myös sisäkkäin voimassaolevia versioita. Siirtotiedostoja ovat: 2014 TVV lippu- ja maksujärjestelmä Oy 2(13)

6 sulkulista blacklist.xml yleiset ohjaukset commonparams.xml paperiliput singleticket.xml korttituotteet cardparams.xml hinnoittelu fareparams.xml matkailijaliput travelcard.xml muut liput otherticket.xml Tässä dokumentissa kuvataan siirtotiedostoon tulevat tapahtumatyyt ja niiden tietosisällöt. Tietotyyt: X = Alfanumeerinen D = Päivämäärä (muoto vvvv-kk-pp) T = Aika (muoto tt:mm:ss) N = Numeerinen tieto, (desimaaliluku) ilman etunollia C = Kokonaisluku etunollilla 2.3 Korttien sulkulista (Blacklist.xml) Sulkulista tuotetaan automaattisesti kerran vuorokaudessa. Liikennöitsijällä on velvollisuus hakea sulkulistatiedosto kerran vuorokaudessa Piletin verkkopalvelusta ja jakaa sulkulistatiedot matkakortteja käyttäviin laitteisiin. Sulkulista-tiedoston tietueen sisältö on seuraava: Sulkulista <Blacklist> Tyyp Pitu us Suljettu kortti tai sarjan alaraja firstcardnumber X 25 Kortin koko numero Sarjan yläraja lastcardnumber X 25 Kortin koko numero tai 0 Sulkutaso blocklevel N 2 Koodiston mukaan Sulku päivämäärä blockdate D 8 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. 2.4 Yleiset ohjaukset (CommonParams.xml) Sulkulistastatus ja ohjaus Sulkulistastatukset <BlacklistControl> Tyyp Pituu s Sulkutaso blocklevel N 2 1=varastettu 2=kadonnut 3=maksuhäiriö Käyttäjän teksti usertext X 12 Kuljettajan rahastuslaitteelle Leimauksen hyväksyntä operationctrl C 1 0= Leimaus estetty 1= Leimaus hyväksytään 2014 TVV lippu- ja maksujärjestelmä Oy 3(13)

7 2.4.2 Päivätyyt Päivätyyp <datetype> Tyyp Pituus Tunnus type N 2 1=arkipäivä 2=lauantai 3=sunnuntai 4=erikoispäivä1 5=erikoispäivä2 Päivätyyn nimi name X 24 Yötaksa alkaa nightstart T 6 tt:mm:ss Yötaksa loppuu nightend T 6 tt:mm:ss Taksa kalenteri Kalenteri poikkeuspäivät <calendarexcdate> Tyyp Pituus Tuotteenomistaja productownerid N 3 TVV tunnus Päivämäärä calendardate D 8 vvvv-kk-pp Taksan päivätyyp type N = ei vaikutusta kalenteriin Kouluryhmä kalenteri Koulukalenteri Tyyp Pituu <CalendarSchool> s Tuotteen omistaja productownerid N 3 TVV tunnus Koulukalenterin tunnus datetableid N 3 koulukortin ohjauksessa (000=oletus kalenteri) Vuosi year N 4 miltä vuodelta kalenteri Sallitut päivät alloweddates X 366 poterot vuoden päiville alkaen vuoden ensimmäisestä päivästä 0=ei matkustusoikeutta 1=on matkustusoikeus Koulu/Koulukalenteri (lisätty versiossa 1.4) Koulu/koulukalenteri Tyyp Pituu <SchoolCalenderMapng> s Tuotteen omistaja productownerid N 3 TVV tunnus Koulu tunnus schoolid N 4 Koulukalenterin tunnus schoolcalendarid N 3 koulukortin tunnus (000=oletus kalenteri) 2014 TVV lippu- ja maksujärjestelmä Oy 4(13)

8 2.4.6 Asiakasryhmät Asiakasryhmä Tyyp Pituu <customergroup> s Asiakasryhmän tunnus customergroupid N 1 muutettu versiossa 1.3 0=ei määritelty 1=aikuinen 2=lapsi 3=nuori 4=seniori 5=oskelija 6=koululainen Asiakasryhmän nimi name X Asiakasryhmien ikärajat Asiakasryhmän ikärajat Tyyp Pit <customergroupage> uus Tuotteen omistaja productownerid Nn 3 TVV tunnus Asiakasryhmän tunnus customergroupid N 1 muutettu versiossa 1.3 1=aikuinen 2=lapsi 3=nuori Asiakasryhmän alaraja agemin N 2 0=ei alarajaa Asiakasryhmän yläraja agemax N 2 0=ei ylärajaa ALV Ryhmät ALV ryhmät Tyyp Pituus <vatgroup> Alv ryhmän tunnus vatgroupid N 4 ALV tunnus tuotteella ALV prosentti vatpercentage N 4,2 Uusi Alv alkaa startdate D 8 Alv muutos alkaa Uusi prosentti newvatpercentage N 4,2 Tuleva alv prosentti Tekstit vattext Erikieliset tekstit ALV Tekstit Alv teksti <vattext> Tyyp Pituus Kielikoodi languagecode C 1 0=suomi 1=ruotsi 2=englanti Alv teksti vattxt X 30 Arvonlisäveron kuittiin tulostettava teksti 2014 TVV lippu- ja maksujärjestelmä Oy 5(13)

9 2.5 Paperiliput (Singleticket.xml) Kertalippu (tekniset käytettävät tunnisteet productgroup=4 productid=20) Paperiliput Tyyp Pituus <PaperTicket> Tuotteen omistaja productownerid N 3 TVV /Liikennöitsijä Lippulaji ticketcode N 4 Lipun tunnus Tuotteen nimi name X 24 Asiakasryhmä customergroup C 1 muutettu versiossa 1.3 1=aikuinen 2=lapsi 3=nuori Alv ryhmä vatgroup N 4 Vaihto transfer C 1 0=ei sallittu 1=on sallittu Vaihtoajat paperticketchangeti Taulukko vaihtoajoista me Tekstit papertickettext Lippulajien tekstit Kertalippujen vaihtoajat Paperiliput vaihtoaika Tyyp Pituus <paperticketchangetime> Vyöhykkeestä fromzone N Vyöhykkeeseen tozone N Vaihtoaika changetime N 4 minuutteja A A Paperilippujen tekstit Lippulajitekstit <papertickettext> Tyyp Pituus Kielikoodi languagecode C 1 0=suomi 1=ruotsi 2=englanti Lippulajiteksti, IP readertext X 20 Lippulajiteksti, RAP reporttext X 20 Lippulajiteksti, MYY salestext X Korttituotteet (Cardparams.xml) Yleiset korttiparametrit Korttiparametrit <cardparamcommon> Tyyp Pituus Kortin liikkeellelaskija cardapplicationissuer N 6 Esim Etäkortin tekninen käyttöikä cardtechage N 2 Vuosia 2014 TVV lippu- ja maksujärjestelmä Oy 6(13)

10 Arvon käyttöaika teknisen iän umpeuduttua valueaddtime N 4 Päiviä Arvon hälytysraja valuealertlimit N 3 Saldo, euroa jäljellä Kauden hälytysraja periodalertlimit N 3 Päiviä jäljellä Antipass aika antipasstime N 4 Aika sekunteina Määrittelee kausikorttien yhteydessä ns. antipass ajan. Uudelleen käytön aikaraja reusetimelimit N 4 Aika sekunteina Määrittelee arvolipun oston ryhmälipun ostamiseksi. Ryhmän kasvatus vaihdon yhteydessä groupincrease C 1 0= ei ole sallittu 1= sallittu Virheilmoituksen näyttöaika errormsgtime N 2 aika sekunteina Infonäyttöön siirtymisaika infoscreendelay N 2 aika sekunteina Kortin hinta cardprice N 4,2 Uusi hinta newcardprice N 4,2 Uusi hinta alkaen newpricestartdate D 8 vvvv-kk-pp Lipputuotteet korteille Liput korteilla Tyyp Pituus <cardticket> Tuotteen omistaja productownerid N 3 TVV /Liikennöitsijä Lippulaji ticketcode N 4 Lipun tunnus Tuotteen nimi name X 24 Tuoteryhmä productgroup C 2 1=kausilippu 2=arvolippu 3=matkailijalippu, kertatuote 5=erikoislippu Tuote producttype C 2 0=kausilippu 1=joustolippu 2=koululaislippu 3=bestpricelippu (4=työmatkalippu) 5=oskelijalippu muutettu versiossa =arvolippu 17=senior lippu 18=kertatuote 19=ryhmätuote Personointi personalized C 1 0=haltijakohtainen 1=henkilökohtainen 2014 TVV lippu- ja maksujärjestelmä Oy 7(13)

11 ALV ryhmä vatgroup N 4 Veroprosentit kerrottu ryhmän tiedoissa Vaihto transfer C 1 0 = ei sallittu 1 =on sallittu Vaihtoajat cardticketchangetime Taulukko vaihtoajoista Voimassaoloajat datetypeperiod Päivätyypeittäin voimassaoloajat, koskee lähinnä koululaislippuja sekä seniorlippuja Lipputuotteiden vaihtoajat Lipun vaihtoaika Tyyp Pituu <cardticketchangetime> s Vyöhykkeestä fromzone N Vyöhykkeeseen tozone N Vaihtoaika x y changetime N 4 minuutteja A A Lipputuotteiden voimassa päivätyypeittäin Päivätyyp voimassa <datetypeperiod> Tyyp Pitu us Tunnus datetype N 2 1=arkipäivä 2=lauantai 3=sunnuntai 4=erikoispäivä1 5=erikoispäivä2 Voimassa alkaen starttime1 T 6 tt:mm:ss Voimassa asti endtime1 T 6 tt:mm:ss Voimassa alkaen starttime2 T 6 seniorilipulla mahdollista kahdet voimassaoloajat tt:mm:ss Voimassa asti endtime2 T 6 tt:mm:ss Kausilipun ohjaustiedot Kausilipun ohjaustiedot <periodcontrol> Tyyp 2014 TVV lippu- ja maksujärjestelmä Oy 8(13) Pitu us Tuotteen omistaja productownerid C 3 TVV / Liikennöitsijä Lippulaji ticketcode C 4 Voimassa perioddays N 3 Voimassa vuorokausia Myös joustolipun, oskelijalipun, työmatkalipun sekä bestprice lipun ohjaus Vuoden voimassa periodyear C 1 0=ei vuosituote 1=voimassa vuoden Annetun ajan dayperiod C 1 0=ei aikarajoitusta

12 1=aikarajoitus (alkaen asti annetaan myynnin yhteydessä) Matkapäivät/Matkojen määrä periodtrip N 3 Joustolipun matkapäivät Työmatkalipun matkojen määrä kaudella Arvolippu Lippulaji valueticket N 4 Bestprice lipun käytettävä arvolipun hinnoittelu Maksimi matkat/päivä maxtripday N 2 0=ei rajoitettu, käytössä koululaislipulla Arvolipun ohjaustiedot Arvolin ohjaustiedot <valuecontrol> Tyyp Pitu us Tuotteen omistaja productownerid C 3 TVV / Liikennöitsijä Lippulaji ticketcode C 4 Minimilataus minload N 6,2 Arvon minimilataus Kerrannainen loadstep N 6,2 Latauskerrannainen Maksiarvo maxvalue N 6,2 Suurin sallittu saldo kortilla Arvolipun tunnus valueticket C 4 Voimassaoloajan ulkopuolella käytettävän arvolipun hinnoittelu koskee lähinnä seniorilippua 2.7 Hinnoittelu (Fareparams.xml) Paperilipun hinnoittelu Paperilipun hinnoittelu<paperticketfar e> Tyyp Pituu s Tuotteen omistaja productownerid N 3 TVV /Liikennöitsijä Lippulaji ticketcode N 4 Lipun tunnus Tariffiversio tariffversion N 4 Palautuu tapahtumassa Voimassaolon alku validstartdatetime DT 18 vvvv-kk-ppttt:mm:ss Voimassaolon loppu validenddatetime DT 18 vvvv-kk-ppttt:mm:ss Asiakasryhmä customergroup C 1 1=aikuinen 2=lapsi 3=nuori Hinnat vyöhykkeittäin paperticketzoneprice Vyöhykkeeltä vyöhykkeelle Paperilippujen hinnat vyöhykkeittäin Paperilipun vyöhykehinnat Tyyp Pitu <paperticketzoneprice> us max 55 kpl Vyöhykkeestä fromzone N 2 1-n (maksimi tvv:n tiedoista) 2014 TVV lippu- ja maksujärjestelmä Oy 9(13)

13 Vyöhykkeeseen tozone N 2 1-n (maksimi tvv:n tiedoista) Normaali hinta price N 6,2 normaalihinta Yöveloitus nightprice N 4,2 0=ei yöveloitusta yöveloituksen hinta Kausituotteiden hinnoittelu Kausilippujen hinnoittelu <periodticketfare> Tyyp Pituu s Tuotteen omistaja productownerid C 3 TVV / Liikennöitsijä Lippulaji ticketcode C 4 Tariffiversio tariffversion N 4 Palautuu tapahtumassa Voimassaolon alku validstartdatetime DT 18 vvvv-kk-ppttt:mm:ss Voimassaolon loppu validenddatetime DT 18 vvvv-kk-ppttt:mm:ss Asiakasryhmä customergroup C 1 1= aikuinen 2= lapsi 3= nuori 4=seniori 5= oskelija 6= koululainen Hinnat vyöhykkeittäin cardticketzoneprice Vyöhykkeeltä vyöhykkeelle Kausilippujen hinnat vyöhykkeittäin Kausilipun vyöhykehinnat Tyyp Pitu <cardticketzoneprice> us Vyöhykkeestä fromzone N 2 Vyöhykkeeseen tozone N 2 Normaali hinta price N 6,2 Normaalihinta max 55 Yöveloitus nightprice N 4,2 0=ei yöveloitusta yöveloituksen hinta Arvolipun hinnoittelu Arvolippujen hinnoittelu <valuecardticketprice> Tuotteen omistaja productownerid C 3 TVV / Liikennöitsijä Lippulaji ticketcode C 4 Tyyp Pituus Tariffiversio tariffversion N 4 Palautuu tapahtumassa Voimassaolon alku validstartdatetime DT 18 vvvv-kk-ppttt:mm:ss Voimassaolon loppu validenddatetime DT 18 vvvv-kk-ppttt:mm:ss Asiakasryhmä customergroup C 1 1= aikuinen 2= lapsi 3= nuori 4= seniori Hinnat vyöhykkeittäin valueticketzoneprice Vyöhykkeeltä vyöhykkeelle 2014 TVV lippu- ja maksujärjestelmä Oy 10(13)

14 Arvolipun hinnat vyöhykkeittäin Arvolipun vyöhykehinnat <valueticketzoneprice> Tyy p Pituu s max 55 kpl Vyöhykkeestä fromzone N 2 Vyöhykkeeseen tozone N 2 Normaali hinta price N 6,2 Normaalihinta Yöveloitus nightprice N 4,2 0=ei yöveloitusta yöveloituksen hinta 2.8 Kertakorttilippu ja sen hinnoittelu (travelcard.xml) Kertakorttituote <travelticket> Tyy p Pitu us Tuotteen omistajai productowner C 4 TVV Lippulaji ticketcode C 4 Asiakasryhmä child C 1 1= aikuinen 2= lapsi Versio tariffversion N 4 Palautuu tapahtumassa Voimassaolon alku validstartdatetime DT 18 vvvv-kk-ppttt:mm:ss Voimassaolon loppu validenddatetime DT 18 vvvv-kk-ppttt:mm:ss Lipun voimassaolon alun tyyp starttype C 1 0= lipun voimassaolo annettu 1= lipun voimassaolo ensimmäisestä käyttöönotosta Voimassaoloajan tyyp validitytype C 1 3=päiviä Voimassaoloajan tuus validitylength N 3 Päivien lukumäärä Hinnat vyöhykkeittäin travelticketzoneprice Vyöhykkeeltä vyöhykkeelle Kertakorttilipun hinnat vyöhykkeittäin Kertakortin vyöhykehinnat Tyy Pituu <travelticketzoneprice> p s Vyöhykkeestä fromzone N 2 Vyöhykkeeseen tozone N 2 Normaali hinta price N 6,2 Normaalihinta Yöveloitus nightprice N 4,2 0=ei yöveloitusta yöveloituksen hinta 2.9 Ryhmälippu (Otherticket.xml) Erikoislippu <groupticket> Tyy p Pitu us Tuotteen omistajai productowner C 4 TVV Lippulaji ticketcode C 4 Versio tariffversion N 4 Palautuu tapahtumassa 2014 TVV lippu- ja maksujärjestelmä Oy 11(13)

15 Voimassaolon alku validstartdatetime DT 18 vvvv-kk-ppttt:mm:ss Voimassaolon loppu validenddatetime DT 18 vvvv-kk-ppttt:mm:ss Max ryhmän koko groupsize C 2 Maksimi ryhmän koko 3 Käyttötapaukset ja toimijat N/A 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 Tariffirajannan 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 Tariffirajannan kautta. Osajärjestelmä tarjoaa tarkastajajärjestelmälle tuote- ja tariffitiedot. 7 UI demo/proto N/A 2014 TVV lippu- ja maksujärjestelmä Oy 12(13)

16 8 Muutoshistoria Versio Päiväys Tekijä Tarkistaja Hyväksyjä Muutoshistoria V Arto Rantanen V Arto Rantanen V Arto Rantanen Ensimmäinen versio Palaverin aikana esiin tulleet asiat Lisätty työmatkalipun ohjaus sekä tieto KELA-lipusta V Ari Hätinen Yhdistetty kuvaus, käyttötapaukset ja käyttöliittymä yhteen dokumenttiin. V Jan Forsberg Tehty skeemat ja samassa yhteydessä korjailtu ja muuteltu tietojen nimiä V 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ä V Arto customergroupid arvot muutettu productid arvot muutettu ja arvoja lisätty productgroup arvoja lisätty paperilipun tekniset tunnisteet (2.5.1) v Arto/Pasi Koulun liittäminen koulukalenteriin Kortin hinta lisätty Yleiset korttiparametrit Lipputuotteiden vaihtoajat ja voimassa päivätyypeittäin Lipputuotteen tietoihin v Arto Tägien nimiä korjattu vastaamaan scheemaa (calendarschool) Anne Siirretty LMJ-pohjaan TVV lippu- ja maksujärjestelmä Oy 13(13)