ApitamoPKI

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ä vuoden 2020 aikana.

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ä Suomi.fi-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.

ApitamoPKI varmenteella tunnistautuminen

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). Tulorekisterin SFTP-kanavan käyttöön tarkoitettuja varmenteita (myöntäjä Vero Data Providers SFTP Issuing CA) ei hyväksytä ApitamoPKI:ssa.

Jos varmenne on jo hankittu tulorekisteri-ilmoittamista tai Vero API:n käyttöä 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. Lue lisää testivarmenteen hausta sivulta Varmennepalvelu.

Varmenteet ovat voimassa 2 vuotta sekä testissä että tuotannossa. Vanhentuneilla varmenteilla ei voi ilmoittaa eikä myöskään sulkulistalle merkityillä.

Lue tarkemmin varmennepalvelusta tulorekisterin sivuilta

Katso myös Verohallinnon ja tulorekisterin rajapintapalveluiden käyttöehdot (pdf).

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 MTOM-liitteinä.

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 (ResultId). Jos lähetettyyn aineistoon liittyy paluuaineisto, vastaussanomassa on noutotunniste elementissä RetrievalId.

Lähetysprosessi

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 status-koodin Ok ja vastausaineisto on vastauksessa MTOM-liitteenä.

Jos aineisto ei ole vielä valmiina noudettavaksi, RetrievalOperation palauttaa status-koodin wait.

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 lokitiedostoon.

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 latauslinkit 

Testi- ja tuotantoympäristö

ApitamoPKI:n testiympäristön osoitteet:

ApitamoPKI:n tuotannon osoitteet saa osoitteesta tamo.tk(at)vero.fi kun toteutus on todettu toimivaksi testiympäristössä

ApitamoPKI:n tuki vanhasta tutusta paikasta eli osoitteesta tamo.tk(at)vero.fi