Kysymyksiä ja vastauksia ohjelmistokehittäjille

Latauspalvelu

Miten tulorekisterin latauspalvelua käytetään?

Aineistojen latauspalvelu on osa tulorekisterin sähköistä asiointipalvelua, johon kirjaudutaan verkkopankkitunnuksilla, mobiilivarmenteella tai varmennekortilla. Palvelulla voi toimittaa tulorekisteriin aineistoja. Tiedostojen pitää olla xml-muotoisia ja tulorekisterin skeemadokumentaation mukaisia. Aineistojen nouto ei ole mahdollista latauspalvelun kautta.

Missä latauspalvelun ominaisuudet on kuvattu?

Aineistojen latauspalveluun toimitettavan aineiston muoto on sama kuin tekniseen rajapintaan toimitettavan aineiston muoto ja se on kuvattu teknisen rajapinnan palvelukuvauksissa. Lue lisää: Tekninen rajapinta - Tietojen toimittaminen tulorekisteriin 2020 (pdf)

Latauspalvelusta saatavan käsittelypalautteen muoto on sama kuin teknisestä rajapinnasta saatavan palautteen muoto ja se on myös kuvattu teknisen rajapinnan palvelukuvauksissa.

Antaako latauspalvelu virheilmoituksia jo aineiston lähetyksen yhteydessä?

Aineiston lataamisen yhteydessä palvelu antaa käyttäjälle skeemaan liittyvät virheilmoitukset.

Miten latauspalvelun kautta toimitetusta aineistosta saa käsittelypalautteen?

Käsittelypalaute on saatavissa latauspalvelusta sen jälkeen, kun tulorekisteri on tehnyt kaikki aineiston käsittelysääntöjen mukaiset tarkistukset.

Täsmäytys, raportit ja koodistot

Tehdäänkö täsmäytys palautesanoman perusteella vai onko tiedon tuottajilla pääsy tulorekisteriin tarkastamaan lähetetty aineistoja, joista täsmäytyksen voi tehdä?

Suorituksen maksaja voi halutessaan saada tulorekisteriin ilmoitetuista tiedoistaan täsmäytysraportin. Jos tulorekisterissä tiedot eroavat palkanlaskentajärjestelmän tiedoista, tulorekisterissä mahdollisesti olevat virheelliset tiedot on korjattava korvaavalla menettelyllä. 

Lue lisää raporteista: Suorituksen maksaja voi tilata tulorekisteriin ilmoitetuista tiedoista raportteja

Miten osapuolet saavat tiedon siitä, että tulorekisterin koodistoihin on tullut muutoksia?

Tulorekisterin teknisen rajapinnan sanomilla esiintyvät tulorekisterin sisäiset koodistot ja niiden arvot on kuvattu dokumenteissa ”Koodistot” ja ”Palkat – Koodistot – Tulolajit”, sekä "Etuudet – Koodistot – Tulolajit”. Koodistojen ja dokumenttien muutoksista tiedotetaan osapuolia.

Tulorekisterin ulkopuolella ylläpidettäviä koodistoja ovat esimerkiksi Kevan koodistot, työeläkealan vakuutusnumerot ja Tilastokeskuksen ammattiluokitus. Näihin tulleet muutokset koodiston omistaja ilmoittaa tulorekisteriin sekä osapuolille kuten nykyisin. Myös tulorekisteriviranomainen tiedottaa osapuolia muutoksista. 

Varmenteen käyttäminen rajapintakutsuissa

Mikä osa lähetettävästä aineistosta allekirjoitetaan eri kanavissa?

Allekirjoituksen kohteena on palvelukanavasta riippumatta aina tulorekisteriin toimitettava aineisto, ei palvelukanavaan liittyvä siirtokehys. Web Service -kanavaa käytettäessä allekirjoitus muodostetaan Envelope/Body-elementin sisällä olevasta tulorekisterin skeeman mukaisesta juuri-elementistä (Root Element). Dokumentaation mukaisesti allekirjoitettu juuri-elementti sijoitetaan sitten SOAP Body -elementin sisälle ennen sen lähettämistä tulorekisteriin. Allekirjoitettu aineisto ei saa muuttua tämän vaiheen aikana.

Varmenteen allekirjoituksen vaiheet Web Service -kanavassa.

Web Service -kanavassa allekirjoituksen vaiheet tiivistetysti:

  1. Muodosta tulorekisterin XML-aineisto ja SOAP Envelope.
  2. Hae SOAP Envelopen Bodyn sisällä oleva root-elementti ja muodosta siitä uusi XML-dokumentti.
  3. Allekirjoita tämä uusi XML-dokumentti dokumentaation mukaisesti.
  4. Poista Bodyn sisällä ollut root-elementti ja lisää sen tilalle äsken muodostettu allekirjoitettu uusi root-elementti.
  5. Lähetä SOAP Envelope. 

WS-rajapinnat

Miksi Web Service -palveluita käytettäessä tulee SSLHandshakeException-poikkeus (tulorekisterin ja varmennepalvelun rajapinta)?

Ongelma liittyy todennäköisesti asiakasohjelmiston käyttämään TLS/SSL-versioon ja niihin liittyviin kryptokirjastoihin. Tulorekisterin ja varmennepalvelun Web Service -rajapinnat käyttävät TLSv1.2:n mukaista protokollaa ja asiakasohjelmiston tulee käyttää samaa versiota. Tiedossa olevat ongelmat:

Java 7 ja sitä vanhemmat versiot → Päivitä käyttöön Java 8 tai uudempi.

SoapUI OpenSource, versio 5.3.0 ja sitä vanhemmat käyttävät vanhentunutta Java-versiota. → Päivitä SoapUI versioon 5.4.0 tai päivitä/korvaa SoapUI:n paketoima Java versioon 8.

SFTP-rajapinnat

Miten tulorekisterin poimimat XML-tiedostot on nimetty OUT-hakemistossa?

OUT-hakemiston tiedostot nimetään muotoon:

<QueryDataType>_<MainSubscriptionId>_<SubscriptionId>_<poiminnan järjestysnumero>_<IRQueryId>_<osatiedostojen kokonaislukumäärä>_<osatiedoston juokseva numero>.xml

Asia on kuvattu seuraavassa dokumentissa: Tekninen rajapinta – Soveltamisohje 2020 (pdf)

Aineistotilaukset

Miksi aineistotilauksen ja vastaussanoman aikaleimat ovat muodoltaan erilaisia? Tilauksessa annamme alla olevat tiedot siitä, mistä haku alkaa ja mihin se päättyy. Ilmoittamamme kellonaika on ymmärtääkseni Suomen aikavyöhykkeessä, kun sen muoto on "+02:00".

<ModifiedTimespanStart>2018-01-01T00:00:00+02:00</ModifiedTimespanStart>

<ValidFrom>2018-05-17</ValidFrom>

<OnetimeDeliverySchedule>

<Time>13:00:00+02:00</Time>

Vastauksessa tuli haettu aikaväli. Siinä muoto on kuitenkin erilainen, sillä siitä puuttuu "+02:00".  

<QueryTimespanStart>2017-12-31T22:00:00Z</QueryTimespanStart>

<QueryTimespanEnd>2018-05-17T11:00:00Z</QueryTimespanEnd>

Miksi vastauksen aikavyöhyke on eri kuin lähetetyn tilauksen aikavyöhyke?

Poiminta-aikaväli tallennetaan tulorekisterin kantaan UTC-ajassa riippumatta siitä, mikä aikavyöhyke tilauksessa on.

Tilauksessa ilmoitettu kellonaika on Suomen talviaikaa, eli UTC-aikaan verrattuna kaksi tuntia enemmän:

<ModifiedTimespanStart>2018-01-01T00:00:00+02:00</ModifiedTimespanStart>

Tulorekisterin kannassa aika on UTC-ajassa eli:

<QueryTimespanStart>2017-12-31T22:00:00Z</QueryTimespanStart>

Poiminnat käynnistyvät aina Suomen ajassa.

Jos käsittelypalautteella palautuu mikä tahansa Error-elementti, MessageErrors, DeliveryErrors tai ItemErrors, tarkoittaako tämä aina sitä, että varsinaista vastaustiedostoa ei voida muodostaa?

Mikäli aineistoon liittyy jokin sanomatason virhe (MessageErrors) tai aineistotason virhe (DeliveryErrors), ei aineistoa pystytä käsittelemään sen pidemmälle. Mikäli aineistosta palautetaan kohdetason virhe (ItemErrors), on sen käsittely mahdollista kelvollisten kohteiden osalta, mikäli aineiston asetukset sen mahdollistavat.

Aineiston lähettäminen

Ottaako tulorekisteri vastaan pakattuja aineistoja?

Tulorekisteri ei ota aineistoja vastaan pakattuna.

Jos aineisto on niin suurikokoinen, että se on lähetettävä useassa osassa, ovatko osa-aineistot itsenäisiä lähetyksiä vai onko niissä oltava jokin tunniste, joka kertoo niiden kuuluvan isompaan kokonaisuuteen?

Jokainen aineisto on oma aineistonsa. Aineistolla ei siis ole erillisiä osia. Ilmoitukselle on mahdollista merkitä versionumero, jonka avulla ilmoittaja saa korjauksensa kohdennettua voimassaolevaan ilmoitukseen. Samassa aineistossa ei kuitenkaan voi olla samaan ilmoitukseen kohdistuvia yhdistelmiä ”uusi-korvaava” tai ”uusi-mitätöinti”.

Jos ilmoituksessa on virhe, miten tulorekisteri käsittelee ilmoituksen?

Teknisen rajapinnan kautta toimitetut virheelliset ilmoitukset hylätään ja palautetaan aina suorituksen maksajalle. Suorituksen maksaja saa käsittelypalautteen mukana tiedon ilmoituksessa havaituista virheistä. Säännöt, joiden mukaan palkkatietoilmoituksen virheettömyys tarkistetaan, on kuvattu dokumentissa ”Tietojen toimittaminen – Skeemat – Palkkatietoilmoitukset”.

Jos virheellinen ilmoitus jää selviteltäväksi tulorekisterissä, saako tiedon käyttäjä mitään tietoa annetusta ilmoituksesta (esimerkiksi tiedonantovelvollisuuden valvontaa varten)?

Jos tulorekisteriin toimitetussa ilmoituksessa on virhe, jonka takia ilmoitus hylätään, ilmoitusta ei tallenneta tulorekisteriin eikä tulorekisteri selvitä sitä. Suorituksen maksaja saa käsittelypalautteen mukana tiedon ilmoituksessa havaituista virheistä. Maksajan on annettava korjattu ilmoitus viiden kalenteripäivän sisällä maksupäivästä.

Tiedon käyttäjille jaetaan vain tulorekisteriin onnistuneesti tallennettuja ilmoituksia. Tiedon käyttäjillä on omat perusrekisteritietonsa, joiden avulla he itse valvovat suorituksen maksajien tiedonantovelvollisuuden täyttämistä. Suorituksen maksaja laiminlyö ilmoitusvelvollisuutensa, mikäli se ei toimita korjattua ilmoitusta määräajassa.

Aineistojen jakelu

Tulorekisteriin on toimitettu poiminta-aikavälillä 1 versio 1, joka on poimittu ensimmäisessä poiminnassa. Toisella poiminta-aikavälillä toimitetaan versiot 2 ja 3. Jos hakukriteeriksi on annettu IncludeAllVersions = ”False”, niin poimitaanko poiminta-aikaväliltä 2 tällöin vain versio 3?

Poimitaan vain versio kolme.

Ovatko korvaaminen ja mitätöinti rinnasteisia tulorekisterin näkökulmasta? Eli jos edellisessä tapauksessa versio 3 olisikin korvauksen sijasta mitätöinti, niin poiminta toimisi samaan tapaan ja vain mitätöinti (versio 3) poimittaisiin?

Kyllä, juuri näin.

Entä tilanteessa, jossa samalla poiminta-aikavälillä on toimitettu versio 1 ja mitätöinti (versio 2). Poimitaanko tällöin IncludeAllVersions = ”False” -kriteerin perusteella sanomalle vain mitätöinti (versio 2)?

Kyllä.

Miten ajastuselementti toimii SFTP-liikenteessä sanomilla? Jos määritän ValidFrom-tietoon kuluvan päivän ja jos kellonaika on kyseisenä päivänä jo mennyt ohi, niin käynnistyykö poiminta heti?

<Schedule>

<OnetimeDeliverySchedule>

<Time>11:00:00+02:00</Time>

</OnetimeDeliverySchedule>

</Schedule>

Jos haluan tehdä ajastuksen seuraavan päivän puolelle aamuyöhön, onko ValidFrom-päivämääräksi määritettävä seuraava päivä?

Jos kertatilauksen ValidFrom-päivämäärä on kuluva päivä ja kellonaika on menneisyydessä, poiminta käynnistyy heti. Eli kertatilaukseen on pantava tulevaisuuden päivämäärä, jos haluaa poiminnan käynnistyvän seuraavana päivänä.

Ajastetussa tilauksessa poiminta käynnistyy ajastuksen mukaisesti seuraavana ajankohtana.

Ilmoitus ja ilmoittaminen

Jos ilmoitus on lähetetty tiedostona, voiko korjaamiseen käyttää eri ilmoituskanavaa, esimerkiksi sähköistä asiointipalvelua?

Kyllä. Tietoja voi lähettää ja korjata eri kanavien kautta. Tietojen korjaamisessa ei tarvitse käyttää samaa ilmoituskanavaa kuin alkuperäisessä ilmoituksessa.

Onko tulorekisterin SFTP-rajapinnan tai Web Service -rajapinnan käyttöajoissa rajoituksia? Voiko tietoja hakea esimerkiksi vain arkisin vai myös juhlapyhinä ja viikonloppuisin?

Teknisen rajapinnan palvelujen käytössä ei ole käyttöaikoihin liittyviä rajoituksia. Palveluja voi käyttää milloin tahansa. Tulorekisterin huoltokatkot, jolloin rajapinnat eivät ole käytettävissä, on ilmoitettu etukäteen. Lue lisää: Tulorekisterin huoltokatkot

Mitä ilmoituksella tarkoitetaan?

Ilmoitus tarkoittaa yhden tulonsaajan yhden maksukerran tietoja. Jos samalla maksukerralla on maksettu useita suorituksia yhdelle palkansaajalle, niistä annetaan vain yksi ilmoitus. Tulolajeja voi olla yhdellä ilmoituksella useita.

Voiko samasta henkilöstä antaa useita ilmoituksia, jos työnantajalla on palkkatietoja monessa eri järjestelmässä?

Kyllä. Samasta henkilöstä voi antaa monta ilmoitusta samalle palkkakaudelle, ja tiedot voidaan ilmoittaa monesta eri järjestelmästä. Kun ilmoituksen toimenpidetyypiksi valitaan ”Uusi”, se ei korvaa edellistä ilmoitusta, vaan kaikki samalla palkkakaudella annetut ilmoitukset jäävät voimaan.

Millä viitetiedoilla korjauksia ja mitätöintejä voi kohdistaa alkuperäisiin ilmoituksiin?

Tulorekisterissä ilmoituksilla voi olla kaksi erillistä yksilöivää viitettä: tulorekisterin ilmoitusviite ja maksajan ilmoitusviite. Tulorekisteri antaa ilmoitukselle automaattisesti tulorekisterin ilmoitusviitteen, kun ilmoitus tallennetaan tulorekisteriin. Lisäksi suorituksen maksajan pitää antaa vapaavalintainen maksajan ilmoitusviite silloin, kun tiedot toimitetaan teknisen rajapinnan tai latauspalvelun kautta. Korjauksia ja mitätöintejä voi kohdistaa alkuperäiseen ilmoitukseen sekä tulorekisterin ilmoitusviitteellä, että maksajan ilmoitusviitteellä.

Mitä tietoja ei voi korjata korvaavalla ilmoituksella? Milloin täytyy mitätöidä aiempi ilmoitus ja antaa uusi ilmoitus?

Tiedot on korjattava mitätöimällä aiempi ilmoitus ja antamalla sen jälkeen uusi ilmoitus seuraavissa tilanteissa:

  • Maksupäivän korjaus
  • Palkanmaksukauden korjaus
  • Suorituksen maksajan ja tulonsaajan asiakastunnisteiden korjaus
  • Tulonsaajan lisätiedon tyypin korjaus, kun muutetaan lisätietoa Urheilija tai Yhteisö
  • Maksajan tyypin korjaus, kun muutetaan tietoa Tilapäinen työnantaja
  • Sijaismaksaja-tietoryhmän varsinaisen työnantajan asiakastunnisteiden korjaus
  • Toimii sijaismaksajana -tiedon korjaus
  • Tulonsaajan syntymäajan korjaus
  • Eläkejärjestelynumeron korjaus
  • Työtapaturmavakuutusyhtiön tunnisteen tai vakuutusnumeron korjaus
  • Vakuuttamisen poikkeustilanteen tyyppi -tietojen korjaukset:
    • Ei vakuuttamisvelvollisuutta -tietojen muutokset taannehtivasti
    • Ei kuulu Suomen sosiaaliturvan soveltamispiiriin -tietojen muutokset taannehtivasti
    • Vapaaehtoinen vakuuttaminen Suomessa (työeläkevakuutus) -tiedon muutos taannehtivasti.

Tietojen mitätöinti kannattaa tehdä vasta, kun uusi ilmoitus saadaan annettua. Suosituksena on, että aiemman ilmoituksen mitätöiminen ja uuden ilmoituksen antaminen tehdään samana päivänä.

Voiko aineiston ja ilmoituksen mitätöinnin antaa samalla palkkatietoilmoituksella, jolla uudet ja korvaavat ilmoitukset annetaan?

Aineiston ja ilmoituksen mitätöintiä ei anneta samalla palkkatietoilmoituksella, jolla uudet ja korvaavat ilmoitukset annetaan. Ilmoitusten mitätöinti on eriytetty omaksi aineistotyypiksi. Tällä aineistotyypillä voidaan mitätöidä yksittäinen ilmoitus, koko palkkatietoaineisto, työnantajan erillisilmoitus tai aineistotilaus. Koska mitätöinti on eriytetty omaksi skeemarakenteekseen, vältetään se, että esimerkiksi yksittäistä palkkatietoilmoitusta mitätöitäessä tarvitsisi antaa palkkatietoilmoituksen pakolliset tiedot.

Tekeekö tulorekisteri samat tietosisältötarkistukset sähköisesti toimitetuille ja paperilla toimitetuille ilmoituksille? Tarkistaako tulorekisteri molemmissa toimituskanavissa esimerkiksi sen, että suorituksen maksaja ja tulonsaaja eivät ole samat?

Tulorekisteri tekee ilmoitukselle samat tietosisältötarkistukset riippumatta ilmoituskanavasta (tekninen rajapinta, sähköinen asiointipalvelu, paperinen asiointi).

Käsittelysääntöjen mukaan ilmoituksen maksaja ja tulonsaaja eivät voi olla samat.