Waltti
Waltti
1. Kumppanirajapinnan yleiset käyttöehdot 2
Kumppanirajapinnan yleiset käyttöehdot
Yleiset käyttöehdot Lippunäytöt Rajapinnan käyttö
Yleistä kumppanimyynnistä
Tässä dokumentissa kuvataan Waltti-mobiililipun ulkoasun teknisiä tietoja kuten elementtien sijoittelua, fontteja, värejä jne sekä perusasioita rajapinnan käyttöehdoista. Tarkka määrittely rajapinnan parametreista ja vaadituista sisällöistä tulee varmistaa ohjelmistorajapinnan määrittelydokumentista (rajapintakuvaus). Rajapintakuvausta voidaan jälleenmyyjästä riippumatta muuttaa, eikä rajapinnan yhteensopivuutta taaksepäin voida taata kaikissa tilanteissa. Xxxxxx pidättää itsellään oikeuden muuttaa myös lipun ulkoasua ja siihen liittyviä vaatimuksia.
Muutoksista tiedotetaan etukäteen.
Tavoitteena on, että lipunmyyntikumppanien sovellusten lippunäytöt vastaavat ulkoasultaan mahdollisimman pitkälle Xxxxxx graafista ilmettä helpottaen visuaalista validointia ja sitä kautta kuljettajien työtä. Vaikka lipun validointi tapahtuu pääosin koneellisesti, on kuljettajien ja mahdollisten lipuntarkastajien rooli lippujen kelpoisuuden varmistamisessa hyvin keskeinen ja heidän työnsä helpottamiseksi tulee käytettävien lippujen olla ulkoisesti mahdollisimman samankaltaisia.
Järjestelmää ylläpitävät tahot toimittavat 3. osapuolelle myyntirajapintaan tunnistautumiseen tarvittavat tiedot, kun asiasta on sovittu ensimmäisen kaupungin kanssa. Onnistuneen testauksen jälkeen toteutetaan vastaavat järjestelyt tuotantoympäristöön, kun asianmukaiset sopimukset kaupungin ja kumppanin kesken on allekirjoitettu. Uusien kaupunkien lisääminen kumppanin rajapintaan tapahtuu tuomalla vastaavat tuotteet kumppanin tuoteluetteloon/luetteloihin, kun kukin kaupunki siitä ilmoittaa Waltille. Uusia tunnuksia tms. ei tarvita, vaan kaikki myynti tapahtuu yksillä ja samoilla tunnuksilla.
Myytävät tuotteet
Kumppanimyynnissä myydään Waltti-kaupunkien lipputuotteita, joita kukin kaupunki on päättänyt antaa kumppaneilla myyntiin. Minimissään tarjolla on aikuisen ja lapsen ikäryhmän kertaliput. Tuotetietoja ylläpidetään Xxxxxx tuotehallinnassa. Nämä liput tulee olla validoitavissa kunkin kaupungin liikenteessä Waltin lippujärjestelmässä. Liikennevälineiden lippujärjestelmät kommunikoivat ainoastaan Waltin taustajärjestelmän kanssa.
Lipun peruutus ja hyvitys
Peruutus on sovelluksen sisäinen tekninen toiminto, joka on luvallista suorittaa kyseisen ostotapahtuman sisällä, mikäli teknisistä syistä johtuen lippua ei ole ollut mahdollista toimittaa asiakkaalle. Loppukäyttäjällä itsellään ei saa olla mahdollisuutta lipun peruuttamiseen missään olosuhteissa. Peruutettu lippu ei kelpaa ajoneuvossa ja sen käyttöyrityksestä täytyy syntyä seurattavissa ja raportoitavissa oleva
tapahtuma. Ajoneuvossa jo leimattua lippua ei saa koskaan peruuttaa.
Jälkikäteen tehtävät peruutukset käsitellään hyvityksinä ja niistä sovitaan tapauskohtaisesti. Waltti-järjestelmässä ei lähtökohtaisesti hyvitetä myytyjä lippuja takautuvasti.
Lipun viivakoodin automaattinen päivittyminen
Turvallisuussyistä lipun viivakoodi pitää päivittää 5 minuutin välein hakemalla uusi koodi rajapinnasta. Mikäli asiakkaan mobiililaitteen verkkoyhteys ei ole hetkellisesti toiminnassa, voidaan vanhan koodin käyttöä jatkaa tilapäisesti. Asiakkaan katkaistessa verkkoyhteyden itse (asettamalla puhelimensa esim. lentotilaan), tulee lippu poistaa käytössä, ellei sovellus saa haettua palvelimelta uutta koodia palvelimelta määritellyn aikarajan sisällä. Tämä koskee ensisijaisesti lippuja, jotka ovat voimassa yi kaksi tuntia.
Asiakaspalautteiden käsittely ja palvelun saatavuus
Kumppanin myymissä lipuissa ilmenevissä ongelmatilanteissa asiakaspalvelun tarjoaa lähtökohtaisesti kumppani. Mikäli rajapinta ei vastaa, voi kumppani tehdä siitä vikailmoituksen LMJ:lle. Yhteystiedot ilmoitetaan sopimusta tehtäessä. LMJ ei takaa, että myyntirajapinta on käyttävissä häiriöttä. Suunnitelluista huoltokatkoista ilmoitetaan etukäteen, mikäli kumppani on toimittanut LMJ:lle asianmukaiset yhteystiedot.
Fontit ja värit
Lippunäytön fonttina on Googlen fontti Poppins. Tössö dokumentaatiossa fonttien koot ilmaistaa dpi-arvoina.
Waltin päävärit ovat keltainen, oranssi ja turkoosi, joita ei varsinaisesti käytetä lippunäytöllä. Päättyneissä lipuissa käytetään harmaan eri sävyjä mm. tekstilaatikossa, jossa ilmaistaan lipun voimassaolon päättyminen.
Väri | Hex | RGB |
LightGrey | f5f5f5 | R245 G245 B245 |
Grey | 808080 | R128 G128 B128 |
DarkGrey | 404040 | R64 G64 B64 |
White | ffffff | R255 G255 B255 |
Black | 000000 | R0 G0 B0 |
Esimerkkejä näytöistä
Voimassa oleva lippu
Lipun viivakoodi tulee vaihtua säännöllisesti, jolloin se pitää hakea palvelimelta 5 minuutin välein. Loppukäyttäjän käyttöliittymässä ei saa olla lipun peruutus-toiminnallisuutta. Voimassaoloaika juoksee alaspäin sekunnin tarkkuudella.
QR-koodin suurentaminen
Kun viivakoodia napsauttaa, avautuu se lipun numeerisen koodin kanssa erilliseen ikkunaan suurennettuna. Suurennetun viivakoodin koko on noin 20-25 mm.
Mikäli viivakoodin lukeminen ei onnistu esim. huonokuntoisen tai pienen näytön vuoksi, voidaan viivakoodi avata suurennettuna erilliseen, modaaliseen ikkunaan.
Samassa näytössä esitetään myös matkatilin tunnus. Kaksoispisteen perässä on kyseisen matkatiliin liitetyn lipun juokseva numero. Matkatilin näyttäminen on tarpeen mahdollisten ongelmatilanteiden selvittämiseksi.
Päättyneet liput
Voimassaolo päättynyt, matkustusaikaa vielä jäljellä
Lipun voimassaoloaika umpeutunut, matkustusaikaa vielä jäljellä. Tämä lippunäyttö näkyy 90 min voimassaolon päättymisen jälkeen.
Voimassaolo päättynyt, ei matkustusaikaa enää jäljellä
Lipun voimassaolo umpeutunut, matkustusaikaa ei ole jäljellä. Tämä lippunäyttö on nähtävissä yhden vuorokauden ajan voimassaolon päättymisen jälkeen.
Kehittäjän ohjeet
Kehittäjään ohjeet sovelluksen tekemiseen ja rajapinnan käyttöön löytyvät oheisen linkin takaa. xxxxx://xxxxxx.xxxxxxxxx.xxx/x/x/xXxXx0XX
Yleistä rajapinnasta
Kumppani voi hakea kaikki mahdolliset liput yhdellä kutsulla ja pitää niitä halutessaan oman myyntisovelluksensa muistissa. On kuitenkin huomattava, että kumppanilla on vastuu huolehtia siitä, että liput ja hinnat päivitetään riittävän usein, jotta mahdolliset muutostilanteet on mahdollista hallita. Muutamissa Waltti-kaupungeissa käytössä oleva yölisä on tuotu mukaan rajapintaan, mikäli sellainen on käytössä.
Rajapinnasta on mahdollista saada kuluvan hetken hinnoittelun lisäksi myös tulevaisuudessa voimaan astuvat hinnoittelut, mikäli sellaisia on julkaistu. Mikäli rajapinnasta tulevassa hinnoittelussa on useampi voimassa oleva hinnoitteluvaihtoehto, käytetään hinnoittelun määrittelyssä sitä vaihtoehtoa, joka on voimassa lipun tulevana käyttöhetkenä. Rajapinnan hinnoittelumekanismit on kuvattu tarkemmin rajapinnan käyttöohjeissa.
Käyttötapaukset
Tällä hetkellä rajapinta tukee yksinkertaisia peruskäyttötapauksia. Tulevaisuudessa rajapintaa kehitetään ja tuodaan uusia ominaisuuksia mukaan. Tavoite on pitää rajapinta mahdollisimman pitkälle taaksepäin yhteensopivana, mutta tätä ei voida kaikissa tapauksissa aina taata. Tavoite on ylläpitää tällaisissa tilanteissa sovitun ajan sekä uutta että vanhaa versiota, jotta kaikki kumppanit ehtivät muuttaa omat sovelluksensa hallitusti. Erityisesti tapauksissa, jotka ovat LMJ:n vaikutuspiirin ulkopuolella, tätä ei voida aina varmuudella taata.
Kertalipun osto
Peruskäyttötapaus on kertalipun osto. Tapahtumassa syntyy taustajärjestelmään matkatili, johon ostettu lippu kytketään. Matkatili saa tunnisteen, jolla se voidaan löytää myöhemmässä vaiheessa esim. virheselvittelyä varten. Oston yhteydessä lippu aktivoidaan, jolloin se astuu voimaan liikennevälineissä. Ostettuun lippuun tulee hakea rajapinnasta uusi tunniste (lippukoodi) viiden minuutin välein. Mikäli tietoliikenteestä johtuen (puhelin hetkellisesti pois verkosta tms) uutta koodia ei saada haettua, tulee se tehdä heti, kun yhteys jälleen palaa.
Kertalippu voidaan asettaa astumaan voimaan heti tai myöhemmin. Tilanteesta riippuen voi olla järkevää käyttää rajapinnasta saatavaa hinnoittelutietoa siihen, että osataan velottaa omalta asiakkaalta oikea lipun hinta. Varsinaisesti lippu ostetaan rajapinnasta vasta sitten, kun asiakas “aktivoi” ostamansa lipun. Tämä voi olla paras tapa esimerkiksi silloin, kun Waltti-lippu myydään osana matkaketjua, jossa ei voida varmuudella tiedää, milloin asiakas haluaa ottaa ostamansa Waltti-lipun käyttöön.
Aktivoinneista on hyvä erottaa kaksi tapausta. Toinen on lipun aktivoiminen rajapinnassa, jolloin se astuu voimaan (tehdään myös lippukoodin uusinnan yhteydessä). Tämä toiminto ei näy kuluttajalle. Lisäksi on käyttäjälle näkyvä aktivointitoimenpide, jolla asiakas “aktivoi” aiemmin ostamansa lipun (matkaoikeuden), jolloin lippu ostetaan fyysisesti rajapinnasta.
Lippujen hinnoittelu
Liput hinnoitellaan rajapinnassa viranomaisilta saatujen hinnoittelutietojen mukaisesti. Tämä asettaa myynnille tiettyjä ehtoja: Lippu tulee myydä käyttöajankohdan hinnalla, mikäli sellainen on tiedossa.
Esim. viranomainen nostaa lippujen hintoja vuodenvaihteessa. Mikäli ostaminen tapahtuu vanhan tariffin aikana, mutta käyttö uuden tariffin aikana ja uusi tariffi on tiedossa, tulee uutta tariffia käyttää hinnoitteluun
Mikäli uutta tariffia ei ole tiedossa, voidaan lippu myydä ostohetken hinnalla.
Mikäli viranomaisella on käytössään yöhinnoittelu näille rajapintalipuille, tulee kaikissa tilanteissa varmistaa, että lippu ostetaan rajapinnasta aina oikealla hinnalla.
Lippu myydää asiakkaalle yöhinnalla, mikäli se aiotaan käyttää yöhinnoittelun ollessa voimassa
Jos lippu on myyty normaalihinnalla ja sen aktivointi (osto rajapinnasta) on asiakkaalle mahdollista, tulee lippu ostaa rajapinnasta yöhinnalla. Rajapinta ja nämä käyttöehdot eivät ota kantaa siihen, millä hinnalla lippu on myyty. Se edellyttää, että rajapinnasta lippu ostetaan aina kulloinkin voimassa olevalla hinnalla
Kumppanin velvollisuus on varmistaa, että lippuja ei voi aktivoida (ostaa rajapinnasta) väärillä hinnoilla
Tämä toimii myös toisin päin eli jos asiakas on maksanut lipusta yöhinnan, mutta aktivoi sen normaalihinnoittelun aikana, tulee lippu ostaa rajapinnasta normaalihinnalla, ei yöhinnalla.
Lipun peruutus
Kumppani saa peruuttaa ostetun lipun omassa palvelussaan tapauksissa, joissa lippua ei ole ollut esim. teknisistä tai muista syistä johtuen mahdollista toimittaa asiakkaalle. Asiakkaalla itsellään ei saa omassa käyttöliittymässään olla mahdollisuutta peruutuksen tekemiseen.
Ajoneuvossa leimattua ja käyttöön otettua lippua ei saa peruuttaa, vaan ongelmatilanteissa se käsitellään hyvityksenä.
Lipun hyvittäminen
Kumppani voi hyvittää omalle asiakkaalleen myydyn lipun, jos siihen on perusteltu syy. Kumppanirajapinnasta ostettuja lippuja ei lähtökohtaisesti palauteta, ellei virhe ole johtunut teknisestä ongelmasta.
Lipun kelpoisuus
Lipun voimassaolo alkaa siitä hetkestä, kun se on ostettu rajapinnasta ja on voimassa viranomaisen kullekin lipulle määrittelemän ajan.
Myyntien ja käyttöjen seuranta
Myynti perustuu Xxxxxx tilipohjaisen lippujärjestelmän sääntöihin. Liput validoidaan Waltissa Xxxxxx tuotesääntöjen mukaisesti. Käyttötapahtumista voidaan viedä ulkoisiin järjestelmiin tarpeelliset tiedot tietosuoja huomioiden. Käyttöjen seuranta tapahtuu ensisijaisesi Waltissa, koska vain se tietää, millä säännöillä nousuja hyväksytään. Viranomaisella on näkyvyys myytyihin ja leimattuihin lippuihin Xxxxxx raportoinnin kautta.
Myytyjen lippujen laskutus
Rajapinta ei ota kantaa siihen, miten viranomainen laskuttaa myydyt liput kumppaneilta. Malli voi olla joko laskutusperusteinen tai kumppani tilittää annettujen aikataulujen mukaisesti myymänsä liput. Tämä on yksityiskohta, jonka jokainen viranomainen huomioi kumppanien kanssa tekemissään sopimuksissa.
Kieliversiot
Tällä hetkellä rajapinta tukee kolmea kieliversiota (FI/SV/EN). Tuettuina ovat tekstit, jotka saadaan tuote- ja tariffihallinnasta. Näitä tietoja ovat mm. asiakasryhmä ja lipun nimi. Muita käyttöliittymän tekstejä täytyy toistaiseksi ylläpitää kumppanin omassa sovelluksessa. Tavoitteena on saada lisättyä ne rajapintaan tulevaisuudessa.
Oheisessa taulukossa on esitetty kolmella kielellä tekstit, jotka esiintyvät tämän dokumentin käyttöliittymäkuvissa. Lippuihin liittyvät teksit saadaan rajapinnasta.
RESOURCE | FI | EN | SV |
ticket/status/valid | Voimassa | Valid | Giltig |
ticket/messages/ recently-expired | Lipun voimassaolo päättynyt. | This ticket has expired. | Biljetten är inte giltig längre. |
Voit tehdä alkaneen matkan loppuun asti, ei vaihto-oikeutta. | You can finish your journey, but no changes are permitted. | Du kan slutföra en påbörjad resa, ingen bytesrätt. | |
ticket/messages/expired | Lipun voimassaolo päättynyt [DATE] klo [TIME]. | This ticket expired on [DATE] at [TIME]. | Biljetten har gått ut [DATE] kl. [TIME]. |