ApitamoPKI:n tekniset ohjeet
Tunnistautuminen ja valtuudet
ApitamoPKI käyttää tunnistamiseen Verohallinnon varmennepalvelun varmenteita. Varmennetta käytetään vain lähettävän tahon tunnistamiseen (client certificate authentication) eikä lähetettäviä ilmoituksia digitaalisesti allekirjoiteta. ApitamoPKI ei allekirjoita vastausviestejä tai paluuaineistoja.
ApitamoPKI hyväksyy varmennepalvelun myöntämät tiedon tuottajien varmenteet (myöntäjä Data Providers Issuing CA, testissä Test Data Providers Issuing CA), jotka on tarkoitettu Web Services -kanavassa (viivästetty tai reaaliaikainen) käytettäväksi. ApitamoPKI:n testiympäristössä hyväksytään vain testivarmenteet ja tuotannossa vain tuotantovarmenteet. Tulorekisterin SFTP-kanavan käyttöön tarkoitettuja varmenteita (myöntäjä Vero Data Providers SFTP Issuing CA) ei voi käyttää ApitamoPKI:ssa.
Varmenne on voimassa kaksi vuotta sekä testissä että tuotannossa. Vanhentuneilla ja sulkulistalle merkityillä varmenteilla ei voi tunnistautua.
Lue lisää varmenteista vaihe1. toteuta ja testaa sekä vaihe 2: Tuotanto -sivuilta.
ApitamoPKI ei vaadi Suomi.fi-valtuutusta toisen puolesta asiointiin. Varmenteella voi lähettää muidenkin kuin sen organisaation ilmoituksia, jolle varmenne on myönnetty, jos tästä on sopimus osapuolten kesken. Vain tietyissä tapauksissa vaaditaan Suomi.fi-valtuutusta, esimerkkinä tästä on maahantuonnin alv -tietovirta (VSTULLER). Tietovirtakohtaiset valtuusvaatimukset voi tarkastaa täältä.
ApitamoPKI:n 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 ApitamoPKI tekninen kuvaus 1.4 (pdf)
ApitamoPKI:n testiympäristön osoitteet:
- palvelu: https://apitesti.ilmoitin.fi/wsapp/apitamopki
- WSDL-kuvaus: https://apitesti.ilmoitin.fi/wsapp/apitamopki?wsdl
ApitamoPKI:n tuki palvelee osoitteesta tamo.tk(at)vero.fi.
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 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:
- Loppukäyttäjä tunnistautuu ohjelmistoon/palveluun (jatkossa järjestelmä) sen käyttämällä tunnistusmenetelmällä ja valitsee järjestelmästä ilmoittamistoiminnallisuuden. Lähettäminen voi myös tapahtua täysin automaattisesti ilman loppukäyttäjää.
- Järjestelmä suorittaa ApitamoPKI:n kutsun, jonka yhteydessä välitetään varmenne ApitamoPKI:lle.
- Kun ApitamoPKI on tarkastanut varmenteen ja ilmoituksen muodollisen oikeellisuuden, lähettävä järjestelmä saa vastaanottokuittauksen.
- Lähettävä järjestelmä esittää tarvittaessa saadun vastauksen ja vastaanottokuittauksen loppukäyttäjälle.
- Aineisto siirtyy (ei reaaliaikaisesti) Verohallinnon operatiivisiin järjestelmiin käsiteltäväksi.
Aineiston tai vastauksen nouto (RetrievalOperation)
Jos lähetettyyn aineistoon liittyy paluuaineisto, kuten verokorttien suorasiirrossa, vastaus haetaan RetrievalOperation:lla. Myös jos lähetetty aineisto oli iso (koko 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
Toteutustyö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 ilmoitusaineistoja sekä noutaa niihin liittyviä vastausaineistoja.
Mikäli ApitamoPKIClient ei sellaisenaan sovellu tarpeisiin, siitä voi ottaa mallia ja generoida ApitamoPKI:n WSDL-kuvauksen perusteella oman toteutuksen.
ApiTamoPKIClient noudattaa MIT-lisenssiä ja tähän liittyvissä kolmansien osapuolten palveluissa sovelletaan heidän ilmoittamia lisenssiehtoja, jotka on mainittu ko. palvelun kirjastoissa.