View on GitHub

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
Datasöksystemets frågegränssnitt

Tiedonhakujärjestelmän kyselyrajapintakuvaus

Dokumentin versio 1.0.28

Versiohistoria

Versio Päivämäärä Kuvaus
1.0 21.10.2019 Versio 1.0
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.

Sisällysluettelo

  1. Johdanto
  2. Pankki- ja maksutilitietojen kysely tiedonhakujärjestelmästä
  3. Tietoturva
  4. Tiedonhakujärjestelmän kyselyrajapinta
    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

1. Johdanto

1.1 Termit ja lyhenteet

Lyhenne tai termi Selite
Rajapinta Standardin mukainen käytäntö tai yhtymäkohta, joka mahdollistaa tietojen siirron laitteiden, ohjelmien tai käyttäjän välillä.
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.
Endpoint Rajapintapalvelu, joka on saatavilla tietyssä verkko-osoitteessa
WSDL (Web Service Description Language) Rakenteellinen kuvauskieli, jolla kuvataan web palvelun tarjoamat toiminnallisuudet.

1.2 Dokumentin tarkoitus ja kattavuus

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.

1.3 Viittaukset

Tiedonhakujärjestelmän WSDL

ISO 20022 External Code Sets

ISO 20022 auth.001.001.01 InformationRequestOpeningV01 MDR

ISO 20022 auth.002.001.01 InformationRequestResponseV01 MDR

ISO 20022 head.001.001.01 skeema

fin.002.001.01

fin.012.001.02

fin.013.001.04

Sähköisen asioinnin tietoturvallisuus -ohje

1.4 Yleiskuvaus

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ä.

Pankki- ja maksutilitietojen kysely
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

Muuttuja Kuvaus
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:

  1. Client lähettää kyselysanoman
  2. 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
  3. Client tarkistaa onko vastaussanomassa koodi COMP vai NRES
  4. Jos koodi on COMP, siirrytään kohtaan 10.
  5. Koodi on NRES. Client odottaa POLLING_INTERVAL muuttujan määrittämän ajan ja tekee sen jälkeen kyselyn request #2
  6. Server, joko
    a. Palauttaa hakutuloksen ja koodin COMP, tai
    b. palauttaa vastaussanoman, joka sisältää koodin NRES
  7. Client tarkistaa onko vastaussanomassa koodi COMP vai NRES
  8. Jos koodi on COMP, siirrytään kohtaan 10.
  9. Koodi on NRES. Jos RETRY_LIMIT ei ole saavutettu, siirrytään kohtaan 5.
  10. Loppu.

Taulukossa 2.2. on kuvattu StatusResponse1Code arvojen käyttö

Taulukko 2.2. StatusResponse1Code arvojen käyttö

Koodi Nimi Määritelmä Kuvaus
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ä

3. Tietoturva

3.1 Tunnistaminen

Taulukossa 3.1. on esitetty varmenteet tiedonhakujärjestelmässä.

Taulukko 3.1. Tiedonhakujärjestelmän varmenteet

Standardi Varmenteen nimi Käyttötarkoitus
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ä

joko
a) varmenne on VRK:n myöntämä, voimassa, eikä esiinny VRK:n ylläpitämällä sulkulistalla ja varmenteen kohteen serialNumber attribuuttina on kyseisen tiedon luovuttajan Y-tunnus tai ALV-tunnus

tai
b) varmenne on eIDAS-hyväksytty sivustojen tunnistamisvarmenne, voimassa, eikä esiinny varmenteen tarjoajan ylläpitämällä ajantasaisella sulkulistalla ja varmenteen kohteen organizationIdentifier-attribuuttina on kyseisen tiedon luovuttajan Y-tunnus tai ALV-tunnus.

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:

joko
a) palvelinvarmenteen on myöntänyt VRK, varmenne on voimassa, eikä esiinny VRK:n sulkulistalla, varmenteen kohteen serialNumber attribuuttina on kyseisen tiedon luovuttajan tai tiedon luovuttajan valtuuttaman tahon Y-tunnus tai ALV-tunnus

tai
b) palvelinvarmenne on eIDAS-hyväksytty sivustojen tunnistamisvarmenne, voimassa, eikä esiinny varmenteen tarjoajan ylläpitämällä ajantasaisella sulkulistalla ja varmenteen kohteen organizationIdentifier-attribuuttina on kyseisen tiedon luovuttajan tai tiedon luovuttajan valtuuttaman tahon Y-tunnus tai ALV-tunnus.

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

<SignedInfo>
  <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
  <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
  <Reference URI="">
    <Transforms>
      <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
      <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
    </Transforms>
    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
    <DigestValue />
  </Reference>
</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.

Allekirjoituksessa käytettyjen kryptografisten algoritmien on vastattava kryptografiselta vahvuudeltaan vähintään Viestintäviraston määrittelemiä kryptografisia vahvuusvaatimuksia kansalliselle suojaustasolle ST IV. Tämänhetkiset vahvuusvaatimukset on kuvattu dokumentissa https://www.kyberturvallisuuskeskus.fi/sites/default/files/media/regulation/ohje-kryptografiset-vahvuusvaatimukset-kansalliset-suojaustasot.pdf (Dnro: 190/651/2015).

Mahdollisuus pyyntöjen IP-avaruuden rajoittamiseen tiedonhakujärjestelmässä tarkennetaan myöhemmin.

3.2 Yhteyksien suojaaminen

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.

TLS-salauksessa käytettyjen kryptografisten algoritmien on vastattava kryptografiselta vahvuudeltaan vähintään Viestintäviraston määrittelemiä kryptografisia vahvuusvaatimuksia kansalliselle suojaustasolle ST IV. Tämänhetkiset vahvuusvaatimukset on kuvattu dokumentissa https://www.kyberturvallisuuskeskus.fi/sites/default/files/media/regulation/ohje-kryptografiset-vahvuusvaatimukset-kansalliset-suojaustasot.pdf (Dnro: 190/651/2015).

3.3 Sallittu HTTP-versio

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

Kyselyrajapinta toteutetaan SOAP/XML Web Servicenä, josta julkaistaan WSDL.

SOAP-protokollasta käytetään versiota 1.1.

Sanomissa käytetään ISO 20022 koodistoviittauksia. Koodistoviittaukset löytyvät ISO 20022 sivulta External Code Sets.

Kyselyrajapinnassa on yksi endpoint, jonka kysely- ja vastaussanomarakenne on kuvattu tässä luvussa.

4.1 Kyselyrajapinnan SOAP-operaatioiden sanomarakenne

SOAP body koostuu aina kahdesta osasta, ISO 20022 Business Application Headerista (BAH) ja varsinaisesta business-sanomasta.

4.2 Business Application Header (BAH)

Business Application Header sanoman tiedot on esitetty seuraavassa taulukossa.

Sanoma-id Sanoman nimi
head.001.001.01 Business Application Header

BAH on oltava aina SOAP bodyn ensimmäinen elementti.

4.3 Kyselyrajapinnan sanomat

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ä

Tieto Sanoma(t) Kuvaus
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ä

Tieto Sanoma(t) Kuvaus
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ö
Kiistanalainen auth.002 disputed-skeeman mukainen Supplementary Data

Taulukko 4.3.3: Pankki- ja maksutili, tiedot sanomakohtaisesti eriteltynä

Tieto Sanoma(t) Kuvaus
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
Kiistanalainen auth.002 disputed-skeeman mukainen Supplementary Data

Taulukko 4.3.4: Tallelokero, tiedot sanomakohtaisesti eriteltynä

Tieto Sanoma(t) Kuvaus
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
Kiistanalainen auth.002 disputed-skeeman mukainen Supplementary Data

Taulukko 4.3.5: Asiakkuus, tiedot sanomakohtaisesti eriteltynä

Tieto Sanoma(t) Kuvaus
Asiakkuus fin.013 Ks. InformationResponseFIN013
Alkamispäivämäärä fin.013 Ks. InformationResponseFIN013
Päättymispäivämäärä fin.013 Ks. InformationResponseFIN013
Kiistanalainen auth.002 disputed-skeeman mukainen Supplementary Data

Taulukko 4.3.6: ISO 20022 katalogin mukaiset auth-sanomat

Sanoma-id Sanoman nimi Käyttötarkoitus Vastaava organisaatio Msg Def Report
auth.001.001.01 InformationRequestOpeningV01 Kyselyrajapinnan kyselysanoma FFI MDR
auth.002.001.01 InformationRequestResponseV01 Kyselyrajapinnan vastaussanoma FFI MDR

Taulukko 4.3.7: Kyselysanomaan auth.001 liitettävä alisanoma

Sanoma-id Sanoman nimi Laajennettavan ISO 20022 sanoman id Tarkoitus ja toiminnallisuus
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

Sanoma-id Sanoman nimi Laajennettavan ISO 20022 sanoman id Tarkoitus ja toiminnallisuus
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
FIN013 InformationResponseFIN013 auth.002.001.01 Sisältää tili- ja tallelokerotiedoista erillisenä hakuparametreja vastaavat asiakkuustiedot

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.

4.4 BusinessApplicationHeaderV01

Seuraavassa taulukossa on esitetty BAH-elementtien käyttö. Elementtien tyypit on kuvattu head.001.001.01-skeemassa.

Nimi Tyyppi Käytössä Kuvaus
BusinessApplicationHeaderV01      
CharSet UnicodeChartsCode kyllä “UTF-8”
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)
BizMsgIdr Max35Text kyllä Käyttö standardin mukaisesti.
MsgDefIdr Max35Text kyllä Sisältää sanoma-id:n. Kyselysanomassa käytetään “auth.001.001.01”, vastaussanomassa sisältönä on “auth.002.001.01”
BizSvc   ei  
CreDt ISONormalisedDateTime kyllä BAH:n luomis päivämäärä ja aika. Normalisoitava Z-notaatiolla (UTC).
CpyDplct   ei  
PssblDplct   ei  
Prty   ei  
Sgntr   kyllä Business messagen lähettäjän muodostama XML-allekirjoitus. Ks. XML-allekirjoituksen muodostaminen
Rltd BusinessApplicationHeader1 kyllä Käytössä vastaussanomassa, sisältää kyselysanoman sisältämän BAH:in.

4.5 InformationRequestOpeningV01

Taulukossa on kuvattu sanoman tietueiden käyttö.

Nimi Tyyppi Käytössä Kuvaus
InformationRequestOpeningV01      
    InvstgtnId Max35Text Kyllä Tutkinnan case id
    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).
    CnfdtltySts YesNoIndicator Kyllä Aina “true”
    DueDt DueDate1 Ei  
    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.
    SplmtryData SupplementaryData1 Kyllä Sisältää sanomalaajennuksen InformationRequestFIN012

Haku henkilötunnuksella

Tagi Skeeman polku InfReqOpng/SchCrit/ Kuvaus Sääntö
<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

Tagi Skeeman polku InfReqOpng/SchCrit/ Kuvaus Sääntö  
<Id> CstmrId/Pty/Id/OrgId/Othr Y-tunnus tai muu oikeushenkilön tunniste    
<Cd> CstmrId/Pty/Id/OrgId/Othr/SchmeNm “COID”    
<MsgNmId> CstmrId/AuthrtyReq/Tp “auth.001.001.01”    
<Cd> CstmrId/AuthrtyReq/InvstgtdRoles “ALLP”    

Haku yrityksen nimellä

Tagi Skeeman polku InfReqOpng/SchCrit/ Kuvaus Sääntö
<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”  
<MsgNmId> CstmrId/AuthrtyReq/Tp “auth.001.001.01”  
<Cd> CstmrId/AuthrtyReq/InvstgtdRoles “ALLP”  

Haku IBANilla

Tagi Skeeman polku InfReqOpng/SchCrit/ Kuvaus
<IBAN> Acct/Id/Id IBAN
<MsgNmId> Acct/AuthrtyReqTp “auth.001.001.01”
<Cd> Acct/InvstgtdPties “ALLP”

Haku muulla tilin yksilöintitunnuksella

Tagi Skeeman polku InfReqOpng/SchCrit/ Kuvaus
<Id> Acct/Id/Id/Othr Tilin muu yksilöintitunnus
<Cd> Acct/Id/Id/Othr/SchmeNm OTHR
<MsgNmId> Acct/AuthrtyReqTp “auth.001.001.01”
<Cd> Acct/InvstgtdPties “ALLP”

Haku luonnollisen henkilön nimi, kansalaisuus ja syntymäaika -yhdistelmällä

Tagi Skeeman polku InfReqOpng/SchCrit/ Kuvaus Sääntö
<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”  
<MsgNmId> CstmrId/AuthrtyReq/Tp “auth.001.001.01”  
<Cd> CstmrId/AuthrtyReq/InvstgtdRoles “ALLP”  

Haku Tallelokeron tunnisteella

ISO-sanoman rajoitusten vuoksi Document/InfReqOpng/SchCrit on täytettävä jokin valinta. Täytetään CstmrId:

Tagi Skeeman polku InfReqOpng/SchCrit/ Kuvaus
<Pty> CstmrId Jätetään tyhjäksi
<MsgNmId> CstmrId/AuthrtyReq/Tp “fin.012.001.02”
<Cd> CstmrId/AuthrtyReq/InvstgtdRoles “ALLP”

Varsinainen hakukriteeri, tallelokeron tunniste, asetetaan auth.001.001.01 Supplementary Dataan, fin.012.001.02 sanomalaajennuksen SafetyDepositBoxId-elementtiin seuraavassa taulukossa esitetyllä tavalla.

Tagi Skeeman polku InfReqOpng/SplmtryData/Envlp/ Kuvaus Sääntö
<SafetyDepositBoxId> Document/InfRspnFin012/AdditionalSearchCriteria/ Tallelokeron tunniste Täsmällinen osuma 1:1, ml. erikoismerkit. Formaatti on vapaamuotoinen.

4.6 Sanomalaajennus InformationRequestFIN012

Sanomalaajennus liitetään taulukossa listattuun ISO 20022 sanoman XPath-sijaintiin.

Nimi [min..max] Tyyppi Kuvaus Liitetään sanomaan XPath
InformationRequestFIN012       auth.001 /Document/InfReqOpng/SplmtryData/Envlp
    AuthorityInquiry [1..1] AuthorityInquirySet Kyselyyn liittyvät viranomaisen tiedot    
    AdditionalSearchCriteria [0..*]   Käytetään hakuun tallelokeron tunnisteella.    

AuthorityInquirySet

Nimi [min..max] Tyyppi Kuvaus
AuthorityInquirySet      
    OfficialId [0..1] Max140Text Viranomaisen (henkilön) tunniste
    OfficialSuperiorId [0..1] Max140Text Esimiehen tunniste

4.7 InformationRequestResponseV01

Taulukossa on kuvattu sanoman tietueiden käyttö.

Nimi Tyyppi Käytössä [min..max] Kuvaus
InformationRequestResponseV01        
    RspnId Max35Text Kyllä [1..1] Vastaussanoman id
    InvstgtnId Max35Text Kyllä [1..1] Kyselysanomassa toimitettu Case Id
    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.

XPath Tyyppi Kuvaus
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.

Esimerkki 1.

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:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.013.001.04</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:Rslt>
      <n1:Document xmlns:n3="fin.013.001.04" ...">
      	<n1:InfRspnFin013>
          <!-- Hakutuloksen asiakkuus #1 tiedot -->
        </n1:InfRspnFin013>
      </n1:Document>
    </n1:Rslt>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.002.001.01</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>

Esimerkki 2.

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:

<!-- 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>
          <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:InfRspnSD1>
      </n2:Document>
    </n1:Rslt>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<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>
          <n2:InvstgtnId>a</n2:InvstgtnId>
          <n2:CreDtTm>
            <!-- -->
          </n2:CreDtTm>
          <n2:AcctSvcrId>
            <n2:FinInstnId>
              <n2:Othr>
                <n2:Id>0828972-6</n2:Id>
                <n2:SchmeNm>
                  <n2:Cd>Y</n2:Cd>
                </n2:SchmeNm>
              </n2:Othr>
            </n2:FinInstnId>
          </n2:AcctSvcrId>
          <n2:AcctAndPties>
            <!-- Y-tunnuksen 0828972-6 hakutulokset, tili #2, tili #3, tili #4 -->
          </n2:AcctAndPties>
        </n2:InfRspnSD1>
      </n2:Document>
    </n1:Rslt>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.013.001.04</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.002.001.01</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>

Esimerkki 3.

Kyselysanomassa esiintynyttä Document/InfReqOpng/SchCrit hakutermiä vastaavia tuloksia ei löytynyt.

Vastaussanomaan liitetään kolme kappaletta InvstgtnSts elementtiä 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:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.013.001.04</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.002.001.01</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>

4.8 InformationResponseSD1V01 supl.027.001.01

Taulukossa on kuvattu sanoman tietueiden käyttö.

Nimi Tyyppi Käytössä [min..max] Kuvaus
InformationResponseSD1V01 supl.027.001.01        
    InvstgtnId Max35Text kyllä [1..1] Tutkinnan case-id
    CreDtTm ISODateTime kyllä [1..1] Sanoman luomisaika
    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.
    AcctAndPties AccountAndParties2 kyllä [1..*] Ks. taulukko alla

AccountAndParties2 käyttö

Nimi Tyyppi Käytössä [min..max] Kuvaus
AccountAndParties2        
    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.
    AddtlInf Max256Text kyllä [1..1] Tilin avaamispäivämäärä merkkijonona ISODate-formaatissa

CustomerAccount1 käyttö

Nimi Tyyppi Käytössä [min..max] Kuvaus
CustomerAccount1        
    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
    Nm   ei    
    Sts   ei    
    Tp   ei    
    Ccy   kyllä [1..1] “EUR”
    MnthlyPmtVal   ei    
    MnthlyRcvdVal   ei    
    MnthlyTxNb   ei    
    AvrgBal   ei    
    AcctPurp   ei    
    FlrNtfctnAmt   ei    
    ClngNtfctnAmt   ei    
    StmtCycl   ei    
    ClsgDt ISODate kyllä [0..1] Tilin sulkemispäivämäärä
    Rstrctn   ei    

AccountRole1 käyttö

Nimi Tyyppi Käytössä [min..max] Kuvaus
AccountRole1        
    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ä

4.9 InformationResponseFIN002

Sanomalaajennus liitetään taulukossa listattuun ISO 20022 sanoman XPath-sijaintiin.

Nimi [min..max] Tyyppi Käytetään Kuvaus Liitetään sanomaan XPath
InformationResponseFIN002         auth.002 /Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
    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ö

Nimi Tyyppi Käytössä [min..max] Kuvaus
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ö

Nimi Tyyppi Käytössä [min..max] Kuvaus
CustomerAccount1        
    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ö

Nimi Tyyppi Käytössä [min..max] Kuvaus
AccountRole1        
    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 arvo “OWNE” (tallelokeron haltija, “omistaja”) tai “ACCE” (tallelokeron käyttöoikeuden haltija, “käyttöoikeus”
    StartDt ISODate kyllä [1..1] Roolin alkamispäivämäärä
    EndDt ISODate kyllä [0..1] Roolin päättymispäivämäärä

4.10 InformationResponseFIN013

Sanomalaajennus liitetään taulukossa listattuun ISO 20022 sanoman XPath-sijaintiin.

Nimi Käytetään [min..max] Tyyppi Kuvaus Liitetään sanomaan XPath
InformationResponseFIN013         auth.002 /Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
    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ä|

Beneficiaries käyttö

Nimi Tyyppi Käytössä [min..max] Kuvaus
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ä|

4.11 Id-elementin käyttö

Kaikissa sanomissa käytetään vastaavaa oikeushenkilön ja luonnollisen henkilön tunnistamisrakennetta Id-elementin (Party8Choice) alla. Tässä on kuvattu Id-elementin käyttö kyselyrajapinnassa.

Nimi Tyyppi Käytössä [min..max] Kuvaus
Nm Max140Text Kyllä [1..1] Formaatti vapaamuotoinen.
Id Party8Choice kyllä [1..1]  

Party8Choice

Nimi Tyyppi [min..max] Kuvaus
Party8Choice      
    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.

OrgId koodit

Koodi Kuvaus
Y Y-tunnus
PRH Yhdistysrekisterinumero
COID Muu yritystunnus, tyyppi ei ole tiedossa

PrvtId koodit

Koodi Kuvaus
PIC Suomalainen henkilötunnus
NATI Kansalaisuus
OTHR Muu henkilön tunnistusasiakirjan id

Syntymäaika

Nimi Tyyppi   Kuvaus
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.

<OrgId>
  <Othr>
    <Id>1234567-8</Id>
    <SchmeNm>
      <Cd>Y</Cd>
    </SchmeNm>
  </Othr>
  <Othr>
    <Id>2000-01-01</Id>
    <SchmeNm>
      <Cd>RGDT</Cd>
    </SchmeNm>
    <Issr>Verohallinto</Issr>
  </Othr>
</OrgId>

4.12 Kyselyrajapinnan WS-sanomaliikenteen skenaariot

Tässä luvussa on esitelty kyselyrajapinnan WS-sanomaliikenteen skenaariot.

Skenaario 1 - OK

   
Kuvaus Sanoma käsiteltiin kokonaisuudessaan onnistuneesti.
HTTP status code 202
Seuraamus Palautetaan head.001.001.01 ja auth.002.001.01 sanomat ja mahdolliset alisanomat

Skenaario 2 - Tapahtui virhe

   
Kuvaus Tapahtui virhe
HTTP status code 500
Seuraamus Palautetaan SOAP Fault ks. taulukko alla

Taulukko 4.12.1: Virhekoodit

Virhetilanne faultcode faultstring detail Virhekoodi
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:ClientBad Request

1 kpl ValidationError-elementtiä per validointivirhe esim.

<errorcode>4</errorcode>
<ValidationError>Validaatiovirheen kuvaus</ValidationError>

4
Palvelimen virhe SOAP-ENV:Server Internal Server Error <errorcode>0</errorcode> 0

4.13 Kiistanalaisten tietojen palauttaminen

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">
	<Disputed>
		<DisputedEntityId>
			<Id>290408-616V</Id>
			<Code>PIC</Code>
		</DisputedEntityId>
		<FinancialInstitutionId>
			<Id>0245442-8</Id>
			<Code>Y</Code>
		</FinancialInstitutionId>
	</Disputed>
</Document>

Taulukko 4.13.1: Kiistanalaisten tietojen id-koodit

Koodi Kuvaus
PIC Henkilötunnus
Y Y-tunnus
PRH Yhdistysrekisterinumero
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.

<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="disputed.xsd">
<Disputed>
    <DisputedEntityId>
      <Id>Markkanen, Veikko</Id>
      <Code>NAME</Code>
    </DisputedEntityId>
    <DisputedEntityId>
      <Id>FI</Id>
      <Code>NATI</Code>
    </DisputedEntityId>
    <DisputedEntityId>
      <Id>2008-04-29</Id>
      <Code>BDAT</Code>
    </DisputedEntityId>
    <FinancialInstitutionId>
      <Id>0245442-8</Id>
      <Code>Y</Code>
    </FinancialInstitutionId>
  </Disputed>
</Document>