Dokumentaatio

Dokumentaatio-sivuilla julkaistaan tulorekisterin tekniset ohjeet ja skeemakuvaukset ohjelmistokehittäjille.

 Tarkemmat ilmoittamisen ohjeet ovat​ tulorekisterin yksityiskohtaisissa ohjeissa.

Palkkojen tietosisällön soveltamisohjeet

Tulolajien ohjeessa kuvataan palkkojen tulolajit ja niiden käyttötarkoitukset. Soveltamisohjeissa kuvataan kohta kohdalta, mitä tietoja palkkatietoilmoituksella ja työnantajan erillisilmoituksella annetaan.

Palkkojen tietosisällön soveltamisohjeet
Palkat – uusimmat soveltamisohjeet Viimeisimmät muutokset

Palkat – Tulolajien ja tuloista vähennettävien erien selitteet 2022 (pdf)

  • Julkaistu 1.12.2021
  • Dokumentissa kuvataan
    • tulorekisterissä käytössä olevat palkkatietoilmoituksen tulolajit, tulolajien koodiarvot ja selitteet
    • ennakonpidätyksen toimittaminen ja sosiaalivakuutusmaksujen maksaminen jokaisesta tulolajista
    • tilanteet, joissa palkkatietoilmoituksen tulolajeja käytetään.
  • Tulolajien 216, 330, 358, 403 ja 418 selitteitä on tarkennettu.
  • Tulolajien selitteet on järjestetty tulolajin koodin mukaiseen numerojärjestykseen.
  • Lisäksi useiden selitteiden kuvauksia on yhtenäistetty ja selkeytetty.

Palkkatietoilmoituksen tietosisällön soveltamisohje 2022 (pdf)

  • Julkaistu 5.11.2021 
  • Dokumentissa kuvataan palkkatietoilmoituksen tietosisältö ja mitä tietosisällön kussakin yksittäisessä kohdassa ilmoitetaan.
  • Lisätty tietoryhmään Autoetu (CarBenefit) uusi tieto Auton päästöarvo.

Työnantajan erillisilmoituksen soveltamisohje 2022 (pdf)

  • Julkaistu 7.6.2021
  • Dokumentissa kuvataan työnantajan erillisilmoituksen tietosisältö ja mitä tietosisällön kussakin yksittäisessä kohdassa ilmoitetaan.
  • Julkaistu dokumentista vuoden 2022 tietosisältömuutokset sisältävä versio.
  • Lisätty uusi tietoryhmä Maksajan muut tiedot (PayerOther) tietoryhmään Maksajan tiedot (Payer).

Palkkojen tietosisällön soveltamisohjeiden aiemmat versiot

Etuuksien tietosisällön soveltamisohjeet

Tulolajien ohjeessa  kuvataan etuuksien tulolajit ja niiden käyttötarkoitus. Soveltamisohjeessa kuvataan kohta kohdalta, mitä tietoja etuustietoilmoituksella annetaan.

Etuuksien tietosisällön soveltamisohjeet
Etuudet – uusimmat soveltamisohjeet Viimeisimmät muutokset

Etuudet – Tulolajien ja tuloista vähennettävien erien selitteet 2022 (pdf)

  • Julkaistu 11.3.2022
  • Dokumentissa kuvataan
    • tulorekisteriin ilmoitettavat etuudet ja eläkkeet selitteineen ja koodiarvoineen
    • tilanteet, joissa etuustietoilmoituksen tulolajeja käytetään.
  • Lisätty uudet tulolajit 1422, 1423, 1424 ja 1425.
  • Täydennetty tulolajien 1001, 1002, 1003, 1004 ja 1005 nimiä.

Etuustietoilmoituksen tietosisällön soveltamisohje 2022 (pdf)

  • Julkaistu 25.1.2022
  • Dokumentissa kuvataan etuustietoilmoituksen tietosisältö ja mitä tietosisällön kussakin yksittäisessä kohdassa ilmoitetaan.
  • Tarkennettu etuuden yksikön selitettä yksiköiden määrän osalta.

Etuuksien tietosisällön soveltamisohjeiden aiemmat versiot

Koodistot

Koodistoissa listataan palkkojen ja etuuksien tulolajit, teknisen rajapinnat koodistot, virhekoodit sekä tulorekisterin TK10-ammattiluokitus. Näihin koodistojen arvoihin viitataan muun muassa teknisen rajapinnan yleiskuvauksissa sekä skeemadokumenteissa.

Koodistot
Koodistot - uusimmat koodistot Viimeisimmät muutokset

Palkat - Koodistot - Tulolajit 2022 (xls)

Palkat - Koodistot – Tulolajit 2022 (pdf)

  • Julkaistu 7.6.2021
  • Koodisto sisältää
    • palkkatietoilmoituksen tulolajien ja tuloista vähennettävien erien koodit, ilmoitustavat ja tulolajeissa oletuksena olevat sosiaalivakuutusmaksut
    • työnantajan erillisilmoituksen tulolajien koodit.
  • Julkaistu dokumentista vuoden 2022 tietosisältömuutokset sisältävä versio.
  • Muutoksia sovelletaan, kun tulon maksupäivä on 1.1.2022 tai sen jälkeen.
  • Lisätty Vakuuttamistiedon tyyppi sallittu -arvo tulolajeille 328, 341 ja 363.

Etuudet – Koodistot – Tulolajit 2022 (xls)

Etuudet – Koodistot – Tulolajit 2022 (pdf)

  • Julkaistu 11.3.2022
  • Koodisto sisältää etuustietoilmoituksen tulolajien ja tuloista vähennettävien erien koodit, ilmoitustavat ja lisätietojen pakollisuudet.
  • Lisätty uudet tulolajit 1422, 1423, 1424 ja 1425. Muutettu selitteet tulolajeille 1001, 1002, 1003, 1004 ja 1005.
  • Muutokset tulevat voimaan 1.8.2022. Uusia tulolajeja voi ilmoittaa 45 päivää
    aikaisemmin.

Koodistot 2022 (xls)

Koodistot 2022 (pdf)

  • Julkaistu 11.3.2022
  • Koodisto sisältää tulorekisterin teknisessä rajapinnassa käytettävät koodistot.

 

  • Muutettu koodistossa Palkallisen poissaolon syy (PaidAbsenceCauseCode) arvojen 3 ja 4 selitteet.
  • Muutettu koodistossa Palkattoman poissaolon syy (UnpaidAbsenceCauseCode) arvojen 3 ja 4 selitteet.

Koodistot - Virhekoodit 2022 (xls)

  • Julkaistu 1.11.2021
  • Koodisto sisältää teknisen rajapinnan virhekoodien selitteet.
  • Lisätty virhekoodi: PIV0140.
  • Päivitetty virhekoodin AV0260 selite.

Tulorekisterin TK10-ammattiluokitus (stat.fi)

  • Tulorekisterissä on käytössä Tulorekisterin TK10-ammattiluokitus, joka on julkaistu Tilastokeskuksen sivuilla.
  • Tulorekisterijärjestelmässä koodiston nimi on Tilastokeskuksen ammattiluokitus (TK10).
  • Ammattiluokituksen nimi on muuttunut:
    • uusi nimi Tulorekisterin TK10-ammattiluokitus
    • aiemmin Tilastokeskuksen ammattiluokitus (TK10)

Koodistojen aiemmat versiot

Raportit

Tulorekisteristä voi tilata erilaisia raportteja. Raporttien sisältökuvauksissa kuvataan tilattavat raportit ja niihin liittyvät laskentasäännöt.

Raporttien sisältökuvaukset
Raportit – uusimmat sisältökuvaukset Viimeisimmät muutokset

Raportit tulorekisteristä 2022 (pdf)

  • Julkaistu 10.1.2022
  • Dokumentissa kuvataan tulorekisteristä tuotettavat raportit tiedon tuottajille, tiedon käyttäjille ja tulonsaajille.
  • Korjattu virheellinen merkintä versiohistoriassa: lisätty uusi poimintaehto Vastaanottohetken aikaväli raporteille 600, 614, 618, 620, 630 ja 632.

Tulotiedot - Laskentasääntöjä 2021 (pdf)

  • Julkaistu 7.10.2021
  • Dokumentissa kuvataan, miten tulorekisterin raporttien tiedot lasketaan.
  • Lisätty uusia laskentasääntöjä.

Raporttien sisältökuvausten aiemmat versiot

Tietojen toimittaminen

Tulorekisteriin voi ilmoittaa tietoja teknisen rajapinnan kautta. Silloin puhutaan tietojen toimittamisesta. Ilmoitusten lisäksi rajapinnassa voi lähettää aineistotilauksia ja mitätöidä tietoja.

Tietojen toimittamisen yleiskuvauksessa kuvataan rajapintailmoittamisen toimintaperiaatteet. Skeemadokumenteissa kuvataan sanomien tekninen rakenne ja käsittelysäännöt eli automaattiset tarkistukset, jotka tulorekisteri tekee vastaanotettaville tiedoille.

Myös sähköisen asiointipalvelun latauspalvelun kautta toimitettavan aineiston pitää vastata näitä skeemakuvauksia.

Tietojen toimittamisen sisältökuvaukset
Tietojen toimittaminen – uusimmat sisältökuvaukset Viimeisimmät muutokset

Tekninen rajapinta - Tietojen toimittaminen tulorekisteriin 2021 (pdf)

  • Julkaistu 19.2.2021 
  • Dokumentissa kuvataan 
    • tietojen toimittamista teknisen rajapinnan ja latauspalvelun kautta yleisellä tasolla
    • tulorekisterissä tietoa vastaanottavat palvelut ja lähetettävien aineistojen rakenne
    • tietojen toimittamiseen liittyvät suositukset.
  • Lisätty lukuun 8.1 tieto siitä, että aineistotilauksen voi lopettaa rajapinnan kautta.

Tietojen toimittaminen - Skeemat - Palkkatietoilmoitukset 2022 (pdf)

  • Julkaistu 18.10.2021 
  • Dokumentissa kuvataan skeema WageReportsToIR, jolla palkkatietoilmoitukset toimitetaan tulorekisteriin.

Sanomaesimerkkejä palkkatietoilmoituksen toimittamisesta. Esimerkit on julkaistu 17.9.2021.

  • Tietoryhmässä Autoetu (CarBenefit) lisätty uusi tieto Auton päästöarvo (EmissionsValue) sekä tiedolle käsittelysäännöt.

Tietojen toimittaminen - Skeemat - Työnantajan erillisilmoitukset 2022 (pdf)

  • Julkaistu 7.6.2021
  • Dokumentissa kuvataan skeema PayerSummaryReportsToIR, jolla työnantajan erillisilmoitukset toimitetaan tulorekisteriin.

Sanomaesimerkkejä työnantajan erillisilmoituksen toimittamisesta. Esimerkki on julkaistu 17.9.2021.

  • Julkaistu vuoden 2022 dokumentti.
  • Lisätty uusi tietoryhmä Maksajan muut tiedot (PayerOther) tietoryhmään Maksajan tiedot (Payer).
  • Muutettu tietoryhmän Työeläkevakuutukset (PensionInsurances) tiedon Eläkejärjestelynumero (PensionPolicyNo) käsittelysääntöä.

Tietojen toimittaminen - Skeemat - Etuustietoilmoitukset 2022 (pdf)

  • Julkaistu 7.6.2021
  • Dokumentissa kuvataan skeema BenefitReportsToIR, jolla etuustietoilmoitukset toimitetaan tulorekisteriin.

Sanomaesimerkkejä etuustietoilmoituksen toimittamisesta. Esimerkit on julkaistu 22.2.2021.

  • Julkaistu dokumentista vuoden 2022 tietosisältömuutokset sisältävä versio.
  • Muutoksia sovelletaan, kun tulon maksupäivä on 1.1.2022 tai sen jälkeen.
  • Muutoksia tietoryhmissä Tulolajin yleistiedot (TransactionBasic) ja Takaisinmaksun lisätiedot (RecoveryData).

Tietojen toimittaminen - Skeemat - Aineistotilaukset 2021 (pdf)

  • Julkaistu 1.6.2020 
  • Dokumentissa kuvataan skeema SubscriptionsToIR, jolla aineistotilaukset toimitetaan tulorekisteriin.
  • Julkaistu vuoden 2021 tietosisältömuutokset sisältävä versio.
  • Lisätty tietoryhmässä Alitilaukset (Subscriptions) elementille Aineiston tyyppi (QueryDataType) uusi mahdollinen koodiston arvo 950 (Hylätyt paperilomakkeella annetut ilmoitukset).
  • Poistettu poimintaehdoista (SubscriptionParameters) maininta, että poimintaehtoja voi olla useita. Tietoryhmän päätasolla on kerrottu, että poimintaehtojen
    määrä on aineistotyyppikohtainen.

Tietojen toimittaminen - Skeemat - Mitätöintitiedot 2021 (pdf)

  • Julkaistu 19.2.2021
  • Dokumentissa kuvataan skeema InvalidationsToIR, jolla tulorekisteristä mitätöidään tulotietoilmoituksia, aineistotilauksia ja aineistoja.
  • Täydennetty aineistotilauksen mitätöimisen käsittelysääntöjä luvussa 2.2 Mitätöitävät kohteet.
  • Täydennetty aineistotilauksen mitätöimisen ja lopettamisen käsittelysäännöt.

Tietojen toimittaminen - Skeemat - Vastaanottokuittaus 2021 (pdf)

  • Julkaistu 1.6.2020
  • Dokumentissa kuvataan skeema AckFromIR, jolla tulorekisteri lähettää vastaanottokuittauksen tulorekisteriin toimitetusta aineistosta.
  • Skeemaa käytetään viivästetyssä Web Service -rajapinnassa.
  • Dokumentin sisältö vastaa vuoden 2020 dokumenttia.

Tietojen toimittaminen - Skeemat - Käsittelypalautteen kysely 2021 (pdf)

  • Julkaistu 1.6.2020
  • Dokumentissa kuvataan skeema StatusRequestToIR, jolla aineiston lähettäjä voi kysyä käsittelypalautetta tulorekisteriin lähettämästään aineistosta.
  • Skeemaa käytetään viivästetyssä Web Service -rajapinnassa.
  • Dokumentin sisältö vastaa vuoden 2020 dokumenttia.

Tietojen toimittaminen - Skeemat - Käsittelypalaute 2021 (pdf)

  • Julkaistu 1.6.2020
  • Dokumentissa kuvataan skeema StatusResponseFromIR, jolla tulorekisteri lähettää käsittelypalautteen tulorekisteriin toimitetusta aineistosta.
  • Dokumentin sisältö vastaa vuoden 2020 dokumenttia.

Tietojen toimittamisen sisältökuvausten aiemmat versiot

Tietojen jakelu

Tietojen jakelun dokumentit on suunnattu pääosin tulorekisterin tiedon käyttäjille. Tulorekisteriin tallennettuja tietoja saavat käyttää vain ne viranomaiset ja muut tahot, joilla on siihen lakisääteinen oikeus.

Tietoja jaetaan sähköisen asiointipalvelun ja teknisen rajapinnan kautta. Tietojen jakelun yleiskuvauksessa kuvataan tietojen rajapintakäyttöön liittyvät toimintaperiaatteet. Skeemadokumenteissa kuvataan sanomien tekninen rakenne ja käsittelysäännöt, joissa määritellään, mitä tietoja kussakin elementissä jaetaan.

Tietojen jakelun sisältökuvaukset
Tietojen jakelu – uusimmat sisältökuvaukset Viimeisimmät muutokset

Tekninen rajapinta – Tietojen jakelu tulorekisteristä 2022 (pdf)

  • Julkaistu 26.1.2022
  • Dokumentissa kuvataan
    • tietojen jakelua tulorekisteristä teknisen rajapinnan kautta yleisellä tasolla
    • tulorekisteristä tietoa jakavat palvelut ja jaettavien aineistojen rakenne
    • aineistotilauksen perusteella jaettavien aineistojen poimintaehdot
    • jakeluun liittyvät suositukset
    • suorituksen maksajille tarkoitettu aineisto Maksajan palkkatietojen yhteenveto (312/313).
  • Poistettu luvussa 6.18 Hylätyt paperilomakkeella annetut ilmoitukset tieto SubscriptionId taulukosta
    Alitilauksen tiedot.

Tietojen jakelu - Skeemat - Palkkatietoilmoitukset 2022 (pdf)

  • Julkaistu 18.10.2021
  • Dokumentissa kuvataan skeema WageReportsFromIR, jolla palkkatietoilmoitukset jaetaan tulorekisteristä.
  • Julkaistu dokumentista vuoden 2022 tietosisältömuutokset sisältävä versio.
  • Muutoksia sovelletaan, kun tulon maksupäivä on 1.1.2022 tai sen jälkeen.
  • Lisätty tietoryhmään Autoetu (CarBenefit) uusi tieto Auton päästöarvo (EmissionsValue).

Tietojen jakelu - Skeemat - Työnantajan erillisilmoitukset 2022 (pdf)

  • Julkaistu 3.2.2022
  • Dokumentissa kuvataan skeema PayerSummaryReportsFromIR, jolla työnantajan erillisilmoitukset jaetaan tulorekisteristä.
  • Korjattu tietoryhmässä Maksajan aliorganisaatiot elementin Aliorganisaation tunnisteen tyyppi sallittujen arvojen koodistoksi PayerSubOrgType.

Tietojen jakelu - Skeemat - Etuustietoilmoitukset 2021 (pdf)

  • Julkaistu 7.6.2021
  • Dokumentissa kuvataan skeema BenefitReportsFromIR, jolla etuustietoilmoitukset jaetaan tulorekisteristä.
  • Päivitetty tietoryhmän Palvelun tiedot (ReportData) kuvaan Ilmoitusversion tallennushetki (CreatedTimestamp) pakollisesta vapaaehtoiseksi.

Tietojen jakelu - Skeemat - Palvelupyyntö 2021 (pdf)

  • Julkaistu 1.6.2020
  • Dokumentissa kuvataan skeema DataRequestToIR, jolla tulorekisterin tiedon käyttäjä tekee palvelupyynnön eli kyselee tietoja tulorekisteristä.
  • Skeemaa käytetään reaaliaikaisessa Web Service -rajapinnassa.
  • Dokumentin sisältö vastaa vuoden 2020 dokumenttia.

Tietojen jakelu - Skeemat - Lokitiedot 2021 (pdf)

  • Julkaistu 1.6.2020
  • Dokumentissa kuvataan skeema LogDataFromIR, jolla lokitiedot jaetaan tulorekisteristä.
  • Dokumentin sisältö vastaa vuoden 2020 dokumenttia.

Tietojen jakelu - Skeemat - Maksajan palkkatietojen yhteenveto 2021 (pdf)

  • Julkaistu 1.6.2020
  • Dokumentissa kuvataan skeema WageReportSummaryFromIR, jolla aineisto Maksajan palkkatietojen yhteenveto (312/313) jaetaan tulorekisteristä.
  • Aineisto on tarkoitettu suorituksen maksajille.
  • Dokumentin sisältö vastaa vuoden 2020 dokumenttia.

Tietojen jakelu - Skeemat - Hylätyt paperilomakkeella annetut ilmoitukset 2021 (pdf)

  • Julkaistu 26.1.2022
  • Dokumentissa kuvataan skeema RejectedPaperReportsFromIR, jolla aineisto Hylätyt paperilomakkeella annetut ilmoitukset (950) jaetaan tulorekisteristä.
  • Aineisto sisältää hylätyt paperilomakkeella annetut palkkatietoilmoitukset ja työnantajan erillisilmoitukset.
  • Korjattu tietoryhmässä Ilmoitusten tiedot elementin Aineiston selvitysviite tyypiksi irct:String40.

Tietojen jakelun sisältökuvausten aiemmat versiot

Sovelluskehittäjän ohjeet

Sovelluskehittäjän ohjeet ovat teknisiä ohjeita rajapintojen toteuttajille.

Sovelluskehittäjän ohjeet
Sovelluskehittäjän ohjeet – uusimmat ohjeet Viimeisimmät muutokset

Tekninen rajapinta – Soveltamisohje 2021 (pdf)

  • Julkaistu 24.5.2022
  • Dokumentissa kuvataan tulorekisterin teknisen rajapinnan toteutukseen liittyvät periaatteet järjestelmäintegraation toteuttajan näkökulmasta.
  • Kohtaan 7.1.2 tarkennettu SOAP virheen rakenne.

Tekninen rajapinta – ZIP – Sovelluskehittäjälle 2022 (zip)

Tekninen rajapinta – ZIP – Sovelluskehittäjälle 2022 (pdf)

  • Julkaistu 21.10.2021
  • Zip-tiedosto sisältää skeemojen xsd-kuvaukset ja palvelujen WSDL-kuvaukset.
  • Pdf-dokumentissa kuvataan zip-tiedoston sisältö.
  • Julkaistu dokumentista vuoden 2022 tietosisältömuutokset sisältävä versio.

Tekninen rajapinta – Sanoman allekirjoitus, esimerkkitoteutus (zip)

Tekninen rajapinta – Sanoman allekirjoitus, esimerkkitoteutus (pdf)

  • Julkaistu 23.3.2018
  • Zip-tiedosto sisältää .Net/C#-kielellä laaditun asiakasrajapinnan (client) toteutuksen Echo-palvelun (EchoService) kutsusta ja lähetettävän pyyntösanoman allekirjoittamisesta.
  • Pdf-dokumentissa kuvataan zip-tiedoston sisältö.
 

Sovelluskehittäjän ohjeiden aiemmat versiot