Versio 1.0 Tietojen toimittaminen Skeemat Viestit Kansallisen tulorekisterin perustamishanke
Tietojen toimittaminen Skeemat Viestit 2 (14) Versiohistoria Versio Päivämäärä Kuvaus 1.0 12.6.2017 Dokumentti julkaistu.
Tietojen toimittaminen Skeemat Viestit 3 (14) SISÄLLYS 1 Yleistä... 4 1.1 Skeema... 4 1.2 Merkistö... 4 1.3 Aikaleimat... 4 1.4 Dokumentin lukuohje... 5 2 Viestit (MessagesToIR)... 6 2.1 Aineiston tiedot (DeliveryDate)... 6 2.2 Viestit (Messages)... 8 2.3 Liitteet (Attachments)... 9 2.4 Yhteyshenkilö (ContactPerson)... 10 2.5 Viestin kohteet (TargetItems)... 11
Tietojen toimittaminen Skeemat Viestit 4 (14) 1 YLEISTÄ 1.1 Skeema Viestit toimitetaan tulorekisteriin skeemalla MessagesToIR. Skeeman nimiavaruudet ovat seuraavat: Tiedoston nimi Prefix Namespace xmlns:xs http://www.w3.org/2001/xmlschema MessagesToIR.xsd xmlns:mtir http://www.tulorekisteri.fi/2017/1/messagestoir MessagesToIRTypes.xsd xmlns:mtirt http://www.tulorekisteri.fi/2017/1/messagestoirtypes IRCommonTypes.xsd xmlns:irct http://www.tulorekisteri.fi/2017/1/ircommontypes Sanomissa ei sallita tyhjiä elementtejä. Jos elementtiin ei tule arvoa, se jätetään sanomalta kokonaan pois. Myöskään tyhjiä merkkijonoja ei sallita, eli kaikkien arvojen pituus on vähintään 1. 1.2 Merkistö Tulorekisterin skeemoissa on käytössä XML:n oletusmerkistö UTF-8. Tiedostossa ei saa olla Byte Order Mark (BOM) -merkkiä. Seuraavassa taulukossa on esitetty sanomissa esiintyvien erikoismerkkien muunnoksiin liittyvät vaatimukset. Merkki Kuvaus Esitysmuoto entiteettinä & et-merkki & muunnos on pakollinen < pienempi kuin < muunnos on pakollinen > suurempi kuin > muunnos ei ole pakollinen, mutta on hyvien käytäntöjen mukaista ' heittomerkki ' muunnos ei ole pakollinen, mutta on hyvien käytäntöjen mukaista " lainausmerkki " muunnos ei ole pakollinen, mutta on hyvien käytäntöjen mukaista -- tupla viiva Merkki ei saa esiintyä xml-tiedostossa /* kauttaviiva asterisk Merkki ei saa esiintyä xml-tiedostossa &# et-merkki risuaitamerkki Merkki ei saa esiintyä xml-tiedostossa 1.3 Aikaleimat Ajat ilmoitetaan UTC-aikoina. Aikaleimoissa ja kellonajoissa tulee olla mukana aikavyöhyke.
Tietojen toimittaminen Skeemat Viestit 5 (14) Esimerkki Suomen aikavyöhykkeessä (UTC+2): <Timestamp>2017-05-11T08:00:00+02:00</Timestamp> <Time>08:00:00+02:00</Time> Esimerkki UTC-ajassa (UTC+0): <Timestamp>2017-05-11T6:00:00Z</Timestamp> <Time>06:00:00Z</Time> 1.4 Dokumentin lukuohje Dokumentin kaavioissa olevien elementtien oikeassa alakulmassa oleva merkintä 0.. tarkoittaa, että elementti voi toistua useita kertoja ja se voi myös puuttua kokonaan. Merkintä 1.. tarkoittaa, että elementti voi toistua useita kertoja, mutta aina vähintään kerran. Pakolliset elementit on merkitty yhtenäisellä reunaviivalla ja vapaaehtoiset elementit katkonaisella reunaviivalla. Dokumentin taulukoissa elementtien pakollisuutta tai vapaaehtoisuutta on kuvattu seuraavilla merkinnöillä: V/P V P V/P Selite Elementti on aina vapaaehtoinen. Elementti on pakollinen siinä tapauksessa, että sen emoelementti on mukana. Elementti on ehdollisesti pakollinen. Tietojen käsittelysäännöissä on kuvattu ne tilanteet, jolloin elementti on pakollinen. Joissakin elementeissä sanomilla käytetään rajoitetun arvoavaruuden arvoja eli koodeja. Elementtien arvoavaruus eli mahdolliset arvot on kuvattu dokumentissa Koodistot. Tässä dokumentissa viitataan koodistossa esiteltyihin arvoihin nimellä koodisto.
Tietojen toimittaminen Skeemat Viestit 6 (14) 2 VIESTIT (MESSAGESTOIR) Tulorekisteriin toimitettavan viestejä sisältävän aineiston yleisrakenne on seuraava: Tiedon nimi Tyyppi V/P Aineiston tiedot (DeliveryData) mtirt:deliverydata P Viestit (Messages) mtirt:messages P Viesti (Message) mtirt:message P Liitteet (Attachments) mtirt:attachments V Liite (Attachment) mtirt:attachment P Yhteyshenkilö (ContactPerson) mtirt:contactperson V Viestin kohteet (TargetItems) mtirt:targetitems V Viestin kohde (TargetItem) mtirt:targetitem P 2.1 Aineiston tiedot (DeliveryDate)
Tietojen toimittaminen Skeemat Viestit 7 (14) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Aineiston tiedot (DeliveryData) mtirt:deliverydata P Aineiston muodostamishetki (Timestamp) xs:datetime P Aineiston tyyppi (DeliveryDataType) xs:int koodisto: DeliveryDataType ja siitä arvo 104 P Aineiston omistajan (viestin lähettäjän) aineistoviite (DeliveryId) Virheellisten tietojen (viestien) käsittelyn ohjaus (FaultyControl) irct:string40 P Jokaisella tietyn lähettäjän (DeliveryDataOwner) viestejä sisältävällä aineistolla (DeliveryDataType=104) tulee olla yksilöllinen aineiston omistajan aineistoviite. xs:int koodisto: FaultyControl P Jos aineisto sisältää virheellisiä ilmoituksia, tiedolla ohjataan sitä, että hylätäänkö aineistosta ainoastaan virheelliset viestit vai hylätäänkö koko aineisto. Tuotantoympäristö (ProductionEnvironment) xs:boolean koodisto: ProductionEnvironment P Aineiston omistaja (DeliveryDataOwner) mtirt:id P Tietoryhmässä tulee antaa aineiston omistajaksi se organisaatio, jonka nimissä viestit lähetetään. Tunnisteen tyyppi (Type) xs:int koodisto: IdType P Tunniste (Code) irct:string30 P Jos Tunnisteen tyyppi on Y-tunnus, tunnisteen on oltava olemassa (Yritys- ja yhteisötietojärjestelmästä (YTJ) saatavien tietojen perusteella). Jos Tunnisteen tyyppi on Suomalainen henkilötunnus, tunnisteen on oltava olemassa (Väestötietojärjestelmästä (VTJ) saatavien tietojen perusteella). Maakoodi (CountryCode) irct:string2 ISO3166-maakoodiston mukainen 2-kirjaiminen koodi. Jos maa on tuntematon, annetaan arvo 99. V/P Pakollinen tieto, jos "Tunnisteen tyyppi" on joku muu kuin Y-tunnus tai Suomalainen henkilötunnus. Maan nimi (CountryName) irct:string70 V/P Pakollinen tieto, jos "Maakoodi" on 99. Aineiston muodostaja (DeliveryDataCreator) mtirt:id P Tunnisteen tyypin, Tunnisteen, Maakoodin ja Maan nimen käsittelysäännöt kuten tietoryhmässä Aineiston omistaja (DeliveryDataOwner). Aineiston lähettäjä (DeliveryDataSender) mtirt:id P Tunnisteen tyypin, Tunnisteen, Maakoodin ja Maan nimen käsittelysäännöt kuten tietoryhmässä Aineiston omistaja (DeliveryDataOwner). Viestit (Messages) mtirt:messages P
Tietojen toimittaminen Skeemat Viestit 8 (14) 2.2 Viestit (Messages) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Viestit (Messages) mtirt:messages P Viesti (Message) mtirt:message P Viestejä voi toimittaa useita. Lähettäjän viestiviite (MessageId) irct:string40 P Lähettäjän viestiviitteen tulee yksilöidä kaikki tietyn lähettäjän (DeliveryDataOwner) viestit. Viestin tyyppi (MessageCategory) xs:int koodisto: MessageCategory V Viestin aihe (SubjectCode) xs:int koodisto: P MessageSubjectCode Sisältö (Content) irct:string4000 P Liitteet (Attachments) mtirt:attachments V Yhteyshenkilö (ContactPerson) mtirt:contactperson V Viestin kohteet (TargetItems) mtirt:targetitems V Viestin tyypin on oltava koodiston mukaan sellainen, jonka osapuoli voi lähettää. Viestin aiheen on oltava koodiston mukaan sellainen, jonka osapuoli voi lähettää.
Tietojen toimittaminen Skeemat Viestit 9 (14) 2.3 Liitteet (Attachments) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Liitteet (Attachments) mtirt:attachments V Liite (Attachment) mtirt:attachment P Liitetiedostoja voi olla enintään 5 kappaletta. Liitetiedosto (AttachmentData) xs:base64binary P Liitetiedosto base64binary muodossa. Liitetiedoston koko saa olla enintään 1Mt. Liitteen tiedot (AttachmentHeader) mtirt:attachmentheade r Liitteen tyyppi (AttachmentType) xs:int koodisto: P AttachmentType Liitteen nimi (AttachmentName) irct:string200 P P
Tietojen toimittaminen Skeemat Viestit 10 (14) 2.4 Yhteyshenkilö (ContactPerson) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Yhteyshenkilö (ContactPerson) mtirt:contactperson V Nimi (Name) irct:string200 P Sähköposti (Email) irct:string70 V Puhelinnumero (Telephone) irct:string40 V
2.5 Viestin kohteet (TargetItems) Tietojen toimittaminen Skeemat Viestit 11 (14)
Tietojen toimittaminen Skeemat Viestit 12 (14) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Viestin kohteet (TargetItems) mtirt:targetitems V Viestin kohde (TargetItem) mtirt:targetitem P Viestin kohteita voi olla useita. Viestin kohde voi olla asiakas, tulotietoilmoitus, viesti, tulorekisteriin toimitettu aineisto tai tulorekisteristä toimitettu aineisto. Viestin kohde on asiakas Viestin kohteen tiedoissa annetaan tietoryhmä Asiakas. Viesti voi kohdistua vain yhteen maksajaan (tietoryhmä Asiakas voi esiintyä viestin kohdetiedoissa vain kerran siten, että Asiakkaan tyyppi on Maksaja ). Viesti voi kohdistua vain yhteen tulonsaajaan (tietoryhmä Asiakas voi esiintyä viestin kohdetiedoissa vain kerran siten, että Asiakkaan tyyppi on Tulonsaaja ). Viesti voi kuitenkin kohdistua sekä maksajaan että tulonsaajaan (tietoryhmä Asiakas voi esiintyä viestin kohdetiedoissa enintään kaksi kertaa). Viestin kohteeksi on annettava myös Maksaja, jos viestillä on kohteena tulotietoilmoitus tai tulorekisteriin toimitettu aineisto. Viestin kohde on tulotietoilmoitus Viestin kohteen tiedoissa annetaan tietoryhmä Tulotietoilmoitus. Viesti voi kohdistua useisiin tulotietoilmoituksiin. Tällöin ilmoituksilla on oltava sama maksaja. Viestin kohteeksi on annettava myös Maksaja tietoryhmässä Asiakas. Viestin kohde on toinen viesti Viestin kohteen tiedoissa annetaan tietoryhmä Viesti. Viesti voi kohdistua useisiin aiemmin lähetettyihin viesteihin. Viestin kohde on tulorekisteriin toimitettu aineisto Viestin kohteen tiedoissa annetaan Tulorekisteriin toimitettu aineisto. Viesti voi kohdistua vain yhteen aineistoon, jonka on oltava palkkatietoaineisto tai työnantajan erillisilmoituksia sisältävä aineisto. Viestin kohteeksi on annettava myös Maksaja tietoryhmässä Asiakas.
Tietojen toimittaminen Skeemat Viestit 13 (14) Asiakas (IdCodeTargetItem) mtirt: IdCodeTargetItem V/P Viestin kohde on tulorekisteristä poimittu aineisto Viestin kohteen tiedoissa annetaan Tulorekisteristä poimittu aineisto. Viesti voi kohdistua useaan tulorekisteristä poimittuun aineistoon. Tietoryhmä annetaan, jos viestin kohde on maksaja tai tulonsaaja. Asiakkaan tyyppi (TargetItemType) xs:int koodisto: P Viestin kohdeasiakkaan tyyppi. MessageIdTargetItemTyp e Asiakkaan tunnisteen tyyppi (Type) xs:int koodisto: IdType P Asiakkaan tunniste (Code) irct:string30 P Jos Tunnisteen tyyppi on Y-tunnus, tunnisteen on oltava olemassa (Yritys- ja yhteisötietojärjestelmästä (YTJ) saatavien tietojen perusteella). Jos Tunnisteen tyyppi on Suomalainen henkilötunnus, tunnisteen on oltava olemassa (Väestötietojärjestelmästä (VTJ) saatavien tietojen perusteella). Tunnisteen maakoodi (CountryCode) irct:string2 ISO3166-maakoodiston mukainen 2-kirjaiminen koodi. Jos maa on tuntematon, annetaan arvo 99. V/P Pakollinen tieto, jos "Tunnisteen tyyppi" on joku muu kuin Y-tunnus tai Suomalainen henkilötunnus. Maan nimi (CountryName) irct:string70 V/P Pakollinen tieto, jos "Maakoodi" on 99. Tulotietoilmoitus (ReportTargetItem) mtirt:reporttargetitem V Tietoryhmä annetaan, jos viestin kohde on tulotietoilmoitus. Kohdistustietona on annettava joko Maksajan ilmoitusviite tai Tulorekisterin ilmoitusviite. Tulotietoilmoituksen tyyppi (TargetItemType) xs:int koodisto: ReportType P Maksajan ilmoitusviite (ReportId) irct:string40 V/P Jos annetaan Maksajan ilmoitusviite, viitteellä on löydyttävä tulorekisteristä Tulotietoilmoituksen tyyppi tiedon mukainen ilmoitus, jossa maksaja on Asiakas -tietoryhmässä kohdistustietona annettu maksaja. Tulorekisterin ilmoitusviite (IRReportId) irct:guid V/P Jos annetaan Tulorekisterin ilmoitusviite, viitteellä on löydyttävä tulorekisteristä Tulotietoilmoituksen tyyppi -tiedon mukainen ilmoitus, jossa maksaja on Asiakas -tietoryhmässä kohdistustietona annettu maksaja. Ilmoituksen versionumero (ReportVersion) xs:int V Versionumeron on oltava nollaa suurempi positiivinen kokonaisluku. Jos versionumero on annettu, tulorekisteristä on löydyttävä Maksajan ilmoitusviite tiedon tai Tulorekisterin ilmoitusviite tiedon perusteella ilmoitus, jonka versionumero vastaa annettua tietoa.
Tietojen toimittaminen Skeemat Viestit 14 (14) Viesti (MessageTargetItem) mtirt:messagetargetite m V Tietoryhmä annetaan, jos viesti kohdistuu aiemmin lähetettyyn viestiin. Kohdistustietona on annettava joko Lähettäjän viestiviite tai Tulorekisterin viestiviite. Lähettäjän viestiviite (MessageId) irct:string40 V/P Jos lähettäjän viestiviite on annettu, viitteellä on löydyttävä tulorekisteristä viestin lähettäjän aiemmin lähettämä viesti. Tulorekisterin viestiviite (IRMessageId) irct:guid V/P Jos tulorekisterin viestiviite on annettu, viitteellä on löydyttävä tulorekisteristä aiemmin lähetetty viesti, jonka lähettäjä/vastaanottaja on viestin lähettäjä. Tulorekisteriin toimitettu aineisto (DeliveryTargetItem) mtirt:deliverytargetite m Aineiston tyyppi (TargetItemType) xs:int koodisto:deliverydatatyp e ja siitä arvot 100, 101 Aineiston toimittajan aineistoviite (DeliveryId) Tulorekisterin aineistoviite (IRDeliveryId) Tulorekisteristä poimittu aineisto (QueryTargetItem) V P Tietoryhmä annetaan, jos viesti kohdistuu tulorekisteriin toimitettuun palkkatietoaineistoon tai työnantajan erillisilmoituksia sisältävään aineistoon. Kohdistustietona on annettava joko Aineiston toimittajan aineistoviite tai Tulorekisterin aineistoviite. irct:string40 V/P Jos annetaan Aineiston toimittajan aineistoviite, viitteellä on löydyttävä tulorekisteristä Aineiston tyyppi -tiedon mukainen aineisto, jossa maksaja on Asiakas -tietoryhmässä kohdistustietona annettu maksaja. irct:guid V/P Jos annetaan Tulorekisterin aineistoviite, viitteellä on löydyttävä tulorekisteristä Aineiston tyyppi -tiedon mukainen aineisto, jossa maksaja on Asiakas -tietoryhmässä kohdistustietona annettu maksaja. mtirt:querytargetitem V Tietoryhmä annetaan, jos viesti kohdistuu tulorekisteristä poimittuun aineistoon. Aineiston tyyppi (TargetItemType) xs:int koodisto:querydatatype P Tulorekisterin poimintaviite (IRQueryId) irct:guid P Tiedon on oltava olemassa oleva tulorekisterin poimintaviite Aineiston tyyppi -tiedon mukaiselle aineistolle.