Tulorekisterin tekninen rajapinta

Teknisellä rajapinnalla tarkoitetaan eri järjestelmien välille rakennettavaa integraatiota. Esimerkiksi palkkahallinnon ohjelmiston ja tulorekisterin välille rakennetaan sähköinen yhteys, jolloin tiedot siirtyvät kahden sovelluksen välillä.

Lähetä tiedot tulorekisteriin suoraan palkkajärjestelmästä

Teknisen rajapinnan avulla palkkatiedot voidaan ilmoittaa suoraan palkkajärjestelmästä tulorekisteriin ilman, että käyttäjän tarvitsisi siirtyä erilliseen tulorekisterin ilmoittamisen palveluun. Kun tiedot siirretään tulorekisteriin teknisen rajapinnan kautta, manuaalisten työvaiheiden määrä palkkatietojen ilmoittamisessa vähenee. Teknisen rajapinnan avulla palkanlaskija voi käyttää samaa järjestelmää sekä palkanlaskentaan että tietojen ilmoittamiseen.

Ilmoittaminen ei vaadi käyttäjältä erillistä tunnistautumista

Tietojen ilmoittajan ei tarvitse erikseen kirjautua palveluun ja tunnistautua henkilökohtaisesti, sillä teknisen rajapinnan käytöstä on sovittu jo palvelua avattaessa. Ilmoittaminen nopeutuu ja siihen liittyvät työtehtävät helpottuvat.

Tulorekisterin varmennepalvelusta muodostettu varmenne annetaan joko yritykselle itselleen tai sen puolesta asioivalle tilitoimistolle tai muulle palkkahallinnon kumppanille. Varmenne myönnetään yritykselle, jos yritys ilmoittaa palkat itse teknistä rajapintaa pitkin. Jos varmenne myönnetään tilitoimistolle tai muulle palkkahallinnon kumppanille, se sitoutuu varmenteen käytön yhteydessä ilmoittamaan vain niiden asiakkaiden puolesta, joiden kanssa on tehnyt keskinäisen toimeksiantosopimuksen.

Teknisen rajapinnan varmennetta käytettäessä ei tarvitse valtuuttaa jokaista työntekijää erikseen.

Ilmoita automaattisesti rajapinnan avulla

Ilmoittamiseen liittyi aiemmin useita manuaalisia työvaiheita: ilmoitusten laatiminen, kirjautuminen ilmoittamisen palveluun, tiedoston siirtäminen palveluun ja tiedoston lähetys. Teknisen rajapinnan avulla ilmoittaminen voidaan automatisoida. Palkkahallinnon järjestelmään syötetty tieto voidaan siirtää teknistä rajapintaa pitkin tulorekisteriin automaattisesti, joten manuaaliset työvaiheet vähenevät.

Rajapinta edellyttää varmenteen hakemista

Tulorekisterin teknisiä rajapintoja käyttävät organisaatiot tunnistetaan käyttämällä tulorekisterin varmennepalvelua. Ratkaisu pohjautuu digitaalisiin varmenteisiin (Public Key Infrastructure).

Varmennepalvelua hyödyntävät kaikki tulorekisteriin aineistoja tuottavat ja sieltä aineistoja noutavat organisaatiot. Varmenne myönnetään organisaatiolle, joka vastaa tietojen toimittamisesta tulorekisteriin tai jolla on oikeus saada tietoja tulorekisteristä. Tulorekisterin varmennepalvelu myöntää varmenteet. Varmenteella tunnistetaan tietoja tuottava tai käyttävä organisaatio sekä varmistetaan aineiston muuttumattomuus. Varmenteet myönnetään käyttötarkoituksen mukaan.

Kun organisaatio on sopinut tulorekisterin kanssa teknisen rajapinnan käyttämisestä voi varmenteen haku ja käsittely alkaa. Varmennepalvelu lähettää asiakkaalle siirtotunnuksen ja kertakäyttösalasanan. Ne saatuaan asiakas voi tehdä varmennepyynnön. Varmennepyynnön palvelukutsu palauttaa vastaanottokuittauksessa noutotunnuksen, jolla yksilöidään luotava varmenne hakua varten. Varmenne saadaan palautteena varmenteen haun palvelukutsulle, johon liitetään noutotunnus. Tämän jälkeen asiakkaalla on tulorekisterin palveluiden käyttöön tarvittava varmenne.

Lue lisää Varmennepalvelun yleis- ja rajapintakuvauksista.

Tulorekisteriin voi rakentaa kolmenlaisia teknisiä rajapintoja:

1. Reaaliaikainen Web Service -rajapinta
2. Viivästetty Web Service -rajapinta
3. SFTP-rajapinta.

Reaaliaikainen Web Service -rajapinta: vähän ilmoituksia, välitön palaute

Reaaliaikaisia palveluita voidaan käyttää integroitaessa palkanlaskentajärjestelmä suoraan tulorekisterin palveluihin. Reaaliaikainen WS-rajapinta on tarkoitettu käytettäväksi tilanteissa, joissa tulorekisteriin toimitetaan vain pieni määrä ilmoituksia. Rajapintaa käyttäessään ilmoittaja saa välittömän palautteen siitä, että ilmoitus on vastaanotettu tulorekisteriin. Reaaliaikaisen WS-rajapinnan kautta ilmoituksia voi toimittaa vain yhden kerrallaan.

Jos palkanlaskenta-ajosta muodostuu paljon palkkatietoilmoituksia, ne tulee lähettää tulorekisteriin joko viivästetyn Web Service -rajapinnan tai SFTP-rajapinnan kautta.

Viivästetty Web Service -rajapinta: suuri määrä ilmoituksia

Viivästettyä Web Service -rajapintaa suositellaan silloin, kun ilmoittaja toimittaa kerralla suuren määrän ilmoituksia tulorekisteriin. Tietojen toimittaja lähettää tulorekisterin tekniseen rajapintaan aineiston Web Service -palvelupyynnöllä. Tulorekisteri lähettää palvelupyyntöön synkronisen vastaanottokuittauksen. Vastaanottokuittaus sisältää mahdolliset palvelupyynnön vastaanotossa havaitut virheet eriteltynä. Tulorekisteri käsittelee aineiston.

Tietojen toimittaja lähettää tulorekisterin tekniseen rajapintaan käsittelypalautteen kyselyn, johon tulorekisteri vastaa lähettämällä käsittelypalautteen. Jos tulorekisteri on jo ehtinyt käsitellä aineiston, käsittelypalaute sisältää tiedot aineiston sisältämistä virheettömistä ja virheellisistä tiedoista sekä käsittelyssä havaitut virheet eriteltyinä. Jos tulorekisteri ei ollut vielä ehtinyt käsitellä aineistoa, käsittelypalaute sisältää tiedon siitä, että aineisto on edelleen käsiteltävänä. Tietojen ilmoittajan on siinä tapauksessa tehtävä palautekysely hetken kuluttua uudelleen. Käsittelyaikaan vaikuttaa muun muassa lähetetyn aineiston koko. Tulorekisteri käsittelee aineistot saapumisjärjestyksessä. Jos aineiston koko ylittää 50 Mt, se tulee jakaa erillisiksi aineistoiksi ennen lähettämistä.

SFTP-rajapinta: suuri määrä ilmoituksia

WS-rajapinnan ohella SFTP-rajapinta sopii suuren ilmoitusmäärän toimittamiseen. Tietojen ilmoittaja muodostaa aineistotiedoston ja lähettää sen tulorekisteriin. Tulorekisteri vastaanottaa aineistotiedoston ja käsittelee tiedoston sisältämät tiedot. Kun aineisto on käsitelty tulorekisterissä, tietojen ilmoittaja saa SFTP-rajapinnan kautta noudettavaksi palautetiedoston, joka sisältää käsittelypalautteen. Noutoajankohdassa tulee huomioida aineiston käsittelyyn tulorekisterissä tarvittava aika. Tietojen ilmoittajan tulee varautua siihen, että jos palautetiedosto ei ole noutohetkellä valmistunut, noutoa on yritettävä hetken kuluttua uudelleen. Tulorekisteri käsittelee aineistot saapumisjärjestyksessä ja käsittelyaikaan vaikuttaa muun muassa lähetetyn aineiston koko. Jos aineiston koko ylittää 50 Mt, se tulee jakaa erillisiksi aineistoiksi ennen lähettämistä.

SFTP-rajapintaa suositellaan silloin, kun palkka-ajo tuottaa kerralla suuria massoja ja ilmoittajalla ei ole mahdollisuutta käyttää WS-rajapintaa.

Tutustu myös teknisten rajapintojen yleiskuvauksiin.