Ilmoitin.fi Ohjelmistotalopäivä 26.11.2015 Maria Jansson-Ojanen Verohallinto
Ilmoitin.fi/Yleistä Sähköinen asiointipalvelu, jonka kautta lähetetään ilmoituksia Verohallintoon, Kelalle ja Työttömyysvakuutusrahastolle Ilmoitukset lähetetään tietuekuvauksen mukaisin tiedostoina Ilmoituksen lähettämiseen käytetään pääasiassa Katsotunnistetta Yksityishenkilöt (esim. yksityiset elinkeinoharjoittajat) voivat lähettää ilmoituksia myös verkkopankkitunnisteella 2
Ilmoitin.fi/Yleistä Aineisto tarkastetaan ennen lähetystä Ilmoittimen kautta on 2015 tullut: yli 46 miljoonaa ilmoitusta 1,2 miljoonassa aineistossa www.ilmoitin.fi 3
Ilmoitin.fi/Käyttö Ilmoituksia voi lähettää: Selaimella Katso tai verkkopankkitunnus/hst-kortti Käyttäen lähettämiseen Web Service rajapintaa Katso-tunniste Käyttäen asiointipalvelun ja Ilmoittimen välistä Tunnelikytkentää, jossa käyttäjä tunnistautuu vain asiointipalveluun käyttäen Verohallinnon hyväksymää tunnistusta Verkkopankkitunnus/HST-kortti 4
Web Service rajapinta (ApiTaMo) Rajapinta mahdollistaa saumattoman ja standardeihin perustuvan integraation järjestelmien ja Ilmoitin.fi:n välille Rajapinnan kautta voi tarkastaa tai tarkastaa ja lähettää ilmoituksia ja tuloveroilmoituksen liitetiedostoja Ilmoituksien, joihin liittyy vastausaineisto, lähetys onnistuu myös, samoin vastausaineistojen nouto Käyttäjän tunnistus tapahtuu Katso-tunnisteella 5
Web Service rajapinnan käyttöönotto lyhyesti Tutustu ohjeisiin osoitteessa www.ilmoitin.fi/kehittajat Toteuta ilmoitusten/kyselyiden muodostus järjestelmääsi Jos ilmoitukset/kysely halutaan lähettää suoraan ohjelmistosta, tutustu ApiTaMoClient referenssitoteutukseen tai toteuta oma Referenssitoteutuksen voi ladata kehittäjäsivustolta 6
WS rajapinnan käyttöönotto lyhyesti Ota yhteyttä Verohallintoon (tamo.tk@vero.fi) saadaksesi rajapinnan testiympäristön osoitteet 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 Tunnisteeseen tarvittavan keinotekoisen henkilö- ja y-tunnuksen saa osoitteesta katso-support@tieto.com 7
WS rajapinnan käyttöönotto lyhyesti 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. Sovi käyttöönotosta Verohallinnon kanssa, jonka jälkeen saat rajapinnan tuotannon osoitteet tamo.tk@vero.fi:stä Ilmoita Verohallinnolle (tamo.tk@vero.fi) sähköpostiosoite, johon ApiTaMon käyttökatkoista tiedotetaan 8
Tunnelipalvelu Tunnelipalvelu on kahdenvälinen kytkentä asiointipalvelun ja Ilmoittimen välillä Tunneli on hyvä vaihtoehto erityisesti niissä tapauksissa, joissa Katso-tunnistusmenetelmä ei ole sopiva tai käytettävissä Esimerkiksi tilanteen, joissa ilmoittajalla on vain henkilötunnus ja ilmoittaja ei ole antanut esimerkiksi tilitoimistolle valtuutusta 9
Tunnelipalvelu Tunnelipalvelu tunnistaa lähetettävän palvelun palvelukohtaisen käyttäjätunnuksen ja salasanan perusteella Verohallinto myöntää nämä tunnisteet kun lähettävä palvelu on hyväksytty rajapinnan käyttäjäksi Loppukäyttäjä on autentikoitava tunnistusmenetelmällä (esim. Tupas), jonka Verohallinto hyväksyy 10
TunneliClient Tunnelipalvelun käyttöönoton helpottamiseksi on toteutettu Javalla TunneliClient ohjelmisto, joka on luonteeltaan referenssitoteutus TunneliClient toteuttaa tunnelipalvelussa tarvittavat toiminnallisuudet, kuten lähettävän pään tunnistamisen, ilmoituksen lähettämisen ja tuloksen vastaanotto Tarkastuksen ja lähetyksen tulos on XML-muodossa, jonka talous- tai henkilöstöhallinnon ohjelmisto/ palvelu esittää valitsemallaan tavalla loppukäyttäjälle 11
TunneliClient Jos TunneliClient:a ei halua tai voi käyttää, dokumentaatiota oman toteutuksen tekemiseen löytyy kehittäjäsivustolta Ota ensimmäisenä yhteyttä ohjelmistotalot@vero.fi jos haluat liittää asiointipalvelusi tunnelin käyttäjäksi 12
Ilmoittimen sanomien vastaanotto ja virhetilanteet Huomioitavaksi ApiTaMo-rajapintaa käyttävissä ohjelmistoissa - tilanne, jolloin Ilmoitin.fi-palvelu ei ole palvelimen vikatilanteen vuoksi pystynyt ottamaan vastaan aineistoja: <SOAP-ENV:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>soap-env:server</faultcode> <faultstring>virhe tiedoston tallennuksessa, tiedostoa ei vastaanotettu.</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Muutamassa tapauksessa käyttäjälle on jäänyt mielikuva, että lähetys on onnistunut ja ilmoitukset olisivat siirtyneet eteenpäin Verohallinnon käsittelyyn, vaikka niin ei todellisuudessa ole 13
Ilmoittimen sanomien vastaanotto ja virhetilanteet Tilanteissa, joissa Ilmoitin.fi-palvelu vastaa normaalisti, ilmoitusaineistojen vastaanoton status löytyy <kuittaus>-elementistä jos vastaanotto on onnistunut: <vastaanotto>true</vastaanotto> jos vastaanotto on epäonnistunut: <vastaanotto>false</vastaanotto> ja <info> -elementistä löytyy tarkempi tieto syystä <ApiTaMoTulos> <kuittaus> <vastaanotto>false</vastaanotto> <info> </ApiTaMoTulos> Infotietona voi olla: <info>ei valtuutusta vuosi-ilmoittamiseen yritykselle xxx</info> <info>datassa virheitä</info> ( tunnus:tieto-parillisessa tai kiinteämittaisessa datassa) <info>ilmoitusdatassa</info> ( tuloveroilmoituksen liitetiedosto esim. virheellisesti nimetty) <info> Ilmoitustunnistetta ei löydy. Aineiston korjaamisessa (ilmoitustyyppi K) tai poistamisessa (ilmoitustyyppi D) on käytettävä samaa ilmoituskanavaa kuin alkuperäisessäkin aineistossa. </info> <info>sama perusilmoitus on lähetetty jo aiemmin.</info> <info>korjausilmoituksella ilmoituslajin pitää olla sama kuin perusilmoituksella. Perusilmoituksella ilmoitettu {0}, nyt ilmoitetaan {1}</info> <info>korjaus- tai poistoilmoituksella kohdekauden pitää olla sama kuin perusilmoituksella</info> 14
Ilmoittimen sanomien vastaanotto ja virhetilanteet Vastausaineistojen nouto informoidaan <Vastaus> -elementissä <Vastaus> <ilmoitus></ilmoitus> // JOS NOUTO ON OK, ILMOITUKSET TÄÄLLÄ <info></info> // JOS NOUTO EI OLE OK, SYY LÖYTYY TÄÄLTÄ <aika></aika> <noutotunniste></noutotunniste> </Vastaus> Infotietona voi olla: <info>aineisto ei vielä noudettavissa</info> ( Vastausaineisto ei ole palautunut Verohallinnosta Ilmoitin.fi-palveluun) <info>tuntematon noutotunniste!</info> <info>ei valtuuksia pyydettyyn aineistoon!</info> <info>aineiston käsittelyssä on tapahtunut virhe!</info> <info>sama perusilmoitus on lähetetty jo aiemmin.</info> Lisää sanomista Ilmoitin.fi-palvelun Kehittäjät-sivustolta löytyvässä dokumentissa ApiTaMon tekninen kuvaus 15