Ilmoitin.fi - tunnistamisen sertifikaattiratkaisu Apitamopki Web Services -rajapinnan muutokset Verohallinnon ja ohjelmistotalojen yhteistyöpäivä 23.5.2019
Esityksen sisällöstä Muutama sana varmenteista Apitamopki:sta ja sen palveluista Hieman ApitamopkiClient-referenssitoteutuksesta
Muutos esitettynä yhdellä kuvalla Nyt Katso WSIDP Jatkossa varmennepalvelu Käyttäjä luottaa Client Client Apitamopki Apitamo
Yleistä muutoksesta Ilmoitin.fi:n Web Services -rajapinnassa siirrytään Katso-tunnisteiden käytöstä Verohallinnon myöntämän varmenteen käyttöön johtuen Katso-palvelun päättymisestä. Tämä muuttaa sanomarakenteita merkittävästi kun WS Security- ja SAML2- rakenteet poistuvat käytöstä. Samalla valtuuskäsittelyä on kevennetty aikaisemmasta, valtuuskäsittely on siis samankaltaista mitä tulorekisterin osalta noudatetaan. Vain harvoissa tapauksissa tullaan vaatimaan erillistä valtuutusta (VSTULLER-tietovirta esimerkkinä tästä). Vanha ApiTamo toimii Apitamopki:n rinnalla niin kauan kuin Katso on käytettävissä. Se voidaan ajaa alas alemminkin jos kaikki käyttö on siirtynyt uuteen.
Pari kalvoa käytettävistä varmenteista
Varmenteista 1/2 Apitamopki hyväksyy ilmoittamisen tulorekisterin varmennepalvelun myöntämillä tiedon tuottajien varmenteilla, jotka on tarkoitettu Web Services -kanavassa (viivästetty tai reaaliaikainen) käytettäviksi (myöntäjä Data Providers Issuing CA, testissä Test Data Providers Issuing CA). Jos tämmöinen on jo hankittu tulorekisteri-ilmoittamista varten, uutta ei tarvita. Varmennetta käytetään vain lähettävän pään tunnistamiseen (client certificate authentication) eikä lähetettäviä ilmoituksia digitaalisesti allekirjoiteta. Apitamopki ei allekirjoita vastausviestejä tai paluuaineistoja. Apitamopki:n testiympäristössä kelpaavat vain testivarmenteet ja tuotannossa vain tuotantovarmenteet.
Varmenteista 2/2 Varmenteet ovat voimassa 2 vuotta sekä testissä että tuotannossa. Vanhentuneilla varmenteilla ei voi ilmoittaa eikä myöskään sulkulistalle merkityillä. Tulorekisterin SFTP-kanavan käyttöön tarkoitettuja varmenteita (myöntäjä Vero Data Providers SFTP Issuing CA) ei hyväksytä Apitamopki:ssa. Varmennepalvelusta voi lukea tarkemmin osoitteesta https://www.vero.fi/tulorekisteri/ohjelmistokehittäjät/varmennepalvelu/ Käyttöehdot löytyvät osoitteesta https://www.vero.fi/globalassets/tulorekisteri/verohallinnon-ja-tulorekisterinrajapintapalveluiden-kayttoehdot.pdf
Apitamopki-rajapinnan palveluista
Apitamopki:n toteutuksesta ja palveluista Rajapinta koostuu kahdesta SOAP-palvelusta, jotka ovat kuvattu WSDL:ssä: aineiston lähettäminen eli SendOperation (SOAPAction: SendAction) aineiston tai vastauksen nouto eli RetrievalOperation (SOAPAction: RetrievalAction) Lähetettävät ilmoitusaineistot ja tuloveroliitteet lähetetään MTOM-liitteinä (Message Transmission Optimization Mechanism). Myös palautettavat aineistot ja tarkastustulokset palautetaan MTOM-liitteinä. Ilmoituksien merkistönä käytetään Verohallinnon tietuekuvauksissa ilmoitettua merkistöä eli ISO-8859-1:stä. XML-muotoisissa aineistoissa käytetään UTF-8 - merkistöä. Sanomarakenteet on kuvattu Apitamopki-rajapinnan teknisessä kuvauksessa.
Aineiston lähettäminen (SendOperation) Aineiston lähettämiseen käytetään SendOperation:a. Samalla operaatiolla lähetetään myös tuloveroilmoitusten liitetiedostot (kuten tase tai tuloslaskelma). Aineistot ja tuloveroilmoitusten liitetiedostot ovat pyyntösanomassa MTOMliitteinä. Jos kyseessä on iso aineisto (koko megatavuja tai enemmän) tai jostain muusta syystä haluaa jättää sen ei-reaaliaikaiseen käsittelyyn eli taustakäsittelyyn, pyynnössä BackgroundProcessing-elementin arvo on true. Tällöin vastaussanomassa tulee mukana noutotunniste (RetrievalId).
Lähetysprosessista yleisesti Ilmoitusten lähettäminen tapahtuu karkealla tasolla seuraavasti: 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ä suorittaa ApitamoPKI:n kutsun, jonka yhteydessä välitetään varmenne Apitamopki:lle. 4. Kun Apitamopki on tarkastanut varmenteen ja ilmoituksen muodollisen oikeellisuuden, lähettävä järjestelmä saa vastaanottokuittauksen. 5. Lähettävä järjestelmä esittää saadun vastauksen ja vastaanottokuittauksen loppukäyttäjälle. 6. Aineisto siirtyy (ei reaaliaikaisesti) Verohallinnon operatiivisiin järjestelmiin käsiteltäväksi. Lähettäminen voi myös tapahtua täysin automaattisesti ilman loppukäyttäjää.
Aineiston tai vastauksen nouto (RetrievalOperation) Jos lähetettyyn aineistoon liittyy paluuaineisto, kuten verokorttien suorasiirrossa tai veronumerokyselyissä, vastaus haetaan RetrievalOperation:lla. Myös jos lähetetty aineisto oli iso (yleensä useampi megatavu tai enemmän) ja siten jätetty taustakäsittelyyn (BackgroundProcessing=true), tarkastustulos noudetaan tällä palvelulla. Operaatiossa käytetään noutotunnistetta, jonka Apitamopki on palauttanut SendOperation:n vastauksessa em. tapauksissa. Jos aineisto on valmiina noudettavaksi, RetrievalOperation palauttaa statuskoodin Ok ja vastausaineisto on vastauksessa MTOM-liitteenä. Jos aineisto ei ole vielä valmiina noudettavaksi, RetrievalOperation palauttaa status-koodin wait.
ApitamopkiClient-referenssitoteutus
ApitamopkiClient Integraatiotyötä helpottamaan on tehty ApitamopkiClient-referenssitoteutus. Se on toteutettu Java-kielellä ja sisältää lähdekoodin lisäksi ajettavan binäärin ja pienimuotoisen käyttöliittymän. Se tallentaa myös SOAP-sanomat levylle. Referenssitoteutuksen tarkoitus on auttaa hyödyntäviä tahoja toteuttamaan lähettävässä päässä vaadittavat toiminnallisuudet. ApitamopkiClient -sovelluksen avulla käyttäjä voi lähettää ohjelmistojen tuottamia, Verohallinnon julkaisemien tietuekuvausten mukaisia ilmoitustiedostoja sekä noutaa niihin mahdollisesti liittyviä vastausaineistoja. Mikäli ApitamopkiClient ei sellaisenaan sovellu tarpeisiin, siitä voi ottaa mallia ja generoida Apitamopki:n WSDL-kuvauksen perusteella oman toteutuksen. ApitamopkiClient:n latauslinkki ilmoitetaan myöhemmin.
Palautettavan aineiston lähetys
Palautettavan aineiston lähetyksen vastaus
Palautettavan aineiston nouto
Palautettavan aineiston noudon vastaus
Ohjeita ja osoitteita Ohjeistus täydentyy kun pilotointi etenee, ohjeistus tulee myös englanniksi. ApitamopkiClient-käyttöohje: linkki ilmoitetaan myöhemmin pilotoinnin päättymisen jälkeen Apitamopki-rajapinnan tekninen kuvaus: linkki ilmoitetaan myöhemmin pilotoinnin päättymisen jälkeen Apitamopki:n testiympäristön osoitteet: palvelu: https://apitesti.ilmoitin.fi/wsapp/apitamopki WSDL-kuvaus: https://apitesti.ilmoitin.fi/wsapp/apitamopki?wsdl Apitamopki:n tuotannon osoitteet ilmoitetaan myöhemmin. Apitamopki:n tuki vanhasta tutusta paikasta eli osoitteesta tamo.tk@vero.fi:stä.
Kiitos mielenkiinnosta!