Source: https://finnishcustoms-suomentulli.github.io/account-register-information-query/
Timestamp: 2020-05-24 21:36:23+00:00
Document Index: 18835898

Matched Legal Cases: ['kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ']

account-register-information-query
Käyttöönoton ja ylläpidon ohjeistus tiedonhakujärjestelmä
Deployment and maintenance instructions for the Data Retrieval System
Query interface description of the data retrieval system
Instruktioner för produktionssättning och underhåll av datasöksystemet
Tiedonhakujärjestelmän kyselyrajapintakuvaus
Dokumentin versio 1.0.28
1.0.1 1.11.2019 Päivitetty Investigation Period (InvstgtnPrd, kappale 4.5) käytettäväksi tiedoksi.
1.0.2 1.11.2019 Lisätty WSDL
1.0.3 27.11.2019 Korjattu Ccy-elementin pakollisuustieto
1.0.4 27.11.2019 Lisätty ohjeet ja skeema kiistanalaisten tietojen ilmoittamisesta
1.0.5 18.12.2019 Alisanoma fin.013 Contract-elementti kuvattu. Lisätty taulukot lukuun 4.3 kuvaamaan pankki- ja maksutilirekisterin tietosisältö sanomakohtaisesti eriteltynä. PartyIdentification41 nimikentän formaatti määritelty. Nimihaun ehtoja tarkennettu. Alisanoma fin.012 AdditionalSearchCriteria poistettu virheellinen pakollisuustieto. Poistettu viittaus OTHER-taulukkoon kyselyparametrien yhteydessä. Tarkennettu investigation period kuvausta. Omistaja-koodin abstraktiotasoa nostettu. Role OwnrTp poistettu virheellinen viittaus Cd-elementtiin. Tarkennettu luonnollisen henkilön palautettavia tietoja. Kuvattu SdBoxAndParties käyttö.
1.0.6 21.1.2020 Selvennetty ReturnIndicator1 käyttöä kun hakutuloksia alisanomalle ei löydy.
1.0.7 7.2.2020 Korvattu etunimi ja sukunimi täydellisellä nimellä.
1.0.8 7.2.2020 Poistettu tallelokeron vuokra-ajan alkupäivämäärän pakollisuus
1.0.9 19.2.2020 Muutettu fin013 Beneficiaries-kentän sisällöksi PersonIdentification5, koska vain luonnolliset henkilöt ovat sallittuja
1.0.10 5.3.2020 Vahvistettu, että tallelokero on hakukriteerinä käytössä. Päivitetty XML-allekirjoituksen vaatimuksia. Korjattu SchemeNm muotoon SchmeNm.
1.0.11 5.3.2020 Lainsäädäntöperusteen kuvaus lisätty.
1.0.12 10.3.2020 Päivitetty vastaussanoman kuvausta tiliin liittyvien roolien osalta.
1.0.13 12.3.2020 Täydennetty IBAN ja muu tilin yksilöinti tunniste -hakujen tietueiden käyttöä.
1.0.14 17.3.2020 Päivitetty XML-allekirjoituksen esimerkki.
1.0.15 17.3.2020 Palautettu fin013 Beneficiaries-kentän sisällöksi PartyIdentification41. Muutettu Contract-kenttä optionaaliseksi.
1.0.16 26.3.2020 Päivitetty fin.013 skeema ja sen käyttö.
1.0.17 26.3.2020 Lisätty kuvaus hausta tallelokeron tunnisteella. päivitetty InformationRequestFIN012 versioon fin.012.001.02.
1.0.18 26.3.2020 Päivitetty oikeushenkilön rekisterinumeron käyttö ja kooditus
1.0.19 31.3.2020 Tarkennettu termistöä. Lisätty kuvaus pitkien tilitunnisteiden esitystavasta. Poistettu ylimääräinen tekstikappale. Tarkennuksia varmenteiden osapuolista. Tarkennettu allekirjoitusvaatimuksia.
1.0.20 17.4.2020 Lisätty InformationResponseFIN013 Beneficiary-kentälle roolin alkamis- ja päättymispäivät. Päivitetty InformationResponseFIN013 versioon fin.013.001.03.
1.0.21 20.4.2020 Poistettu mahdollisuus hakea henkilötodistuksen tunnistenumerolla.
1.0.22 24.4.2020 Päivitetty SearchCriteria1Choice-kentän kuvaus kappaleessa 4.5.
1.0.23 29.4.2020 Selvennetty kuvaa 2.1. Pankki- ja maksutilitietojen kysely. Lisätty virhekoodeille numerointi.
1.0.24 5.5.2020 Luvun 4.3 tarkennuksia: maininta luonnollisen henkilön edunsaajatiedosta, maininta tilin osallisista, maininta tallelokeron osallisista.
1.0.25 6.5.2020 Selvennetty etu- ja sukunimien esitystavan rajoituksia liittyen ISO 20022 auth.001-sanomaan.
1.0.26 7.5.2020 Korjattu linkitykset kappaleissa 4.2 ja 4.3.
1.0.27 11.5.2020 Poistettu edunsaajan roolin alkupäivän pakollisuus, päivitetty fin.013 skeema versioon fin.013.001.04.
1.0.28 14.5.2020 Lisätty tarkennus vastaussanomien kokorajoituksiin.
Pankki- ja maksutilitietojen kysely tiedonhakujärjestelmästä
4.1 Kyselyrajapinnan SOAP-operaatioiden sanomarakenne
4.2 Business Application Header (BAH)
4.3 Kyselyrajapinnan sanomat
4.4 BusinessApplicationHeaderV01
4.5 InformationRequestOpeningV01
4.6 InformationRequestFIN012
4.7 InformationRequestResponseV01
4.8 InformationResponseSD1V01
4.9 InformationResponseFIN002
4.10 InformationResponseFIN013
4.11 Id-elementin käyttö
4.12 Kyselyrajapinnan WS-sanomaliikenteen skenaariot
4.13 Kiistanalaisten tietojen palauttaminen
WS (Web Service) Verkkopalvelimessa toimiva ohjelmisto, joka tarjoaa standardoitujen internetyhteyskäytäntöjen avulla palveluja sovellusten käytettäväksi. Tiedonhakujärjestelmä tarjoaa palveluna tietojen kyselyn.
WSDL (Web Service Description Language) Rakenteellinen kuvauskieli, jolla kuvataan web palvelun tarjoamat toiminnallisuudet.
Tämä dokumentti on osa Tullin julkaisemaa määräystä pankki- ja maksutilien valvontajärjestelmästä. Dokumentin tarkoitus on antaa ohjeet tiedonhakujärjestelmän kyselyrajapinnasta. Tätä dokumenttia täydentää tiedonhakujärjestelmän käyttöönoton ja ylläpidon ohje.
Tiedonhakujärjestelmän WSDL
fin.002.001.01
fin.012.001.02
fin.013.001.04
Tulli on perustanut Tilirekisterihankkeen, joka toteuttaa (EU) 2018/843 direktiivin ja sen täytäntöön panemiseksi säädetyn, Suomen lainsäädäntöön perustuvan pankki- ja maksutilien valvontajärjestelmän.
Tässä dokumentissa kuvataan tiedonhakujärjestelmän kyselyrajapinnat.
2. Pankki- ja maksutilitietojen kysely tiedonhakujärjestelmästä
Tässä luvussa on kuvattu pankki- ja maksutilitietojen kysely tiedonhakujärjestelmästä.
Viranomaisten järjestelmissä on olemassa rajoituksia yksittäisen sanoman koolle.
Toimijat voivat käyttöönoton yhteydessä keskenään sopia sanomien kokorajasta sekä keinoista, millä tavoin yksittäisen sanoman kokoa voidaan tarvittaessa pienentää tai vaihtoehtoisesta menetelmästä satunnaisten ylisuurten sanomien toimittamiseen.
Kuvassa 2.1 on esitetty vuokaaviona pankki- ja maksutilitietojen kysely tiedonhakujärjestelmästä.
Kuva2.1. Pankki- ja maksutilitietojen kysely
Kuvasta nähdään, että kyselyrajapinta mahdollistaa sekä vastauksen palauttamisen heti synkronisesti, tai vaihtoehtoisesti asynkronisesti.
Taulukossa 2.1. on esitetty vuokaavion muuttujien merkitys.
Taulukko 2.1. Vuokaavion muuttujat
POLLING_INTERVAL Pollausväli, viive joka clientin on odotettava ennen seuraavaa kyselyä. Jos client pollaa serveriä liian tiheästi, voi server hylätä transaktion käsittelyn (virhekoodi 3, ks 4.12).
RETRY_LIMIT Kuinka monta pollausta on sallittua tehdä, ennen kuin lopetetaan. Jos vastausta ei edelleenkään saada, on joko tehtävä kokonaan uusi kysely tai siirrettävä asia manuaaliseen käsittelyyn.
Taulukossa 2.1. esitettyjen muuttujien kulloinkin voimassa olevat arvot kerrotaan liitedokumentaatiossa.
Kyselyn vuo kulkee seuraavasti:
Client lähettää kyselysanoman
Server voi kyvykkyydestä ja kontekstista riippuen palauttaa hakutulokset joko synkronisesti tai asynkronisesti. Server joko
a. Palauttaa vastaussanoman, joka sisältää hakutuloksen ja koodin COMP, esimerkiksi viiden (5) sekunnin sisällä, tai
b. palauttaa vastaussanoman, joka sisältää koodin NRES
Client tarkistaa onko vastaussanomassa koodi COMP vai NRES
Jos koodi on COMP, siirrytään kohtaan 10.
Koodi on NRES. Client odottaa POLLING_INTERVAL muuttujan määrittämän ajan ja tekee sen jälkeen kyselyn request #2
Server, joko
a. Palauttaa hakutuloksen ja koodin COMP, tai
Koodi on NRES. Jos RETRY_LIMIT ei ole saavutettu, siirrytään kohtaan 5.
Taulukossa 2.2. on kuvattu StatusResponse1Code arvojen käyttö
Taulukko 2.2. StatusResponse1Code arvojen käyttö
COMP CompleteResponse Response is complete. Vastaussanoma sisältää hakutulokset
NRES NoResponseYet Response not provided yet. Vastaussanoma ei sisällä hakutuloksia, tee uusi kysely myöhemmin.
PART PartialResponse Response is partially provided. Ei käytössä
Taulukossa 3.1. on esitetty varmenteet tiedonhakujärjestelmässä.
Taulukko 3.1. Tiedonhakujärjestelmän varmenteet
X.509 (versio 3) Tiedonhakujärjestelmän tietoliikennevarmenne Rajapinnan hyödyntäjän ja tiedon luovuttajan tai tiedon luovuttajan valtuuttaman tahon tunnistaminen
X.509 (versio 3) Tiedonhakujärjestelmän allekirjoitusvarmenne Sanoman allekirjoittaminen, sanoman muuttumattomuuden varmistaminen, tiedon luovuttajan tunnistaminen
Tiedonhakujärjestelmän kyselyrajapinnan hyödyntäjät sekä tiedon luovuttajat tai tiedon luovuttajan valtuuttamat tahot tunnistetaan X.509-varmenteilla (Tietoliikennevarmenne). Kyselyrajapinnan kysely- ja vastaussanomat allekirjoitetaan XML-allekirjoituksella (Allekirjoitusvarmenne).
Tiedon luovuttajan allekirjoitusvarmenne
Tiedon luovuttajan on allekirjoitettava lähettämänsä sanomat käyttäen x.509 palvelinvarmennetta, josta käy ilmi ko. tiedon luovuttajan Y-tunnus tai ALV-tunnus. Saapuvien sanomien allekirjoitus on tarkistettava. Vastaanottaja ei saa hyväksyä sanomaa ilman hyväksyttävää allekirjoitusta. Allekirjoituksen hyväksyminen edellyttää, että XML-allekirjoitus on validi ja että
Toimivaltaisen viranomaisen allekirjoitusvarmenne
Toimivaltaisen viranomaisen on allekirjoitettava lähettämänsä sanomat käyttäen x.509 palvelinvarmennetta, josta käy ilmi ko. viranomaisen Y-tunnus. Saapuvien sanomien allekirjoitus on tarkistettava. Vastaanottaja ei saa hyväksyä sanomaa ilman hyväksyttävää allekirjoitusta. Toimivaltaisen viranomaisen allekirjoituksen hyväksyminen edellyttää, että XML-allekirjoitus on validi ja että
a) varmenne on VRK:n myöntämä, voimassa, eikä esiinny VRK:n ylläpitämällä sulkulistalla
b) varmenteen kohteen serialNumber attribuuttina on tunnus, joka muodostuu kirjaimista “FI” ja sanoman lähettäneen toimivaltaisen viranomaisen Y-tunnuksen numero-osasta ilman väliviivaa (ALV-tunnuksen muotoinen tunnus).
Yhteydenottajan tietoliikennevarmenne
Tiedon luovuttaja tai tiedon luovuttajan valtuuttama taho tunnistaa toimivaltaisen viranomaisen, joka ottaa yhteyden tiedonhakujärjestelmän kyselyrajapintaan, palvelinvarmenteen avulla. Yhteys toimivaltaiselta viranomaiselta on hyväksyttävä seuraavin edellytyksin: a) Toimivaltaisen viranomaisen varmenteen on myöntänyt VRK
b) varmenne on voimassa, eikä esiinny VRK:n sulkulistalla
c) varmenteen kohteen serialNumber attribuuttina on tunnus, joka muodostuu kirjaimista “FI” ja toimivaltaisen viranomaisen tai sen puolesta toimivan valtion palvelukeskuksen Y-tunnuksen numero-osasta ilman väliviivaa (ALV-tunnuksen muotoinen tunnus).
Tiedon luovuttajan tai tiedon luovuttajan valtuuttaman tahon tietoliikennevarmenne
Toimivaltainen viranomainen, joka ottaa yhteyden kyselyrajapintaan, tunnistaa tiedon luovuttajan tai tiedon luovuttajan valtuuttaman tahon palvelinvarmenteen avulla. Tiedon luovuttajan valtuuttamalla taholla tarkoitetaan esim. palvelukeskusta, jonka tiedon luovuttaja on valtuuttanut puolestaan huolehtimaan ilmoitusten muodostamisesta ja/tai lähettämisestä.
Yhteys tiedon luovuttajaan on hyväksyttävä seuraavin edellytyksin:
Mikäli tiedon luovuttajan tietoliikennevarmenteessa ja lähtevän sanoman allekirjoitusvarmenteessa käytetään samaa Y-tunnusta tai ALV-tunnusta, voidaan kumpaankin tarkoitukseen käyttää samaa varmennetta.
XML-allekirjoituksen muodostaminen
Allekirjoituksen tyyppi on enveloped signature. Signature-elementti sijoitetaan BAHin Sgntr-elementin alle.
Esimerkki 3.1. Esimerkki SignedInfo
Allekirjoitusalgoritmi on siis RSA-SHA256 ja C14N on Exclusive XML Canonicalization. Reference URI on “”, eli koko dokumentti allekirjoitetaan. Allekirjoitusta muodostettaessa laskettavien tiivisteiden (Digest) muodostamiseen tulee käyttää SHA256 -algoritmia.
Mahdollisuus pyyntöjen IP-avaruuden rajoittamiseen tiedonhakujärjestelmässä tarkennetaan myöhemmin.
Tiedonhakujärjestelmän kyselyrajapinnan yhteydet on suojattava TLS-salauksella käyttäen TLS-protokollan versiota 1.2 tai korkeampaa. Yhteyden molemmat päät tunnistetaan yllä kuvatuilla palvelinvarmenteilla käyttäen kaksisuuntaista kättelyä. Yhteys on muodostettava käyttäen ephemeral Diffie-Hellman (DHE) avaintenvaihtoa, jossa jokaiselle sessiolle luodaan uusi uniikki yksityinen salausavain. Tämän menettelyn tarkoituksena on taata salaukselle forward secrecy -ominaisuus, jotta salausavaimen paljastuminen ei jälkikäteen johtaisi salattujen tietojen paljastumiseen.
Tiedonhakujärjestelmän kyselyrajapinnan yhteydet käyttävät HTTP-protokollan versiota 1.1.
3.4 Tietoturvapoikkeamien ilmoitusvelvollisuus
Mikäli tiedonhakujärjestelmän toteuttajan varmenteet tai näiden salaiset avaimet vaarantuvat on tästä ilmoitettava välittömästi varmenteen myöntäjälle ja niille toimivaltaisille viranomaisille, jotka hyödyntävät tiedonhakujärjestelmää. Toimivaltaisille viranomaisille on ilmoitettava myös, jos tiedonhakujärjestelmässä havaitaan tietoturvapoikkeama
Mikäli tiedonhakujärjestelmää hyödyntävän toimivaltaisen viranomaisen varmenteet tai näiden salaiset avaimet vaarantuvat on tästä ilmoitettava välittömästi varmenteen myöntäjälle ja niille tiedonhakujärjestelmän toteuttajille, joiden toteutusta tiedonhakujärjestelmästä kyseinen toimivaltainen viranomainen hyödyntää.
4. Tiedonhakujärjestelmän kyselyrajapinta
SOAP-protokollasta käytetään versiota 1.1.
Tiedonhakujärjestelmän kyselyrajapinnassa käytetään ISO 20022 -sanomia InformationRequestOpeningV01 (auth.001.001.01) ja InformationRequestResponseV01 (auth.002.001.01), joihin liitetään tarvittavat alisanomat (Supplementary Data).
Ylätasolla käytettävät alisanomat jakautuvat kolmeen käsitteeseen: asiakkuus, tili ja tallelokero. Asiakkuus- ja edunsaajatiedot palautetaan sanomassa fin.013.001.04, tilitiedot sanomassa supl.027.001.01 ja tallelokerotiedot sanomassa fin.002.001.02 (huom. tässä sama koodi eräiden olemassaolevien järjestelmien manuaalisen käsittelyn kanssa). Nämä alisanomat liitetään auth.002.001.01 elementtiin InformationRequestResponseV01/RtrInd.
Taulukoissa 4.3.1-4.3.5 on esitetty pankki- ja maksutilirekisterin tietosisältö, sekä Supplementary Data -alisanoma, jonka osana kukin tieto palautetaan.
Taulukossa 4.3.6-4.3.8 on esitetty ISO 20022 -katalogin mukaiset auth-sanomat, sekä niihin liitettävät alisanomat.
Tarkemmat sanomakuvaukset ovat tämän luvun aliluvuissa 4.4 alkaen.
Taulukko 4.3.1: Luonnollinen henkilö, tiedot sanomakohtaisesti eriteltynä
Sanoma(t)
Täydellinen nimi fin.002, fin.013, supl.027 Palautetaan rooliin liitetyssä Pty/Nm-elementissä, lähdejärjestelmän formaatissa. Jotta saavutetaan yhteensopivuus olemassaolevien järjestelmien kanssa, on käytettävä yhtä nimikenttää esittämään henkilön kaikki nimet. Tämän elementin formaattia etu- ja sukunimien suhteen ei ole tarkasti määritelty ISO 20022 -sanomatoteutuksissa, jotka on tiedonhakurajapinnan määrittelytyön pohjaksi annettu (auth.001: Document/InfReqOpng/SchCrit/CstmrId/Pty/Nm). Lisäksi on huomioitava, ettei etu- ja/tai sukunimeä esiinny globaalisti kaikilla henkilöillä.
Syntymäaika fin.002, fin.013, supl.027 Palautetaan jos luonnollisella henkilöllä ei ole suomalaista henkilötunnusta. Palautetaan rooliin liitetyn Id-elementin osana ks. Id-elementin käyttö
Henkilötunnus fin.002, fin.013, supl.027 Palautetaan rooliin liitetyn Id-elementin osana ks. Id-elementin käyttö
Kansalaisuudet fin.002, fin.013, supl.027 Palautetaan jos luonnollisella henkilöllä ei ole suomalaista henkilötunnusta. Palautetaan rooliin liitetyn Id-elementin osana ks. Id-elementin käyttö
Edunsaaja fin.013 Organisaatiot, joissa luonnollinen henkilö on edunsaajana
Kiistanalainen auth.002 disputed-skeeman mukainen Supplementary Data
Taulukko 4.3.2: Oikeushenkilö, tiedot sanomakohtaisesti eriteltynä
Nimi fin.002, fin.013, supl.027 Palautetaan rooliin liitetyssä Pty/Nm-elementissä
Rekisterinumero fin.002, fin.013, supl.027 Palautetaan rooliin liitetyn Id-elementin osana ks. Id-elementin käyttö
Rekisteriviranomainen fin.002, fin.013, supl.027 Palautetaan rooliin liitetyn Id-elementin osana ks. Id-elementin käyttö
Rekisteröitymispäivä fin.002, fin.013, supl.027 Palautetaan rooliin liitetyn Id-elementin osana ks. Id-elementin käyttö
Toimijan yksilöivä tunniste fin.002, fin.013, supl.027 Palautetaan rooliin liitetyn Id-elementin osana ks. Id-elementin käyttö
Taulukko 4.3.3: Pankki- ja maksutili, tiedot sanomakohtaisesti eriteltynä
IBAN-numero supl.027 Ks. CustomerAccount-käyttö
Tilin avaamispäivä supl.027 Palautetaan AddtlInf-kentässä
Tilin sulkemispäivä supl.027 Ks. CustomerAccount-käyttö
Tilin osalliset supl.027 Tilin haltijat ja tilin käyttöoikeuden haltijat
Taulukko 4.3.4: Tallelokero, tiedot sanomakohtaisesti eriteltynä
Yksilöintitieto fin.002 ks. SafetyDepositBoxAndParties käyttö
Vuokra-ajan alkamispäivämäärä fin.002 ks. SafetyDepositBoxAndParties käyttö
Vuokra-ajan päättymispäivämäärä fin.002 ks. SafetyDepositBoxAndParties käyttö
Tallelokeron osalliset fin.002 Tallelokeron haltijat ja tallelokeron käyttöoikeuden haltijat
Taulukko 4.3.5: Asiakkuus, tiedot sanomakohtaisesti eriteltynä
Asiakkuus fin.013 Ks. InformationResponseFIN013
Alkamispäivämäärä fin.013 Ks. InformationResponseFIN013
Päättymispäivämäärä fin.013 Ks. InformationResponseFIN013
Taulukko 4.3.6: ISO 20022 katalogin mukaiset auth-sanomat
Taulukko 4.3.7: Kyselysanomaan auth.001 liitettävä alisanoma
FIN012 InformationRequestFIN012 auth.001.001.01 ISO 20022 sanomalaajennus. Kyselyrajapinnan toimivaltaiset viranomaiset käyttävät tätä sanomaa tietojen kyselyyn tiedonhakurajapinnasta. Sisältää kyselyn tekevän henkilön ja henkilön esimiehen tunnisteet. Mahdollistaa auth.001.001.01 puuttuvien hakukriteerien käytön (esim. tallelokero)
Taulukko 4.3.8: Vastaussanomaan auth.002 liitettävät alisanomat
supl.027.001.01 InformationResponseSD1V01 auth.002.001.01 Sisältää hakuparametreja vastaavat tilitiedot
FIN002 InformationResponseFIN002 auth.002.001.01 Sisältää hakuparametreja vastaavat tallelokerotiedot
Kyselyrajapinnan sanomavastauksiin sisällytetään kaikki hakukriteereitä vastaavat tiedot, joiden ajallinen ulottuvuus johdetaan rahanpesun ja terrorismin rahoittamisen estämistä koskevan lain 3 luvun 3 §:stä, jossa on täsmällisesti ja tarkkarajaisesti säädetty asiakkaan tuntemistiedot ja niiden säilyttämisestä. Tileihin ja tallelokeroihin liittyvät kaikki osallisuustiedot palautetaan, eli kyselyparametrina annetun hakuehdon mukaisten henkilöiden (oikeus- tai luonnollinen) lisäksi palautetaan myös kaikki osalliset henkilöt. Osallisten henkilöiden muita kuin kyselyn hakuparametria vastaavia tilejä ja tallelokeroita sen sijaan ei palauteta, vaan niitä koskien on tehtävä uudet kyselyt lainsäädäntöperusteineen.
Fr Party9Choice kyllä Käytetään seuraavasti: Elementti Fr/OrgId/Id/OrgId/Othr/SchmeNm/Cd sisältää arvon “Y” ja elementti Fr/OrgId/Id/OrgId/Othr/Id sisältää lähettäjän Y-tunnuksen.
To Party9Choice kyllä Käytetään seuraavasti: Elementti To/OrgId/Id/OrgId/Othr/SchmeNm/Cd sisältää arvon “Y” ja elementti To/OrgId/Id/OrgId/Othr/Id sisältää vastaanottajan Y-tunnuksen (Esim. Tiedonhakujärjestelmässä Y-tunnus 0245442-8)
Sgntr kyllä Business messagen lähettäjän muodostama XML-allekirjoitus. Ks. XML-allekirjoituksen muodostaminen
LglMndtBsis LegalMandate1 Kyllä Lainsäädäntöperuste. Numeroarvo välillä 100..n. Ensimmäiset numerot kertovat viranomaisen ja kaksi viimeistä numeroa lainsäädäntöperusteen. Lainsäädäntöperusteita kootaan Finanssiala Ry:n kanssa sovitun mukaisesti viranomaisten yhteisesti ylläpitämään kooditaulukkoon. Taulukko toimitetaan tiedonhakujärjestelmän toteuttajille sopimusneuvottelujen yhteydessä (taulukko ei ole julkinen).
InvstgtnPrd DateOrDateTimePeriodChoice Kyllä Päivä tai päivämääräväli, johon haku kohdistuu. Päivämääräväli on aina tänään tai menneisyydessä. Aikavälihaku on sisällyttävä siten, että jos jokin tietosisältöön määritetty aikaväli (kaikki taulukoiden 4.3.1-4.3.5 päivämäärätietueet) sisältyy osittain tai kokonaan annettuun InvstgtnPrd-aikaväliin, on kyseinen tietorivi lisättävä hakutulokseen.
SchCrit SearchCriteria1Choice Kyllä Hakukriteeri. Käytettävä aina mahdollisimman täsmällistä hakukriteeriä. Ks. tarkempi erittely alla.
Haku henkilötunnuksella
Skeeman polku InfReqOpng/SchCrit/
<Id> CstmrId/Pty/Id/Prvtld/Othr Hetu Validi henkilötunnus.
<Cd> CstmrId/Pty/Id/Prvtld/Othr/SchmeNm “PIC” (Person Identification Code, hetu)
<MsgNmId> CstmrId/AuthrtyReq/Tp “auth.001.001.01”
<Cd> CstmrId/AuthrtyReq/InvstgtdRoles “ALLP”
Haku oikeushenkilön rekisterinumerolla
<Id> CstmrId/Pty/Id/OrgId/Othr Y-tunnus tai muu oikeushenkilön tunniste
<Cd> CstmrId/Pty/Id/OrgId/Othr/SchmeNm “COID”
Haku yrityksen nimellä
<Id> CstmrId/Pty/Nm Yrityksen nimi Täsmällinen osuma 1:1
<Id> CstmrId/Pty/Id/OrgId/Othr Arvoksi asetetaan “1”
<Cd> CstmrId/Pty/Id/OrgId/Othr/SchmeNm “NAME”
Haku IBANilla
<IBAN> Acct/Id/Id IBAN
<MsgNmId> Acct/AuthrtyReqTp “auth.001.001.01”
<Cd> Acct/InvstgtdPties “ALLP”
Haku muulla tilin yksilöintitunnuksella
<Id> Acct/Id/Id/Othr Tilin muu yksilöintitunnus
<Cd> Acct/Id/Id/Othr/SchmeNm OTHR
Haku luonnollisen henkilön nimi, kansalaisuus ja syntymäaika -yhdistelmällä
<Nm> CstmrId/Pty Nimi Täsmällinen osuma 1:1, ml. erikoismerkit. Formaatti on vapaamuotoinen.
<Id> CstmrId/Pty/Id/PrvtId/Othr Maakoodi
<Cd> CstmrId/Pty/Id/PrvtId/Othr/SchmeNm “NATI”
<BirthDt> CstmrId/Pty/Id/PrvtId/DtAndPlcOfBirth Syntymäaika. CtryOfBirth arvoksi asetetaan “XX” ja CityOfBirth arvoksi asetetaan ”not in use”
Haku Tallelokeron tunnisteella
ISO-sanoman rajoitusten vuoksi Document/InfReqOpng/SchCrit on täytettävä jokin valinta. Täytetään CstmrId:
<Pty> CstmrId Jätetään tyhjäksi
<MsgNmId> CstmrId/AuthrtyReq/Tp “fin.012.001.02”
Varsinainen hakukriteeri, tallelokeron tunniste, asetetaan auth.001.001.01 Supplementary Dataan, fin.012.001.02 sanomalaajennuksen SafetyDepositBoxId-elementtiin seuraavassa taulukossa esitetyllä tavalla.
Skeeman polku InfReqOpng/SplmtryData/Envlp/
<SafetyDepositBoxId> Document/InfRspnFin012/AdditionalSearchCriteria/ Tallelokeron tunniste Täsmällinen osuma 1:1, ml. erikoismerkit. Formaatti on vapaamuotoinen.
4.6 Sanomalaajennus InformationRequestFIN012
AuthorityInquiry [1..1] AuthorityInquirySet Kyselyyn liittyvät viranomaisen tiedot
AdditionalSearchCriteria [0..*] Käytetään hakuun tallelokeron tunnisteella.
OfficialId [0..1] Max140Text Viranomaisen (henkilön) tunniste
OfficialSuperiorId [0..1] Max140Text Esimiehen tunniste
RspnSts StatusResponse1Code Kyllä [1..1] Vastaussanoman status, “COMP”
SchCrit SearchCriteria1Choice Kyllä [1..1] Kyselysanomassa esiintynyt Document/InfReqOpng/SchCrit sellaisenaan
RtrInd ReturnIndicator1 Kyllä [0..*] ks. ReturnIndicator1 käyttö alla.
SplmtryData SupplementaryData1 Kyllä [0..1] Ks. Kiistanalaisten tietojen palauttaminen
ReturnIndicator1 käyttö
ReturnIndicator1 sisältää yksittäisen hakutulostyypin esiintymän.
RtrInd/AuthrtyReqTp/MsgNmId Max35Text sisältää sanomalaajennuksen sanoma-id:n (supl.027.001.01, fin.013.001.04 tai fin.002.001.01)
RtrInd/InvstgtnRslt InvestigationResult1Choice palautetaan Rslt elementti tyyppiä SupplementaryDataEnvelope1, joka sisältää joko supl.027.001.01, InformationResponseFIN002 tai InformationResponseFIN013 tai InvstgtnSts koodilla NFOU.
Jokaista hakutulostyyppiä kohti palautetaan enintään yksi hakutulos-alisanoma (supl.027.001.01, fin.013.001.04 tai fin.002.001.01) per Y-tunnus.
Kyselysanomassa esiintynyttä Document/InfReqOpng/SchCrit hakutermiä vastaavia tuloksia on löytynyt kolme kappaletta: yksi asiakkuus ja kaksi tiliä. Tallelokeroita ei löytynyt.
Vastaussanomaan liitetään kolme kappaletta RtrInd-elementtiä, joista supl.027.001.01 ja fin.013.001.04 osalta liitetään hakutulokset Rslt-elementteihin ja fin.002.001.01 osalta palautetaan InvstgtnSts koodilla NFOU:
<!-- xmlns:n1="urn:iso:std:iso:20022:tech:xsd:auth.002.001.01" -->
<n1:RtrInd>
<n1:AuthrtyReqTp>
<n1:MsgNmId>supl.027.001.01</n1:MsgNmId>
</n1:AuthrtyReqTp>
<n1:InvstgtnRslt>
<n1:Rslt>
<n2:Document xmlns:n2="urn:iso:std:iso:20022:tech:xsd:supl.027.001.01" ...>
<n2:InfRspnSD1>
<!-- Hakutuloksen tili #1, tili #2 tiedot -->
</n2:InfRspnSD1>
</n2:Document>
</n1:Rslt>
</n1:InvstgtnRslt>
</n1:RtrInd>
<n1:MsgNmId>fin.013.001.04</n1:MsgNmId>
<n1:Document xmlns:n3="fin.013.001.04" ...">
<n1:InfRspnFin013>
<!-- Hakutuloksen asiakkuus #1 tiedot -->
</n1:InfRspnFin013>
</n1:Document>
<n1:MsgNmId>fin.002.001.01</n1:MsgNmId>
<n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
Rajapinta on koosteinen: yksi rajapinta palauttaa hakutuloksia useiden Y-tunnusten alla.
Kyselysanomassa esiintynyttä Document/InfReqOpng/SchCrit hakutermiä vastaavia tuloksia on löytynyt neljä kappaletta: yksi tili (tili #1) Y-tunnukselle 0190983-0 ja kolme tiliä (tili #2, tili #3, tili #4) Y-tunnukselle 0828972-6.
Vastaussanomaan liitetään neljä kappaletta RtrInd-elementtiä, joista supl.027.001.0 osalta liitetään hakutulokset Rslt-elementteihin, ja fin.013.001.04 sekä fin.002.001.01 osalta palautetaan InvstgtnSts koodilla NFOU:
<n2:InvstgtnId>a</n2:InvstgtnId>
<n2:CreDtTm>
</n2:CreDtTm>
<n2:AcctSvcrId>
<n2:FinInstnId>
<n2:Othr>
<n2:Id>0190983-0</n2:Id>
<n2:SchmeNm>
<n2:Cd>Y</n2:Cd>
</n2:SchmeNm>
</n2:Othr>
</n2:FinInstnId>
</n2:AcctSvcrId>
<n2:AcctAndPties>
<!-- Y-tunnuksen 0190983-0 hakutulokset, tili #1-->
</n2:AcctAndPties>
<n2:Id>0828972-6</n2:Id>
<!-- Y-tunnuksen 0828972-6 hakutulokset, tili #2, tili #3, tili #4 -->
Kyselysanomassa esiintynyttä Document/InfReqOpng/SchCrit hakutermiä vastaavia tuloksia ei löytynyt.
Vastaussanomaan liitetään kolme kappaletta InvstgtnSts elementtiä koodilla NFOU.
4.8 InformationResponseSD1V01 supl.027.001.01
AcctSvcrId BranchAndFinancialInstitutionIdentification4 kyllä [1..1] Käytetään seuraavasti: Elementti AcctSvcrId/FinInstnId/Othr/SchmeNm/Cd sisältää arvon “Y” ja elementti AcctSvcrId/FinInstnId/Othr/Id sisältää lähettäjän Y-tunnuksen.
Acct CustomerAccount1 kyllä [1..1] Tilin tiedot ks. CustomerAccount1 käyttö
Role AccountRole1 kyllä [1..*] Tiliin liittyvät roolit ks. toinen taulukko alla. Jokainen rooli on ilmoitettava erikseen, esim. jos luonnollisella henkilöllä on sekä tilin haltijuus että tilin käyttöoikeuden haltijuus tiliin, niin Role-elementtejä on tällöin kaksi kappaletta, joista yhden OwnrTp=OWNE ja toisen OwnrTp=ACCE, ks. AccountRole1 käyttö. Jokaisella roolilla on alkupäivämäärä ja valinnainen loppupäivämäärä. Tämän lisäksi jokaiseen rooliin liittyvä asiakkuus on ilmoitettava fin.013-alisanomassa yhden kerran per osallinen. Em. esimerkin henkilölle ilmoitetaan siis yksi asiakkuus tässä tapauksessa.
Id AccountIdentification4Choice kyllä [1..1] Joko IBAN tai muu tilin tunnistetieto, kts. supl.027.001.01 -skeema. Pitkien tunnusten tapauksessa Acct/Id/Othr/SchmeNm/Cd elementtiin asetetaan koodi GLID (Generic Long Id) ja Acct/Id/Othr/Id arvoksi asetetaan “1”. Varsinainen id (luottokorttitilin numero) asetetaan Acct/Nm-elementtiin
Ccy kyllä [1..1] “EUR”
Pty PartyIdentification41 kyllä [1..*] ks. Id-elementin käyttö
OwnrTp OwnerType1 kyllä [1..1] Käytetään OwnrTp/Prtry/SchmeNm arvolla “RLTP”, sekä OwnrTp/Prtry/Id, jossa arvot “OWNE” (tilin haltija, “omistaja”) tai “ACCE” (tilin käyttöoikeuden haltija, “käyttöoikeus”). Kohtaan OwnrTp/Tp laitetaan arvo “TRUS”, joka ei tässä tarkoita mitään.
StartDt ISODate kyllä [1..1] Roolin alkamispäivämäärä
EndDt ISODate kyllä [0..1] Roolin päättymispäivämäärä
InvstgtnId [1..1] Max35Text kyllä Tutkinnan case-id
CreDtTm [1..1] ISODateTime kyllä Sanoman luomisaika
SvcrId [1..1] BranchAndFinancialInstitutionIdentification4 kyllä Käytetään seuraavasti: Elementti SvcrId/FinInstnId/Othr/SchmeNm/Cd sisältää arvon “Y” ja elementti SvcrId/FinInstnId/Othr/Id sisältää lähettäjän Y-tunnuksen.
SdBoxAndPties [0..*] SafetyDepositBoxAndParties kyllä Tallelokero ja osalliset ks. SafetyDepositBoxAndParties käyttö
SafetyDepositBoxAndParties käyttö
SafetyDepositBoxAndParties
SdBox SdBox kyllä [1..1] Tilin tiedot ks. SdBox käyttö
Role SdBoxRole kyllä [1..*] Tallelokeroon liittyvät roolit ks. toinen taulukko alla. Jokainen rooli on ilmoitettava erikseen koodille OwnrTp=OWNE. Tämän lisäksi jokaiseen rooliin liittyvä asiakkuus on ilmoitettava fin.013-alisanomassa yhden kerran per osallinen.
SdBox käyttö
Id Max34Text kyllä [1..1] Yksilöllinen tallelokeron tunniste
ClsgDt kyllä [0..1] Vuokra-ajan alkupäivämäärä*
ClsgDt kyllä [0..1] Vuokra-ajan päättymispäivämäärä*
*) Vuokra-ajan pituus ilmoitettava joko alkaen pvm, päättyen pvm tai päivämääräväli.
SdBoxRole käyttö
OwnrTp OwnerType1 kyllä [1..1] Käytetään OwnrTp/Prtry/SchmeNm arvolla “RLTP”, sekä OwnrTp/Prtry/Id, jossa arvo “OWNE” (tallelokeron haltija, “omistaja”) tai “ACCE” (tallelokeron käyttöoikeuden haltija, “käyttöoikeus”
InvstgtnId kyllä [1..1] Max35Text Tutkinnan case-id
CreDtTm kyllä [1..1] ISODateTime Sanoman luomisaika
SvcrId kyllä [1..1] BranchAndFinancialInstitutionIdentification4 Käytetään seuraavasti: Elementti SvcrId/FinInstnId/Othr/SchmeNm/Cd sisältää arvon “Y” ja elementti SvcrId/FinInstnId/Othr/Id sisältää lähettäjän Y-tunnuksen.
LegalPersonInfo kyllä [1..*] LegalPersonInfo Oikeushenkilö tai luonnollinen henkilö. Ks. LegalPersonInfo-elementin käyttö taulukko alla
LegalPersonInfo-elementin käyttö
|Nimi|Tyyppi|Käytössä|[min..max]|Kuvaus| |:—|:—|:—|:—|:—| |Id|PartyIdentification41b|Kyllä|[1..1]|Ks. Id-elementin käyttö| |CustomerInfo|CustomerInfo|Kyllä|[0..1]|Asiakkuustiedot. Ks. CustomerInfo-elementin käyttö| |Beneficiaries|Beneficiaries|Kyllä|[0..1]|Edunsaajatiedot. Ks. Beneficiaries-elementin käyttö|
CustomerInfo-elementin käyttö
|Nimi|Tyyppi|Käytössä|[min..max]|Kuvaus| |:—|:—|:—|:—|:—| |OpngDt|ISODate|Kyllä|[1..1]|Asiakkuuden alkupäivämäärä| |ClsgDt|ISODate|Kyllä|[0..1]|Asiakkuuden loppupäivämäärä|
Id Beneficiary kyllä [1..*] Ks. Beneficiary-elementin käyttö
Beneficiary-elementin käyttö
|Nimi|Tyyppi|Käytössä|[min..max]|Kuvaus| |:—|:—|:—|:—|:—| |Nm|Max140Text|Kyllä|[1..1]|Edunsaajan nimi. Formaatti vapaamuotoinen.| |PrvtId|PersonIdentification5b|Kyllä|[1..1]|Luonnollinen henkilö. Ks. PersonIdentification5b-elementin käyttö| |StartDt|ISODate|Kyllä|[0..1]|Roolin alkamispäivämäärä| |EndDt|ISODate|Kyllä|[0..1]|Roolin päättymispäivämäärä|
Nm Max140Text Kyllä [1..1] Formaatti vapaamuotoinen.
OrgId OrganisationIdentification6 [0..1] Käytetään seuraavasti: Elementti OrgId/Othr/SchmeNm/Cd sisältää organisaatiotunnuksen tyyppikoodin ja elementti OrgId/Othr/Id sisältää tunnuksen. Ks. koodit taulukko alla. Lisäksi voidaan kyselyvastauksen yhteydessä palauttaa oikeushenkilön rekisteröitysmispäivämäärä ks. esimerkki alla
PrvtId PersonIdentification5 [0..1] Ks. PersonIdentification5-elementin käyttö
PersonIdentification5- ja PersonIdentification5b-elementtien käyttö
|XPath|Tyyppi|Kuvaus| |:—|:—|:—| |Othr/SchmeNm/Cd|ExternalPersonIdentification1Code|Sisältää henkilötunnisteen tyyppikoodin, tai kansalaisuuskoodin jos henkilöllä ei ole henkilötunnusta.| |Othr/Id|Max35Text|Sisältää tunnuksen tai maakoodin. Ks. koodit taulukko alla.| |DtAndPlcOfBirth|DateAndPlaceOfBirth|Ks. taulukko alla.
Y Y-tunnus
PRH Yhdistysrekisterinumero
COID Muu yritystunnus, tyyppi ei ole tiedossa
PIC Suomalainen henkilötunnus
NATI Kansalaisuus
OTHR Muu henkilön tunnistusasiakirjan id
DtAndPlcOfBirth
BirthDt ISODate Syntymäaika.
CtryOfBirth arvoksi asetetaan “XX”
CityOfBirth arvoksi asetetaan ”not in use”
Esimerkki oikeushenkilön rekisteröitymispäivän palauttamisesta
Oikeushenkilön rekisteröitymispäivämäärä palautetaan tunniste-elementin (esim. Y-tunnus) rinnakkaisena Othr-elementtinä:
Id-elementissä palautetaan rekisteröitymispäivämäärä. SchmeNm/Cd-elementissä palautetaan koodi RGDT, Issr-elementissä palautetaan rekisteriviranomaisen nimi.
<Id>1234567-8</Id>
<Id>2000-01-01</Id>
<Cd>RGDT</Cd>
<Issr>Verohallinto</Issr>
Seuraamus Palautetaan head.001.001.01 ja auth.002.001.01 sanomat ja mahdolliset alisanomat
Skenaario 2 - Tapahtui virhe
Kuvaus Tapahtui virhe
Seuraamus Palautetaan SOAP Fault ks. taulukko alla
Taulukko 4.12.1: Virhekoodit
Asynkronisesti aloitettu kysely on kadonnut SOAP-ENV:Server The query has been lost. Please re-send initial query. <errorcode>1</errorcode> 1
XML-allekirjoitus on virheellinen SOAP-ENV:Client The provided signature is invalid. <errorcode>2</errorcode> 2
Transaktio hylätty liian tiheän pollausvälin johdosta SOAP-ENV:Client Too many requests <errorcode>3</errorcode> 3
Sanomassa on validointivirheitä SOAP-ENV:Client Bad Request
1 kpl ValidationError-elementtiä per validointivirhe esim.
<ValidationError>Validaatiovirheen kuvaus</ValidationError>
Palvelimen virhe SOAP-ENV:Server Internal Server Error <errorcode>0</errorcode> 0
Kyselyvastauksessa esitetyistä tiedoista osa voi olla kiistanalaisia. Tällöin liitetään auth.002.001.01 sanomaan Document/InfReqRspn/SplmtryData-elementin alle disputed.xsd mukainen supplementary data, jossa listataan kiistanalaisten tietueiden tunnisteet.
Listaus 4.13.1: Esimerkki kiistanalaisten tietojen ilmoittamisesta Supplementary Datassa
<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="disputed.xsd">
<DisputedEntityId>
<Id>290408-616V</Id>
<Code>PIC</Code>
</DisputedEntityId>
<FinancialInstitutionId>
<Id>0245442-8</Id>
</FinancialInstitutionId>
</Disputed>
Taulukko 4.13.1: Kiistanalaisten tietojen id-koodit
PIC Henkilötunnus
COID Muu oikeushenkilön tunniste
ACCT Tilin tunniste esim. IBAN
SDBX Tallelokeron tunniste
NAME+NATI+BDAT Erikoistapaus, kun henkilötunnusta ei ole tiedossa. Tällöin on palautettava koko nimi, kansalaisuus ja syntymäaika ks. esimerkki alla
Listaus 4.13.2: Esimerkki kiistanalaisten tietojen ilmoittamisesta Supplementary Datassa. Erikoistapaus, kun henkilötunnusta ei ole tiedossa. Tällöin on palautettava koko nimi, kansalaisuus ja syntymäaika.
<Id>Markkanen, Veikko</Id>
<Id>FI</Id>
<Code>NATI</Code>
<Id>2008-04-29</Id>
<Code>BDAT</Code>
account-register-information-query maintained by FinnishCustoms-SuomenTulli