Ilmoitin.fi rajapinnat, liittyminen, testaaminen Ohjelmistotalopäivä 23.5.2014 Matti Rounamo VH/TIHA
Palvelusta yleensä Ilmoitin.fi on Verohallinnon omistama sähköinen asiointipalvelu, jonka kautta voi lähettää ilmoitusaineistoa tietuekuvauksen mukaisina tiedostoina Verohallintoon, Kelalle ja Työttömyysvakuutusrahastolle. Ilmoituksilla on määrätty rakenne ja tarkistussäännöt, jotka on kuvattu Verohallinnon ilmoitusten tietuekuvauksissa. Tarkastus on luonteeltaan muodollisen oikeellisuuden tarkastamista, sisällön oikeellisuutta ei tarkasteta Verohallinnon rekistereistä. 2
Palveluun voi tunnistautua Katsotunnisteilla ja verkkopankkitunnisteilla. Ilmoittimen kautta tullut vuonna 2014 yli 24,6 miljoonaa ilmoitusta; 439 000 aineistossa www.ilmoitin.fi 3
Rajapinnat/käyttötavat Palvelussa on kolme tapaa lähettää ilmoituksia: 1. Selaimen kautta lataamalla ilmoituksen/ilmoitukset sisältävä tiedosto selaimen upload-toiminnallisuudella 2. Käyttäen lähettämiseen Web Services -rajapintaa (ApiTaMo) 3. Käyttäen asiointipalvelun ja Ilmoittimen välistä tunnelipalvelua, jossa käyttäjä tunnistautuu vain asiointipalveluun käyttäen Verohallinnon hyväksymää tunnistusta Vaihtoehdossa 2 tunnistautuminen on mahdollista vain Katso-tunnisteella, muissa vaihtoehdoissa lähettäjän tunnistaminen onnistuu myös henkilötunnisteella (verkkopankkitunnukset ja HST-kortti). 4
Punaisella katkoviivalla Raksikanavat KARVA = Katso roolija valtuuspalvel u 5
ApiTamo Ilmoitin.fi:n ApiTaMo Web Services -rajapinta mahdollistaa saumattoman ja standardeihin perustuvan integraation järjestelmien ja Ilmoitin.fi:n välillä. ApiTaMo -rajapinnan kautta voi tarkastaa tai tarkastaa ja lähettää ilmoituksia ja tuloveroilmoitusten liitetiedostoja. Ilmoituksien, joihin liittyy vastausaineisto, lähetys onnistuu myös, samoin vastausaineistojen nouto. Käyttäjän tunnistus tapahtuu Katso-tunnisteella (joko Katso PWD- tai Katso OTP -tunnistusmenetelmällä). ApiTaMo -rajapinta on tarkoitettu ohjelmistojen/saaspalveluiden käyttöön ja sen saa käyttöön Verohallinnon luvalla. Rajapinta on ns. SOAP-tyyppinen. Tunnistautumistapahtuma (SAML-assertio) on voimassa 10 minuuttia, jonka sisällä sanoma on lähetettävä Ilmoitin.fi:lle. 6
ApiTaMon periaatekuva Katso käyttäjän tunnistus Katso valtuustarkastus Lähettävä verkkopalvelu tai ohjelmisto Ilmoitusten muodostus ja katselu ApiTaMo client HTTPS <SAML-assertio> <ilmoitus> 010:hetu tai Y-tunnus. </ilmoitus> ApiTaMo Web Services Ilmoitin.fi Verohallinto 7 7
ApiTamon toiminta/ilmoituksen lähetys 1. Loppukäyttäjä tunnistautuu ohjelmistoon/palveluun (jatkossa järjestelmä) sen käyttämällä tunnistusmenetelmällä. 2. Loppukäyttäjä valitsee järjestelmästä ilmoittamistoiminnallisuuden. 3. Järjestelmä kysyy loppukäyttäjän Katso-tunnisteita (joko käyttäjätunnus ja salasana tai sen lisäksi myös kertakäyttösalasana) tai tiedot haetaan turvallisesta paikasta, jonne ne on etukäteen tallennettu. 4. Järjestelmä suorittaa ApiTaMon 1. kutsun, jolla sanomavälitys käynnistyy (mm. tunnistautuminen Katsoon, tunnistetietojen välitys ApiTaMolle). 5. Kun ApiTaMo on tarkastanut ilmoituksen ja ilmoittajan oikeuden ilmoittaa, lähettävä järjestelmä saa vastaanottokuittauksen. 6. Lähettävä järjestelmä esittää saadun vastauksen ja vastaanottokuittauksen loppukäyttäjälle. 7. Aineisto siirtyy (ei reaaliaikaisesti) Verohallinnon operatiivisiin järjestelmiin käsiteltäväksi. 8
ApiTamon toiminta/kyselyt 1. Loppukäyttäjä tunnistautuu ohjelmistoon/palveluun (jatkossa järjestelmä) sen käyttämillä tunnuksilla. 2. Loppukäyttäjä valitsee järjestelmästä ilmoittamistoiminnallisuuden. 3. Järjestelmä kysyy loppukäyttäjän Katso-tunnisteita (joko käyttäjätunnus ja salasana tai sen lisäksi myös kertakäyttösalasana) tai tiedot haetaan turvallisesta paikasta, jonne ne on etukäteen tallennettu. 4. Järjestelmä suorittaa ApiTaMon 1. kutsun, jolla sanomavälitys käynnistyy (mm. tunnistautuminen Katsoon, tunnistetietojen välitys ApiTaMolle). 5. Kun ApiTaMo on tarkastanut ilmoituksen ja ilmoittajan oikeuden ilmoittaa, lähettävä järjestelmä saa vastaanottokuittauksen, joka sisältää noutotunnisteen. 6. Lähettävä järjestelmä esittää saadun vastauksen ja vastaanottokuittauksen loppukäyttäjälle. 7. Aineisto siirtyy (ei reaaliaikaisesti) Verohallinnon operatiivisiin järjestelmiin käsiteltäväksi. 9
Kyselyt jatkuu 8. ApiTaMo saa vastausaineiston ja siirtää sen odottamaan noutoa. 9. Järjestelmä kysyy ApiTaMolta käyttäen noutotunnistetta onko vastausaineisto jo noudettavissa. 10. ApiTaMo vastaa järjestelmälle: a) vastausaineisto löytyy: palauttamalla noutotunnisteella löydetyn vastausaineiston b) vastausaineistoa ei löydy: vastaamalla ettei vastausaineistoa ei vielä ole noudettavissa 11. Järjestelmä käsittelee saamansa vastauksen riippuen siitä löytyikö vastausaineisto vai ei. 10
ApiTamo Client ApiTaMon lähetystoiminnallisuuden toteuttamisen helpottamiseksi on Javalla toteutettu ApiTaMoClientohjelmisto, joka on luonteeltaan referenssitoteutus. ApiTaMoClient on Katso-tunnistautumisen suhteen Web Services Client (WSC). ApiTaMoClient toteuttaa Katson ID-WSF -rajapinnan (Web Services) mukaisen tunnistuksen. ApiTaMoClient on liitetty valmiiksi Katsoon. Katso-tunnistautumiseen kuuluva roolikysely tapahtuu Web Services Provider:n (WSP) eli Ilmoitin.fi:n päässä, ei WSC:ssä. Jos ApiTaMoClient:a ei halua tai ei voi käyttää, on toteutus mahdollista tehdä myös itse, dokumentaatio löytyy Veron sivulta. Tosin se on työläs vaihtoehto ID-WSF -rajapintojen mutkikkuuden vuoksi. 11
Testauksesta Alkuvaiheessa kätevintä on testata ohjelmiston tuottamia ilmoituksia käyttämällä testi.ilmoitin.fi:n selainliittymää ja etusivulta löytyvää aineiston tarkastusta. Kun aineistot menevät tarkastuksesta läpi, testaamista voi laajentaa lähettämisen testaamiseen. Siihen tarvitaan Katso-testitunnistetta. Siihen tarvittavan keinotekoisen henkilö- ja y-tunnuksen saa osoitteesta katso-support@tieto.com. Perusta tunniste osoitteessa https://htesti.katso.tunnistus.fi:ssä ja pyydä sen aktivointia osoitteesta katso-support@tieto.com. Osoite palvelee myös Katso-tunnisteiden mennessä lukkoon. Lisäksi tarvitaan toteutus ApiTaMo-client:sta (joko referenssitoteutus tai itse tehty) ja rajapinnan osoitteet. Rajapinnan osoitetta voi kysyä tamo.tk@vero.fi:stä. Referenssitoteutuksen voi ladata Ilmoitin.fi:n kehittäjäsivustolta. 1 21.2.2014 12
Sama asia lyhyesti Toteuta ilmoitusten/kyselyiden muodostus järjestelmääsi. Jos ilmoitukset/kyselyt halutaan lähettää suoraan ohjelmistosta, tutustu ApiTaMoClient-referenssitoteutukseen tai toteuta oma. Ota yhteyttä Verohallintoon (tamo.tk@vero.fi) saadaksesi ApiTaMo-rajapinnan testiympäristön osoitteet. Hanki Katso-testitunnisteessa tarvittava keinotekoinen henkilö- ja y-tunnus katso-support@tieto.com:sta ja perusta testitunniste Katson testiympäristössä. Testaa toteutus testi.ilmoitin.fi:tä käyttäen (selain tai Web Services). Sovi tuotannollisesta käytöstä Verohallinnon kanssa, jonka jälkeen saat tuotannon osoitteet. Ilmoita Verohallinnolle (tamo.tk@vero.fi) sähköpostiosoite, johon ApiTaMon käyttökatkoista tiedotetaan. 1 21.2.2014 13
Tietoa liitetyistä ohjelmistoista Ilmoittimen ja sen rajapintojen käytön seuraamiseksi ja virhetilanteista tiedottamiseksi olemme halukkaita kuulemaan toiminnastanne. Kertokaa lyhyesti seuraavista asioista: yrityksenne toiminnasta, kohdeasiakkaista, ohjelmiston toimintaperiaatteesta (verkkopalvelu, erillinen asennettava ohjelmisto jne.) ja sen tuottamista ilmoituksista. haluatteko ohjelmistonne esiintyvän mahdollisesti julkaistavalla listalla, jossa kerrotaan ohjelmistoista, jotka tuottavat Verohallinnolle ilmoitusaineistoa. 14
Linkkejä ja lisätietoja Ilmoitin.fi:n testiympäristö: testi.ilmoitin.fi Ilmoitin.fi:n tuotantoympäristö: www.ilmoitin.fi Ilmoitin.fi-kehittäjäsivusto: www.ilmoitin.fi/kehittajat Tietuekuvaukset: http://www.vero.fi/fi- FI/Syventavat_veroohjeet/Sahkoinen_asiointi/Kehittajat/Tietuekuv aukset/tietuekuvaukset Suorasiirrot_ja_muut_il%2815904%29 Verohallinnon Katso-sivut: http://www.vero.fi/katso Testauksessa tarvittavat Katso-tunnisteet: katsosupport@tieto.com Ilmoitin.fi- ja ApiTaMo-kysymykset: tamo.tk@vero.fi Rakentamisilmoitukset: http://www.vero.fi/rakentamisilmoitukset 1 21.2.2014 15