Versio 1.0 Tietojen jakelu Skeemat Viestit Kansallisen tulorekisterin perustamishanke
Tietojen jakelu Skeemat Viestit 2 (20) Versiohistoria Versio Päivämäärä Kuvaus 1.0 12.6.2017 Dokumentti julkaistu.
Tietojen jakelu Skeemat Viestit 3 (20) SISÄLLYS 1 Yleistä... 4 1.1 Skeema... 4 1.2 Merkistö... 4 1.3 Aikaleimat... 4 1.4 Dokumentin lukuohje... 5 2 Viestit (MessagesFromIR)... 6 2.1 Aineistotilauksen tiedot (Subscription)... 8 2.2 Poiminnan tiedot (Query)... 10 2.3 Poiminnan yhteenvetotiedot (Summary)... 11 2.4 Sanomatason virheet (MessageErrors)... 12 2.5 Aineistotason virheet (DeliveryErrors)... 13 2.6 Viestit (Messages)... 14 2.7 Liitteet (Attachments)... 16 2.8 Yhteyshenkilö (ContactPerson)... 17 2.9 Viestin kohteet (TargetItems)... 18
Tietojen jakelu Skeemat Viestit 4 (20) 1 YLEISTÄ 1.1 Skeema Viestit toimitetaan tulorekisteristä skeemalla MessagesFromIR. Skeeman nimiavaruudet ovat seuraavat: Tiedoston nimi Prefix Namespace xmlns:xs http://www.w3.org/2001/xmlschema MessagesFromIR.xsd xmlns:mfir http://www.tulorekisteri.fi/2017/1/messagesfromir MessagesFromIRTypes.xsd xmlns:msfirt http://www.tulorekisteri.fi/2017/1/messagesfromirtypes IRCommonTypes.xsd xmlns:irct http://www.tulorekisteri.fi/2017/1/ircommontypes StatusMessageTypes.xsd xmlns:smt http://www.tulorekisteri.fi/2017/1/statusmessagetypes Sanomissa ei sallita tyhjiä elementtejä. Jos elementtiin ei tule arvoa, se jää 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 jakelu Skeemat Viestit 5 (20) 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 Selite Elementti on aina vapaaehtoinen. Vapaaehtoiseksi merkityt tietoryhmät tai tiedot ovat mukana poimitussa aineistossa, jos ne sisältävät tietoa (tieto on annettu viestissä tai se on tulorekisterin tuottama tieto). Elementti on aina mukana siinä tapauksessa, että sen emoelementti on mukana. Joissakin elementeissä sanomilla käytetään rajoitetun arvoavaruuden arvoja eli koodeja. Koodien arvoavaruus eli mahdolliset arvot on kuvattu dokumenteissa Koodistot. Tässä dokumentissa viitataan koodistoissa esiteltyihin arvoihin nimellä koodisto.
Tietojen jakelu Skeemat Viestit 6 (20) 2 VIESTIT (MESSAGESFROMIR) Tulorekisteristä jaettavan viestejä sisältävän aineiston yleisrakenne on seuraava: Tietoryhmän nimi Tyyppi V/P Aineistotilauksen tiedot (Subscription) mfirt:subscription P Poiminnan tiedot (Query) mfirt:query V Poiminnan yhteenvetotiedot (Summary) mfirt:summary P Sanomatason virheet (MessageErrors) smt:messageerrors V Aineistotason virheet (DeliveryErrors) smt:deliveryerrors V Viestit (Messages) mfirt:messages V Viesti (Message) mfirt:message P Liitteet (Attachments) mfirt:attachments V Liite (Attachment) mfirt:attachment P Viestin kohteet (TargetItems) mfirt:targetitems V Viestin kohde (TargetItem) mfirt:targetitem P
Tietojen jakelu Skeemat Viestit 7 (20) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Aineistotilauksen tiedot (Subscription) mfirt:subscription P Tietoryhmässä toimitetaan aineistotilaukseen tai palvelupyyntöön liittyviä tietoja. Poiminnan tiedot (Query) mfirt:query V Tietoryhmässä toimitetaan poimintaan liittyviä tietoja. Tietoryhmä ei esiinny DataRequestToIR-skeeman mukaisen reaaliaikaisen WSpalvelukutsun vastaussanomalla, jos palvelukutsun käsittelyssä on tapahtunut sanomatason tai aineistotason virhe. Poiminnan yhteenvetotiedot (Summary) mfirt:summary P Tietoryhmässä toimitetaan poimintaan liittyvää summatietoa. Sanomatason virheet (MessageErrors) smt:messageerrors V Tietoryhmä voi esiintyä vain DataRequestToIR-skeeman mukaisen reaaliaikaisen WS-palvelukutsun vastaussanomalla. Aineistotason virheet (DeliveryErrors) smt:deliveryerrors V Tietoryhmä voi esiintyä vain DataRequestToIR-skeeman mukaisen reaaliaikaisen WS-palvelukutsun vastaussanomalla. Viestit (Messages) mfirt:reports V Viestit
Tietojen jakelu Skeemat Viestit 8 (20) 2.1 Aineistotilauksen tiedot (Subscription) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Aineistotilauksen tiedot (Subscription) mfirt:subscription P Tietoryhmässä toimitetaan aineistotilaukseen tai palvelupyyntöön liittyviä tietoja. Aineiston tyyppi (QueryDataType) xs:int koodisto: QueryDataType ja siitä arvo 309. Tuotantoympäristö (ProductionEnvironment) xs:boolean koodisto: ProductionEnvironment Tulorekisterin päätilausviite (IRMainSubscriptionId) P P Aineistotilauksella tai palvelupyynnössä annettu tieto. irct:guid V Tulorekisterin päätilausviite sille päätilaukselle, jonka perusteella aineisto on poimittu. Tietoa ei toimiteta DataRequestToIR-skeeman mukaisen reaaliaikaisen WSpalvelukutsun vastaussanomalla. Tulorekisterin alitilausviite (IRSubscriptionId) irct:guid V Tulorekisterin alitilausviite sille alitilaukselle, jonka perusteella aineisto on poimittu. Tietoa ei toimiteta DataRequestToIR-skeeman mukaisen reaaliaikaisen WSpalvelukutsun vastaussanomalla. Tilaajan päätilausviite (MainSubscriptionId) irct:string40 V Tilaajan päätilausviite sille päätilaukselle, jonka perusteella aineisto on poimittu. Tietoa ei toimiteta DataRequestToIR-skeeman mukaisen reaaliaikaisen WS-
Tietojen jakelu Skeemat Viestit 9 (20) palvelukutsun vastaussanomalla. Tilaajan alitilausviite (SubscriptionId) irct:string40 V Tilaajan alitilausviite sille alitilaukselle, jonka perusteella aineisto on poimittu. Tietoa ei toimiteta DataRequestToIR-skeeman mukaisen reaaliaikaisen WSpalvelukutsun vastaussanomalla.
Tietojen jakelu Skeemat Viestit 10 (20) 2.2 Poiminnan tiedot (Query) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Poiminnan tiedot (Query) mfirt:query V Tietoryhmässä toimitetaan poimintaan liittyviä tietoja. Tulorekisterin poimintaviite (IRQueryId) irct:guid P Tulorekisterin antama viite poimitulle aineistolle. Viite yksilöi kaikki tulorekisteristä poimitut aineistot. Poimintahetki (QueryTimestamp) xs:datetime P Päivä ja kellonaika, jolloin aineisto on poimittu. Muutosten poimintavälin alkuhetki xs:datetime P Päivä ja kellonaika, josta lähtien muuttuneet tiedot aineistoon on poimittu. (QueryTimespanStart) Muutosten poimintavälin loppuhetki (QueryTimespanEnd) xs:datetime P Päivä ja kellonaika, johon asti muuttuneet tiedot aineistoon on poimittu.
Tietojen jakelu Skeemat Viestit 11 (20) 2.3 Poiminnan yhteenvetotiedot (Summary) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Poiminnan yhteenvetotiedot (Summary) mfirt:summary P Tietoryhmässä toimitetaan poimintaan liittyvää summatietoa. Poimittujen kohteiden lukumäärä xs:int P Poimittujen viestien lukumäärä. (NrOfReports)
Tietojen jakelu Skeemat Viestit 12 (20) 2.4 Sanomatason virheet (MessageErrors) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Sanomatason virheet (MessageErrors) smt:messageerrors V Tietoryhmässä palautetaan tekniset ja auktorisointivirheet. Virheen tiedot (ErrorInfo) smt:errorinfo P Virheitä voi olla useita. Virhekoodi (ErrorCode) irct:string20 P Elementissä palautetaan virheen koodi. Tietoryhmä voi esiintyä vain DataRequestToIR-skeeman mukaisen reaaliaikaisen WS-palvelukutsun vastaussanomalla. Virhekoodin selite (ErrorMessage) irct:string500 P Elementissä palautetaan virhekoodin selite. Virheen tarkenne (ErrorDetails) irct:string500 V Elementissä palautetaan virheen kohdistus- ja yksilöintitiedot.
Tietojen jakelu Skeemat Viestit 13 (20) 2.5 Aineistotason virheet (DeliveryErrors) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Aineistotason virheet (DeliveryErrors) smt:deliveryerrors V Tietoryhmässä palautetaan aineistotason tietojen sisältöön liittyvät virheet. Virheen tiedot (ErrorInfo) smt:errorinfo P Virheitä voi olla useita. Virhekoodi (ErrorCode) irct:string20 P Elementissä palautetaan virheen koodi. Tietoryhmä voi esiintyä vain DataRequestToIR-skeeman mukaisen reaaliaikaisen WS-palvelukutsun vastaussanomalla. Virhekoodin selite (ErrorMessage) irct:string500 P Elementissä palautetaan virhekoodin selite. Virheen tarkenne (ErrorDetails) irct:string500 V Elementissä palautetaan virheen kohdistus- ja yksilöintitiedot.
Tietojen jakelu Skeemat Viestit 14 (20) 2.6 Viestit (Messages) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Viestit (Messages) mfirt:messages V Viesti (Message) mfirt:message P Viestejä voi olla useita. Viestin lähetyshetki (Timestamp) xs:datetime P Päivä ja kellonaika, jolloin viesti on tallennettu tulorekisteriin. Tulorekisterin viestiviite (IRMessageId) irct:guid P Tulorekisterin viestille antama viite. Viite yksilöi kaikki tulorekisteriin tallennetut viestit. Viestin tyyppi (MessageCategory) xs:int koodisto: MessageCategory Viestin aihe (SubjectCode) xs:int koodisto: MessageSubjectCode V P
Tietojen jakelu Skeemat Viestit 15 (20) Vastausta odotetaan (ResponseExpected) xs:boolean P Sisältö (Content) irct:string4000 P Liitteet (Attachments) mfirt:attachment V Yhteyshenkilö (ContactPerson) mfirt:contactperson V Viestin kohteet (TargetItems) mfirt:targetitems V
Tietojen jakelu Skeemat Viestit 16 (20) 2.7 Liitteet (Attachments) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Liitteet (Attachments) mfirt:attachments V Liite (Attachment) mfirt:attachment P Liitteitä voi olla useita. Liitetiedosto (AttachmentData) xs:base64binary P Liitetiedosto base64binary muodossa. Liitteen tiedot (AttachmentHeader) mfirt:attachmentheade r Liitteen nimi (AttachmentName) irct:string200 P Liitteen tyyppi (AttachmentType) xs:int koodisto: AttachmentType P P
Tietojen jakelu Skeemat Viestit 17 (20) 2.8 Yhteyshenkilö (ContactPerson) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Yhteyshenkilö (ContactPerson) mfirt:contactperson V Nimi (Name) irct:string200 P Sähköposti (Email) irct:string70 V Puhelinnumero (Telephone) irct:string40 V
2.9 Viestin kohteet (TargetItems) Tietojen jakelu Skeemat Viestit 18 (20)
Tietojen jakelu Skeemat Viestit 19 (20) Tietoryhmän tiedot: Tiedon nimi Tyyppi Sallitut arvot V/P Käsittelysääntö Viestin kohteet (TargetItems) mfirt:targetitems V Viestin kohde (TargetItem) mfirt:targetitem P Viestin kohteita voi olla useita. Viestin kohde voi olla asiakas, tulotietoilmoitus, viesti, tulorekisteriin toimitettu aineisto tai tulorekisteristä toimitettu aineisto. Asiakas (IdCodeTargetItem) mfirt: IdCodeTargetItem Asiakkaan tyyppi (TargetItemType) xs:int koodisto: P MessageIdTargetItemTyp e Asiakkaan tunnisteen tyyppi (Type) xs:int koodisto: IdType P Asiakkaan tunniste (Code) irct:string30 P Tunnisteen maakoodi (CountryCode) irct:string2 ISO3166-maakoodiston V mukainen 2-kirjaiminen koodi. Jos maa on tuntematon, arvo on 99. Maan nimi (CountryName) irct:string70 V Tulotietoilmoitus (ReportTargetItem) mfirt:reporttargetitem V Tulotietoilmoituksen tyyppi xs:int koodisto: ReportType P (TargetItemType) Maksajan ilmoitusviite (ReportId) irct:string40 V Tulorekisterin ilmoitusviite (IRReportId) irct:guid V Ilmoituksen versionumero xs:int V (ReportVersion) Viesti (MessageTargetItem) mfirt:messagetargetite V m Lähettäjän viestiviite (MessageId) irct:string40 V Tulorekisterin viestiviite (IRMessageId) irct:guid V Tulorekisteriin toimitettu aineisto (DeliveryTargetItem) mfirt:deliverytargetite m Aineiston tyyppi (TargetItemType) xs:int 100, 101 P Aineiston toimittajan aineistoviite irct:string40 V (DeliveryId) V V
Tietojen jakelu Skeemat Viestit 20 (20) Tulorekisterin aineistoviite (IRDeliveryId) Tulorekisteristä poimittu aineisto (QueryTargetItem) irct:guid mfirt:querytargetitem Aineiston tyyppi (TargetItemType) xs:int koodisto:querydatatype P Tulorekisterin poimintaviite (IRQueryId) irct:guid V V P