View on GitHub

Tilirekisteri

Tilirekisterin ja tiedonhakujärjestelmän rajapintakuvaukset

Tilirekisterin ja Tiedonhakujärjestelmän rajapintakuvaus

Dokumentin versio 0.7

English translation

Svensk översättning

Versiohistoria

Versio Päivämäärä Kuvaus Tekijä
0.3 26.4.2019 Alustava versio AP,TV
0.4 9.5.2019 Sanomarakenne päivitetty alustavasti ISO 20022 mukaillen AP
0.5 22.5.2019 Päivityksiä standardinmukaisuuteen liittyen AP
0.6 31.5.2019 Tarkennuksia rajapintakuvauksen käyttöohjeistukseen AP
0.7 10.6.2019 Tarkennus virtuaalivaluutan tarjoajien osalta TV

Sisällysluettelo

  1. Johdanto
    1.1 Termit ja lyhenteet
    1.2 Dokumentin tarkoitus ja kattavuus
    1.3 Viittaukset
    1.4 Yleiskuvaus
  2. Tausta ja kattavuus
    2.1 Tausta
    2.2 Kattavuus
  3. Toimijat ja roolit
  4. Prosessikuvaus
    4.1 Käyttötapauskaavio
    4.2 Prosessien kulku
  5. Aktiviteettien kuvaus
    5.1 Pankki- ja maksutilitietojen toimittaminen
    5.2 Pankki- ja maksutilitietojen kysely
  6. Palvelutaso
    6.1 Saatavuusvaatimukset
    6.2 Käyttökatkoista tiedottaminen
    6.3 Vikatilanteet
  7. Tietoturva
    7.1 Tunnistaminen
  8. Tilirekisterin päivitysrajapinta
  9. Tilirekisterin ja tiedonhakujärjestelmän kyselyrajapinta

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. Tilirekisterin tarjoamia palveluja ovat tietojen toimittaminen, tietopyyntö, ja tietojen kysely. Tiedonhakujärjestelmä tarjoaa palveluna tietojen kyselyn.
Endpoint Rajapintapalvelu, joka on saatavilla tietyssä verkko-osoitteessa

1.2 Dokumentin tarkoitus ja kattavuus

Tämä dokumentti on Pankki- ja maksutilirekisterin valvontajärjestelmän rajapintakuvaus.

1.3 Viittaukset

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

TUVE-väylä

Suomi.fi palveluväylä

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 maksu- ja tilirekisterin valvontajärjestelmän.

Järjestelmä koostuu kahdesta osasta: pankki- ja maksutilirekisteristä sekä tiedonhakujärjestelmästä.

Tässä dokumentissa kuvataan tilirekisterin ja tiedonhakujärjestelmän sanomarajapinnat ja niihin liittyvät kattavuus ja toiminnallisuus, toimijat ja roolit, prosessikuvaus yleisellä tasolla, aktiviteettien kuvaus ja rajapintasanomien käytön määräykset.

2. Tausta ja kattavuus

Tässä luvussa kuvataan tämän dokumentin tausta ja kattavuus.

2.1 Tausta

Euroopan parlamentin ja neuvoston direktiivi (EU) 2018/843 rahoitusjärjestelmän käytön estämisestä rahanpesuun tai terrorismin rahoitukseen annetun direktiivin (EU) 2015/849 ja direktiivien 2009/138/EY ja 2013/36/EU muuttamisesta, jäljempänä viides rahanpesudirektiivi tai direktiivi, annettiin 30 päivänä toukokuuta 2018.

Viidennen Rahanpesudirektiivin ohjaamana on laadittu hallituksen esitys 167/2018 vp pankki- ja maksutilien valvontajärjestelmästä ja eräiksi siihen liittyviksi laeiksi, mikä on hyväksytty eduskunnassa 13.3.2019.

Direktiivin mukaan jäsenvaltioiden olisi perustettava keskitettyjä automatisoituja mekanismeja, jotta pankki- ja maksutilien sekä tallelokeroiden haltijat voidaan kansallisesti tunnistaa.

Tulli on perustanut Tilirekisterihankkeen, joka toteuttaa (EU) 2018/843 direktiivin rahanpesun tai terrorismin rahoituksen estämiseen ja sen täytäntöön panemiseksi säädetyn, Suomen lainsäädäntöön perustuvan maksu- ja tilirekisterin valvontajärjestelmän.

Järjestelmä koostuu kahdesta osasta: pankki- ja maksutilirekisteristä sekä tiedonhakujärjestelmästä.

2.2 Kattavuus

Tilirekisteriin kerätään tietoa maksulaitosten ja sähkörahayhteisöjen asiakastileistä sekä tallelokeroista. Virtuaalivaluutan tarjoajilta pyydetään vain asiakkuustiedot. Luottolaitokset voivat finanssivalvonnalta saadulla poikkeusluvalla tuoda tiedot tilirekisteriin. Tulli toteuttaa Pankki- ja maksutilirekisterin ja sen rajapinnat sekä vastaa sen ylläpidosta. Tiedonhakujärjestelmän osalta Tulli laatii määritykset ja suunnitelman, jotka luottolaitokset ja maksulaitokset toteuttavat laissa määriteltyjen viranomaisten käyttöön.

3. Toimijat ja roolit

Tässä luvussa on esitetty maksu- ja tilirekisterin valvontajärjestelmän rajapintojen toimijat ja roolit.

Seuraavassa taulukossa on esitetty maksu- ja tilirekisterin valvontajärjestelmän rajapintojen toimijat ja roolit.

Taulukko 3.1. Maksu- ja tilirekisterin valvontajärjestelmän rajapintojen toimijat ja roolit

Toimijat Roolit Tiedonhakujärjestelmän rajapinnan toteuttaja Tilirekisterin päivitysrajapinnan tietojen toimittaja Tilirekisterin kyselyrajapinnan hyödyntäjä Tiedonhakujärjestelmän kyselyrajapinnan hyödyntäjä Tilirekisterin toteuttaja
Tiedon hyödyntäjä       x x  
Luottolaitos   a b      
Maksulaitos   c a      
Sähkörahayhteisö   c a      
Virtuaalivaluutan tarjoaja   c a      
Tilirekisteri           x

x) aina
a) lähtökohtaisesti
b) poikkeusluvalla
c) ilmoituksella

Taulukosta nähdään, että toimijoita ovat tiedon hyödyntäjä, luottolaitos, maksulaitos, sähkörahayhteisö, virtuaalivaluutan tarjoaja ja tilirekisteri. Tilirekisteriä edustaa Tulli tilirekisterin toteuttajana.

Taulukosta nähdään, että maksu- ja tilirekisterin valvontajärjestelmän rajapintojen käyttöön liittyy roolit tiedonhakujärjestelmän rajapinnan toteuttaja, tilirekisterin päivitysrajapinnan tietojen luovuttaja, tilirekisterin kyselyrajapinnan hyödyntäjä, tiedonhakujärjestelmän kyselyrajapinnan hyödyntäjä ja tilirekisterin toteuttaja.

Tiedon hyödyntäjät ovat tilirekisterin kyselyrajapinnan ja tiedonhakujärjestelmän kyselyrajapinnan käyttäjiä. Luottolaitokset ovat lähtökohtaisesti tiedonhakujärjestelmän rajapinnan toteuttajia, mutta voivat liittyä Finanssivalvonnan poikkeusluvalla tilirekisterin tietojen toimittajaksi. Maksulaitokset, sähkörahayhteisöt ja virtuaalivaluutan tarjoajat ovat lähtökohtaisesti tilirekisterin tietojen toimittajia, mutta voivat ilmoituksella siirtyä tiedonhakujärjestelmän rajapinnan toteuttajaksi.

4. Prosessikuvaus

Tässä luvussa on esitetty prosessikuvaus. Luvussa 4.1 on esitetty käyttötapauskaavio. Luvussa 4.2 on esitetty Liiketoimintaprosessien kulku ja roolit.

4.1 Käyttötapauskaavio

Kuvassa 4.1 on esitetty käyttötapauskaavio pankki- ja maksutilirekisterin keskeisimmistä liiketoimintaprosesseista.

Käyttötapauskaavio
Kuva 4.1. Käyttötapauskaavio. “Maksulaitos” kattaa maksulaitokset, sähkörahayhteisöt ja virtuaalivaluutan tarjoajat.

Kuvasta nähdään, että tiedon hyödyntäjän käyttötapaukset ovat kyselyn suorittaminen tiedonhakujärjestelmän rajapintaan ja kyselyn suorittaminen tilirekisterin kyselyrajapintaan. Kuvassa “Maksulaitos” kattaa maksulaitokset, sähkörahayhteisöt ja virtuaalivaluutan tarjoajat. Kuvasta nähdään, että Maksulaitoksen käyttötapaus on lähtökohtaisesti sanoman lähettäminen tilirekisterin päivitysrajapintaan, ja toissijaisesti tiedonhakujärjestelmän rajapinnan toteuttaminen. Kuvasta nähdään, että luottolaitoksen ensisijainen käyttötapaus on tiedonhakujärjestelmän rajapinnan toteuttaminen ja toissijaisesti sanoman lähettäminen tilirekisterin päivitysrajapintaan.

4.2 Liiketoimintaprosessien kulku ja roolit

Tilirekisterin ja tiedonhakujärjestelmän liiketoimintaprosessin ensimmäinen tehtävä on rajapintojen käyttöoikeuden hakeminen. Käyttöoikeuden hakemisen tarve rooleittain nähdään taulukoista 3.1 ja 4.2. Käyttöoikeuden hakemiseen liittyy tarvittaessa varmenteen hankkiminen VRK:lta. Käyttöoikeuden myöntämisen tekniset yksityiskohdat on esitetty kappaleessa (Tietoturva).

Tilirekisterin käyttöoikeuden myöntää Tulli.

Tiedonhakujärjestelmän rajapintojen käyttöoikeuden myöntää jokainen rajapinnan toteuttaja erikseen.

Taulukossa 4.2 on listattu pankki- ja maksutilirekisterin liiketoimintaprosessien prosessiaskeleet yleisellä tasolla ja niihin liittyvät roolit.

Taulukko 4.2. Liiketoimintaprosessin askeleet ja roolit

Prosessiaskel Roolit
Rajapintojen käyttöoikeuden hakeminen Tilirekisterin päivitysrajapinnan tietojen luovuttaja, Tilirekisterin kyselyrajapinnan hyödyntäjä, Tiedonhakujärjestelmän kyselyrajapinnan hyödyntäjä
Tilirekisterin rajapintojen käyttöoikeuden myöntäminen Tilirekisteri
Tiedonhakujärjestelmän kyselyrajapinnan käyttöoikeuden myöntäminen Tiedonhakujärjestelmän rajapinnan toteuttaja
Tietojen toimittaminen tilirekisteriin Tilirekisterin päivitysrajapinnan tietojen toimittaja
Tietojen kysely tilirekisterin kyselyrajapinnasta Tilirekisterin kyselyrajapinnan hyödyntäjä
Tietojen kysely tiedonhakujärjestelmän kyselyrajapinnasta Tiedonhakujärjestelmän kyselyrajapinnan hyödyntäjä, Tilirekisterin toteuttaja

5. Aktiviteettien kuvaus

Tässä luvussa on esitettu pankki- ja maksutilitietojen toimittaminen ja pankki- ja maksutilitietojen kysely vuokaavioina.

5.1 Pankki- ja maksutilitietojen toimittaminen tilirekisteriin

Kuvassa 5.1 on esitetty vuokaaviona pankki- ja maksutilitietojen toimittaminen tilirekisteriin.

Pankki- ja maksutilitietojen toimittaminen
Kuva 5.1. Pankki- ja maksutilitietojen toimittaminen

Kuvasta nähdään, että päivitysrajapinta on synkroninen. HTTP-vastauksen bodyssa palautetaan osittain onnistuneen sanoman tapauksessa objekti, joka sisältää tietueet, joiden tallentaminen on epäonnistunut.

5.2 Pankki- ja maksutilitietojen kysely tilirekisteristä ja tiedonhakujärjestelmästä

Kuvassa 5.2 on esitetty vuokaaviona pankki- ja maksutilitietojen kysely tilirekisteristä ja tiedonhakujärjestelmästä.

Pankki- ja maksutilitietojen kysely
Kuva5.2. Pankki- ja maksutilitietojen kysely

Kuvasta nähdään, että kyselyrajapinta on asynkroninen. Tietojen kysyminen tapahtuu kahdella SOAP-sanomalla. Ensimmäisessä sanomassa lähetetään kyselyparametrit ja muut vaaditut tiedot. Vaadittavat tiedot on listattu luvussa 9. Ensimmäisen sanoman vastaussanoma sisältää kyselytunnisteen, jonka perusteella vastaus on noudettavissa määrätyn ajan kuluttua. Määrätty aika on listattu kappaleessa 7.

6. Palvelutaso

6.1 Saatavuusvaatimukset

Tarkentuu.

Kyselyvastaus on oltava noudettavissa yhden (1) sekunnin kuluttua.

Kyselyrajapinta on oltava saatavilla 99,95 % ajasta. Kyselyrajapinta on oltava saatavilla 99,999 % ajasta kello 06:00-00:00 välillä. Saatavuusvaatimuksen toteutuminen lasketaan keskiarvona kalenterikuukausittain.

6.2 Käyttökatkoista tiedottaminen

Palvelun käyttökatkokäytännöt, huoltokatkoista tiedottamiset.

Tarkentuu.

6.3 Vikatilanteet

Palvelun vikatilanteet, uusintakyselyt kuinka kauan odotetaan uuden kyselyn välissä, kuinka monta kyselyä maksimissaan, manuaalinen yhteyspiste jos viimeinenkin kutsukerta epäonnistuu.

Tarkentuu.

7. Tietoturva

7.1 Tunnistaminen

Tarkentuu.

Tilirekisterin ja Tiedonhakujärjetestelmän kyselyajapinnan hyödyntäjät tunnistetaan VRK:n myöntämillä X.509-sertifikaateilla. Kyselyrajapinnan Sanomat allekirjoitetaan XML-allekirjoituksella. Päivitysrajapinnan sanomat allekirjoitetaan JWS-allekirjoituksella (PKI). Tarkempi sanomien allekirjoitusten kuvaus lisätään tähän dokumenttiin myöhemmin.

Tilirekisterin rajapintaan on saatavissa pääsy Suomi.fi palveluväylän kautta. Osa tiedon hyödyntäjistä käyttää Tilirekisterin rajapintaa TUVE-väylän kautta.

Mahdollisuus pyyntöjen IP-avaruuden rajoittamiseen tiedonhakujärjestelmässä tarkentuu.

8. Tilirekisterin päivitysrajapinnan yleiskuvaus

Päivitysrajapinta toteutetaan REST/JSON-menetelmällä.

Rajapinnan käyttäjän (tiedon luovuttajan) on lähetettävä vähintään yksi (1) minimisanoma (ks. alla *-merkityt kentät täytetty) kerran kuukaudessa (watchdog timer reset). Jos yhtään viestiä ei toimiteta kuukauden kuluessa, lähetetään sähköposti-ilmoituksena vianselvittämispyyntö. Tämän jälkeen odotetaan kaksi (2) viikkoa. Jos kahden viikon kuluessa ei toimiteta vähintään yhtä minimisanomaa, rajapinnan käyttö evätään oletuksella, että yhteys on katkennut.

Kyselysanomat allekirjoitetaan JWS-allekirjoituksella (PKI, tarkentuu myöhemmin).

Jokaisessa sanomassa tulee olla mukana luontipäivämäärä.

Jokaisen sanoman tulee sisältää tietojen toimittajan Y-tunnus senderBusinessId propertyssa.

Erikseen määriteltyjen (ks. alla) tietueiden tulee sisältää servicerIssuedId property, joka on mikä tahansa tietojen toimittajan antama hyvien tapojen mukainen yksiselitteinen tunniste tietueelle merkkijonona. Esimerkiksi UUIDv4 on hyvä servicerIssuedId. Tämän propertyn perusteella tietueet pystytään tunnistamaan esimerkiksi henkilön nimen tai hetun vaihtuessa.

Tili-, asiakkuus-, ja tallelokeroihin liittyvät roolitiedot ja henkilötiedot voidaan merkitä virheelliseksi asettamalla disputed property arvoon true. Tällöin uusin versio tiedosta merkitään “virheelliseksi ilmoitettu” -tilaan alkaen sanoman saapumispäivämäärästä.

Sanomassa tulee olla mukana sarjanumero. Sarjanumeroa käytetään varmistamaan, ettei sanomia ole jäänyt saapumatta.

Seuraavassa taulukossa on listattu rajapinnan endpointit.

HTTP-metodi Polku Tarkoitus ja toiminnallisuus
POST /information-update Tietojen toimitusvelvolliset (Maksulaitokset, sähkörahayhteisöt, virtuaalivaluutan tarjoajat tai finanssivalvonnalta saadulla poikkeusluvalla luottolaitokset) käyttävät tätä endpointia asiakkuuksien, asiakastilien sekä tallelokeroiden tietojen toimittamiseen tilirekisteriin.

Endpointia käytetään tietojen toimittamiseen tilirekisteriin. Sanomassa toimitetaan tiedot asiakkuuksista, tileista ja tallelokeroista. Jos tilejä tai tallelokeroita ei ole, toimitetaan pelkät asiakkuustiedot. Virtuaalivaluutan tarjoajat toimittavat vain asiakkuustiedot.

Notaatio

Rajapintatietueiden rakenteiseen kuvaukseen käytetään seuraavanlaista notaatiota:

Objekti {
  tietue                    tietotyyppi
}

Kuvaus

Alla on kuvattu endpointin vastaanottama ja palauttama sanomarakenne. Pakolliset tietueet merkitty tähdellä (*). Valinta merkitty kahdella tähdellä (**).

Request bodyn määritys

{ 
  creationDateTime*         date-time
  senderBusinessId*         string
  messageSerialNumber*      integer
  customers                 [ Customer ]
  accounts                  [ Account ]
  safetyDepositBoxes        [ SafetyDepositBox ]                   
}

HTTP vastaukset

200 OK

400 Bad Request

Body

{
  errorMessage              string
}

405 Method Not Allowed

Body

{
  errorMessage              string
}

500 Internal Server Error

Body

{
  errorMessage              string
}

Tietueiden määritykset

Customer

Customer { 
  startDate*                date-time
  endDate                   date-time
  identification*           Identification
}

Account

Account {
  id*                       AccountIdentification
  servicerIssuedId*         string
  openingDate*              date-time
  closingDate               date-time
  roles                     [ Role ]
}

AccountIdentification

AccountIdentification {
  iban**                    string
  other**                   OtherAccountIdentification
}

OtherAccountIdentification

OtherAccountIdentification {
  id*                       string
  description*              string
}

SafetyDepositBox

SafetyDepositBox {
  startDate*                date-time
  endDate                   date-time
  roles                     [ Role ]
}

Identification

Identification {
  organisation**            Organisation  
  privatePerson**           PrivatePerson                         
}

Role

Role {
  startDate*                date-time
  endDate                   date-time
  role*                     RoleType
  identification*           Identification
  disputed                  boolean
}

|RoleType|kuvaus| |:—|:—| |Owner|Omistaja| |Access|Käyttöoikeuden haltija| |Beneficiary|Edunsaaja|

Organisation

Organisation {
  servicerIssuedId*         string
  registrationAuthority*    string
  businessId*               string
  businessIdCountryCode*    string
  otherOrganisationId       OtherOrganisationId
  beneficiaries*            [ Role ]   
  disputed                  boolean
}

Jos businessId on suomalainen Y-tunnus, businessIdCountryCode arvoksi asetetaan “FI”. Jos Y-tunnusta tai vastaavaa ei ole saatavilla, annetaan otherOrganisationId

OtherOrganisationId

OtherOrganisationId {
  id*                       string
  description*              string
}

PrivatePerson

PrivatePerson {
  servicerIssuedId*         string
  lastName*                 string
  firstNames*               string
  hetu                      string
  birthdate*                date-time
  nationality*              string
  identificationDocumentId  string
  disputed                  boolean
}

Suomalaisille henkilöille on liitettävä aina suomalainen henkilötunnus.

FailedEntries

FailedEntries {
  customers                 [
                              Customer
                            ]
  accounts                  [
                              Account
                            ]
  safetyDepositBoxes        [
                              SafetyDepositBox
                            ]
}

9. Tiedonhakujärjestelmän ja tilirekisterin kyselyrajapinta

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

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.

9.1 Kyselyrajapinnan SOAP-operaatioiden sanomarakenne

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

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

9.3 Kyselyrajapinnan sanomat

Tiedonhakujärjestelmässä ja tilirekisterin kyselyrajapinnassa käytetään ISO 20022 -sanomia InformationRequestOpeningV01 ja InformationRequestResponseV01, joihin liitetään tarvittavat Supplementary Datat.

Seuraavassa taulukossa on listattu käytettävät ISO 20022 -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

Seuraavassa taulukossa on listattu kyselysanomaan liitettävä Supplementary Data -sanomalaajennus. Sanomalaajennusten tarkempi sisältö ja tietueiden käyttöohjeet on listattu luvussa 9.

Sanoma-id Sanoman nimi Laajennettavan ISO 20022 sanoman id Tarkoitus ja toiminnallisuus
FIN012 InformationRequestFIN012 auth.001.001.01 ISO 20022 sanomalaajennus. Kyselyrajapinnan käyttöoikeuden haltijat käyttävät tätä sanomaa tietojen kyselyyn tilirekisteristä ja tiedonhakurajapinnasta.

Seuraavassa taulukossa on listattu vastaussanomaan liitettävät Supplementary Data -sanomalaajennukset.

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 ja tileihin liittyvät edunsaajat
FIN002 InformationResponseFIN002 auth.002.001.01 Sisältää hakuparametreja vastaavat tallelokeroiden ja tallelokeroiden haltijoiden tiedot.
FIN013 InformationResponseFIN013 auth.002.001.01 Sisältää tili- ja tallelokerotiedoista erillisenä hakuparametreja vastaavat asiakkuustiedot

Kyselyrajapinnan sanomavastauksiin sisällytetään kaikki hakukriteereitä vastaavat sanomarakenteen sellaiset tiedot, jotka liittyvät asiakkuuksiin, jotka ovat päättyneet alle 10 vuotta sitten (tietojen säilytysaika). 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.

Seuraavassa on listattu kyselyrajapinnan sanomat tietueineen. Taulukoita luetaan siten, että sisennetyt rivit ovat ensimmäisen rivin sisällä sanomarakenteessa.

Taulukossa pakollisuus on merkitty seuraavasti:

9.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 “COID” 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 “COID” ja elementti To/OrgId/Id/OrgId/Othr/Id sisältää vastaanottajan Y-tunnuksen (Esim. Tilirekisterissä Tullin 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 XMl-allekirjoitus. Tarkentuu.
Rltd BusinessApplicationHeader1 kyllä Käytössä vastaussanomassa, sisältää kyselysanoman sisältämän BAH:in.

9.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. Arvojoukko tarkentuu.
    CnfdtltySts YesNoIndicator Kyllä Aina “true”
    DueDt DueDate1 Ei  
    InvstgtnPrd DateOrDateTimePeriodChoice Ei Ei huomioida. Skeemassa pakollinen, joten /Document/InfReqOpng/InvstgtnPrd/Dt/FrDt ja ToDt esim. kuluva pvm
    SchCrit SearchCriteria1Choice Ei Pakollinen skeemassa. Ei huomioida. Yhdessä kyselyssä voi olla useampia hakutermejä, joten ne on sijoitettu SplmtryData alle
    SplmtryData SupplementaryData1 Kyllä Sisältää sanomalaajennuksen InformationRequestFIN012

9.6 Sanomalaajennus InformationRequestFIN012

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

Nimi Pakollisuus (RAO) [min..max] Tyyppi Kuvaus Liitetään sanomaan XPath
InformationRequestFIN012         auth.001 /Document/InfReqOpng/SplmtryData/Envlp
    AuthorityInquiry R [1..1] AuthorityInquirySet Kyselyyn liittyvät viranomaisen tiedot    
    SearchCriteria R [1..*] SearchCriteriaChoice Hakukriteeri. Käytettävä aina mahdollisimman täsmällistä hakukriteeriä. Esim. jos ei käytetä Y-tunnusta, vaan käytetään OtherOrganisationIdentification-kenttää, haku ei kohdistu Y-tunnuksiin lainkaan. Ks. tarkempi erittely alla.    

AuthorityInquirySet

Nimi Pakollisuus (RAO) [min..max] Tyyppi Kuvaus
AuthorityInquirySet        
    OfficialName R [0..1] Max140Text Virkamiehen nimi
    OfficialSuperiorName R [0..1] Max140Text Esimiehen nimi

SearchCriteriaChoice

Tarkentuu

9.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
    RtrInd ReturnIndicator1 Kyllä [3..3] Vastaussanoman payload. RtrInd/AuthrtyReqTp/MsgNmId sisältää sanomalaajennuksen sanmoma-id:n, ja RtrInd/InvstgtnRslt/Rslt, sisältää itse sanomalaajennuksen supl.027.001.01, InformationResponseFIN002 tai InformationResponseFIN013. Sääntö: Jokainen sanomalaajennus esiintyy yhden kerran.
    SplmtryData SupplementaryData1 Ei [0..0] -

9.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 “COID” 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..*] Tilin tiedot ks. CustomerAccount1 käyttö
    Role AccountRole1 kyllä [1..*] Tiliin liittyvät roolit ks. toinen taulukko alla
    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] ks. Id-elementin käyttö
    Nm   ei    
    Sts   ei    
    Tp   ei    
    Ccy   ei    
    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 [1..*] ks. Id-elementin käyttö  
    OwnrTp OwnerType1 [1..1] Käytetään OwnrTp/Prtry/SchmeNm arvolla “ROLETYPE”, sekä OwnrTp/Prtry/Id, jossa arvot “POWN” (omistaja), “ACCE” (käyttöoikeus) tai “BENE” (edunsaaja)  
    StartDt ISODate [1..1] Roolin alkamispäivämäärä  
    EndDt ISODate [0..1] Roolin päättymispäivämäärä  

9.9 InformationResponseFIN002

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

Nimi Pakollisuus (RAO) [min..max] Tyyppi Index Liitetään sanomaan XPath
InformationResponseFIN002         auth.002 /Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
    InvstgtnId Max35Text kyllä [1..1] Tutkinnan case-id    
    CreDtTm ISODateTime kyllä [1..1] Sanoman luomisaika    
    SvcrId BranchAndFinancialInstitutionIdentification4 kyllä [1..1] Käytetään seuraavasti: Elementti SvcrId/FinInstnId/Othr/SchmeNm/Cd sisältää arvon “COID” ja elementti SvcrId/FinInstnId/Othr/Id sisältää lähettäjän Y-tunnuksen.    
    SdBoxAndPties O [0..*] SafetyDepositBoxAndParties Tallelokero ja osalliset    

9.10 InformationResponseFIN013

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

Nimi Pakollisuus (RAO) [min..max] Tyyppi Index Liitetään sanomaan XPath
InformationResponseFIN013         auth.002 /Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
    InvstgtnId Max35Text kyllä [1..1] Tutkinnan case-id    
    CreDtTm ISODateTime kyllä [1..1] Sanoman luomisaika    
    SvcrId BranchAndFinancialInstitutionIdentification4 kyllä [1..1] Käytetään seuraavasti: Elementti SvcrId/FinInstnId/Othr/SchmeNm/Cd sisältää arvon “COID” ja elementti SvcrId/FinInstnId/Othr/Id sisältää lähettäjän Y-tunnuksen.    
    Customer O [0..*] Customer Asiakas. Luonnollinen henkilö tai yritys. Ks. Customer-elementin käyttö taulukko alla    

Customer-elementin käyttö

Nimi Tyyppi Käytössä [min..max] Kuvaus
Customer        
    Contract Contract kyllä [1..1]  
    Id PartyIdentification41 kyllä [1..1] Ks. Id-elementin käyttö
    Beneficiaries Beneficiaries kyllä [0..1] Kun asiakas on oikeushenkilö, palautetaan myös kaikki edunsaajat.

Beneficiaries käyttö

Nimi Tyyppi Käytössä [min..max] Kuvaus
Beneficaries        
    lastName string kyllä [1..1] sukunimi
    firstNames string kyllä [1..1] etunimet
    hetu string kyllä [0..1] suomalainen henkilötunnus
    birthdate date-time kyllä [0..1] syntymäaika
    nationality string kyllä [0..1] kansalaisuus

9.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
Id Party8Choice kyllä [1..1]  

Party8Choice

Nimi Pakollisuus (RAO) Tyyppi [min..max] Kuvaus  
Party8Choice          
    OrgId A   [0..1] OrganisationIdentification6 Käytetään seuraavasti: Elementti OrgId/Othr/SchmeNm/Prtry sisältää organisaatiotunnuksen tyyppikoodin ja elementti OrgId/Id/OrgId/Othr/Id sisältää tunnuksen. Ks. koodit taulukko alla.
    PrvtId A PersonIdentification5 [0..1] Käytetään seuraavasti: Elementti PrvtId/Othr/SchmeNm/Prtry sisältää henkilötunnisteen tyyppikoodin. Elementti PrvtId/Othr/Id sisältää tunnuksen. Ks. koodit taulukko alla.  

OrgId koodit

Koodi Kuvaus
YTUN Y-tunnus
PRHY Yhdistysrekisterinumero
OTHR Muu yritystunnus, tässä tapauksessa annettava lisäksi maakoodi elementissä OrgId/Othr/Issr

PrvtId koodit

Koodi Kuvaus
HETU Suomalainen henkilötunnus
PIDE Muu henkilön tunnistusasiakirjan id

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

Skenaario 3 - Virheellinen kysely

   
Kuvaus Kyselysanoma on virheellinen
HTTP status code 400
Seuraamus Lähetä korjattu sanoma

Skenaario 4 - Tekninen virhe

   
Kuvaus Tapahtui tekninen virhe
HTTP status code 500
Seuraamus Viestiä ei ole käsitelty. Vastaussanoma sisältää virheen kuvauksen.