View on GitHub

account-register-aggregating-application

Tiedon hyödyntäjien käyttöönoton ja ylläpidon ohje, koostava sovellus
Deployment and maintenance instructions for data users, Aggregating Application
Description of the aggregating application’s query API
Instruktioner för uppgiftsanvändare om ibruktagande och underhåll, sammanställningsprogrammet
Beskrivning av sammanställningsprogrammets frågegränssnitt

Koostavan sovelluksen rajapintakuvaus

Dokumentin versio 1.03

Versiohistoria

Versio Päivämäärä Kuvaus
1.0 7.2.2023 Versio 1.0
1.01 29.6.2023 Lisätty skeema sanomalle fin.012 ja uusi esimerkkisanoma. Päivitetty lukuun 4.2 kaksi kyselyssä käytettävää uutta tietokenttää. Toista käytetään kohdistamaan kysely tiety(i)lle tiedonlähteille, toista merkitsemään kyselyn liittyvän kansainväliseen/rajat ylittävään tietopyyntöön. Lisäksi päivitetty lukuun 4.7 InvstgtnSts NOAP käyttö vastaussanomassa.
1.02 25.4.2024 Tarkennettu lukuun 2, että status-rajapinta palauttaa vastauksen COMP myös silloin, kun osumia ei löytynyt.
1.03 4.4.2025 Lisätty kuvaus PART vastauskoodin käytöstä lukuun 2.

Sisällysluettelo

  1. Johdanto
  2. Pankki- ja maksutilitietojen kysely koostavasta sovelluksesta
  3. Tietoturva
  4. Koostavan sovelluksen kyselyrajapinta
    4.1 Kyselyrajapinnan SOAP-operaatioiden sanomarakenne
    4.2 Kyselyrajapinta
    4.3 Status-rajapinta
    4.4 Tulosrajapinta
    4.5 Sanomalaajennus Fin020 (QueryResultRequest)
    4.6 Sanomalaajennus Fin021 (QueryResultResponse)
    4.7 Elementin ReturnIndicator1 käyttö
    4.8 Virhetilanteiden hallinta
    4.9 Esimerkkisanomat

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 täydentää Tullin julkaisemaa määräystä pankki- ja maksutilien valvontajärjestelmästä. Dokumentin tarkoitus on antaa ohjeet koostavan sovelluksen rajapinnasta ja sen käytöstä. Tätä dokumenttia täydentää tiedon hyödyntäjän käyttöönoton ja ylläpidon ohje.

1.3 Viittaukset

Tiedonhakujärjestelmän WSDL

fin.020.001.01

fin.021.001.03

fin.012.001.03

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 Koostavan sovelluksen rajapinnat.

2. Pankki- ja maksutilitietojen kysely koostavasta sovelluksesta

Tässä luvussa on kuvattu pankki- ja maksutilitietojen kysely koostavasta sovelluksesta.

Kuvassa 2.1 kyselyprosessi on on esitetty vuokaaviona.

Tietojen kysely koostavasta sovelluksesta
Kuva 2.1. Tietojen kysely Koostavasta sovelluksesta

Taulukossa 2.1. on esitetty vuokaavioon liittyvien muuttujien merkitys.

Taulukko 2.1. Vuokaavioon liittyvät muuttujat

Muuttuja Kuvaus
POLLING_INTERVAL Pollausväli eli viive joka clientin on odotettava ennen seuraavaa kyselyä on 1 minuutti. Jos client pollaa serveriä liian tiheästi, voi server hylätä transaktion käsittelyn (virhekoodi 3, ks. taulukko 4.12.1).
POLLING_TIME_LIMIT Kuinka kauan 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.

Kyselyn vuo kulkee seuraavasti:

  1. Client lähettää kyselysanoman Query Endpointtiin.
  2. Query Endpoint palauttaa vastauksena avaimen (ResultKey).
  3. Client odottaa hetken (kts. POLLING_INTERVAL) ja lähettää avaimen sisältävän statuskyselyn Status Endpointtiin.
  4. Status Endpoint palauttaa vastauskoodin (StatusResponseCode). Koodi on joko
    a. NRES, jos tuloksia ei ole vielä valmiina,
    b. PART, jos osa tuloksista on valmiina, tai
    c. COMP, jos kyselyn kaikki tulokset ovat valmiit.
  5. Jos kyselyyn on saatu osumia (PART tai COMP vastaus), palautuu myös lista avaimia (ResultKey), joilla valmistuneet vastaukset voi hakea.
  6. Jos koodi on
    a. NRES, Client palaa kohtaan 3 tai loppu.
    b. COMP ja osumia on löytynyt, Client lähettää hakutuloskyselyn yhdellä kohdassa 5 vastaanottamistaan avaimista Result Endpointtiin.
    c. COMP mutta osumia ei löytynyt, loppu.
    d. PART, Client valitsee joko
    1. Odottaa, että lisää vastauksia valmistuu (paluu kohtaan 3) tai
    2. Hakea valmistuneet vastaukset, jos osumia on löytynyt (kohdat 6.c. ja 6.d.)
  7. Result Endpoint palauttaa lähetettyä avainta vastaavan hakutulossanoman.
  8. Jos hakutuloksia on vielä hakematta, palataan kohtaan 6.c. ja toistetaan haku seuraavalla avaimella.
  9. Jos Status Endpointin palauttama koodi oli PART,
    a. Client palaa kohtaan 3 kyselemään onko uusia vastauksia (uudet ResultKeyt) valmistunut, tai
    b. Jos kyselyä ei tarvitse tai kannata jatkaa, loppu.
  10. Jos kaikki hakutulokset on saatu, loppu.

Palautettavat koodit on määritelty ISO-koodistossa StatusResponse1Code, jonka arvojen käyttön on kuvattu Taulukossa 2.2.

Taulukko 2.2. StatusResponse1Code arvojen käyttö

Koodi Nimi Määritelmä Kuvaus
COMP CompleteResponse Response is complete. Kysely on käsitelty kokonaan, kaikki tiedonlähteet ovat vastanneet ja mahdolliset tulokset ovat saatavilla.
NRES NoResponseYet Response not provided yet. Kyselyyn ei ole vielä saatu vastauksia tiedonlähteistä, tee uusi kysely myöhemmin.
PART PartialResponse Response is partially provided. Kysely on käsitelty osittain, ainakin yhdestä tiedonlähteestä odotetaan vielä vastausta. Mahdolliset tähän asti saadut tulokset ovat saatavilla.

Tulosten säilytysaika Koostavassa sovelluksessa

Tulokset poistetaan kun ne on noudettu. Valmiita tuloksia pidetään tallessa korkeintaan 24 tunnin ajan niiden valmistumisesta, jona aikana tulokset on noudettava.

3. Tietoturva

Tietoturvakäytäntö noudattaa samoja periaatteita, kuin Tiedonhakujärjestelmän kyselyrajapinnan määrittelyssä on kuvattu.

4. Koostavan sovelluksen rajapinta

Rajapinta toteutetaan SOAP/XML Web Servicenä, jonka WSDL on julkaistu Tiedonhakujärjestelmän kyselyrajapintakuvaus -dokumentin yhteydessä.

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.

Koostavan sovelluksen rajapinnassa on kolme endpointia:

4.1 Kyselyrajapinnan SOAP-operaatioiden sanomarakenne

Rajapinnassa käytettävä sanomarakenne on päätasolla identtinen Tullin julkaiseman Tiedonhakujärjestelmien kyselyrajapinnan määrityksen kanssa. Tämän lisäksi rajapintaan on määritelty alisanomat fin.020 ja fin.021, joilla välitetään tarvittavat tunnisteet haun tilan tarkistamiseksi ja tulosten hakemiseksi.

4.2 Kyselyrajapinta

Kyselyrajapintaan lähetettävä sanoma on enimmäkseen samanlainen kuin Tiedonhakujärjestelmien kyselyrajapinnassa käytettävä sanoma. Erona tiedonhakujärjestelmien kyselyrajapinnassa käytettävään sanomaan, fin012 sanomalaajennuksessa on käytettävissä kaksi lisäkenttää: RequestedDataSources ja InternationalRequest. RequestedDataSources-kenttää käytetään kohdistamaan kysely yhteen tai useampaan tiedonlähteeseen (tiedonhakujärjestemät ja tilirekisteri). Kohdistettu kysely välitetään ainoastaan kentässä määritellyille tiedonlähteille. InternationalRequest-kenttää käyttäen merkitään kyselyn liittyvän kansainväliseen/rajat ylittävään tietopyyntöön rahoitustietodirektiiviin ((EU) 2019/1153) 19 artiklaan ja kansallisen rahanpesulain (444/2017) 2 luvun 4 §:ään perustuen.

Vastaussanoma noudattaa myös samaa rakennetta, mutta auth.002-sanoman yhtenä alisanomana on fin.021-sanoma, joka kertoo vastaanotetun kyselyn tunnuksen. Tätä tunnusta käytetään kyselyn tilan tarkistamiseen Status-rajapinnasta. Status-rajapinnassa muut alisanomat palauttavat statuksen NFOU, mikä ei tässä tapauksessa merkitse mitään.

4.2.1 Sanomalaajennus InformationRequestFIN012

Alisanoman skeema on määritelty tiedostossa fin.012. 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.    
    RequestedDataSources [0..1] RequestedDataSources Tiedonlähde tai tiedonlähteet, joille kysely lähetetään. Jos elementti puuttuu sanomasta, kysely lähetetään kaikille tiedonlähteille.    
    InternationalRequest [0..1] boolean Käytetään arvoa “true”, kun kysely liittyy kansainväliseen tietopyyntöön.    

AuthorityInquirySet

Nimi Tyyppi Käytössä Kuvaus
AuthorityInquirySet      
    OfficialId Max140Text Kyllä Kyselyn tehneen viranomaisen tunnus
    OfficialSuperiorId Max140Text Kyllä Kyselyn tehneen viranomaisen esihenkilön tunnus

RequestedDataSources

Nimi [min..max] Tyyppi Kuvaus
RequestedDataSources      
    DataSourceOrgId [1..*] Max35Text Tiedonlähteen Y-tunnus

4.3 Status-rajapinta

Status-rajapintaan lähetettävä sanoma koostuu samasta sanomasisällöstä kuin kyselyä tehtäessä, lisäksi kyselyrajapinnan vastauksena saatu tunnus välitetään fin.020-alisanomassa.

Vastaussanoma on kuten Kyselyrajapinnan vastauksessa, ja lisäksi:

4.4 Tulosrajapinta

Tulosrajapintaan lähetettävä sanoma koostuu samasta sanomasisällöstä kuin kyselyä tehtäessä, lisäksi Status-rajapinnan vastauksena saadut tunnukset välitetään yksi kerrallaan fin.020-alisanomassa.

Vastaussanoma on samanlainen, kuin Tiedonhakujärjestelmän kyselyrajapinnan vastaussanoma, sisältäen varsinaiset hakutulokset skeeman mukaisesti. Lisäksi fin.021-alisanomassa palautuu tuloksen tunnus sekä datasourceIdentifier-attribuutissa tuloksen palauttaneen tiedonhakujärjestelmän Y-tunnus.

4.5 Sanomalaajennus Fin020 (QueryResultRequest)

Alisanoman skeema on määritelty tiedostossa fin.020. Sanomalaajennus liitetään taulukossa listattuun ISO 20022 sanoman XPath-sijaintiin.

Nimi [min..max] Tyyppi Kuvaus Liitetään sanomaan XPath
QueryResultRequest       auth.001 /Document/InfReqOpng/SplmtryData/Envlp
    ResultKeyList [1..1] ResultKeyList Lista haettavien tietojen tunnisteista    
Nimi [min..max] Tyyppi Kuvaus Huomioita
ResultKeyList        
    ResultKey [1..n] Max256Text Haun tai tuloksen UUID Toistaiseksi tuetaan vain yhtä arvoa kerrallaan

4.6 Sanomalaajennus Fin021 (QueryResultResponse)

Alisanoman skeema on määritelty tiedostossa fin.021. Alisanoma palautetaan Tiedonhakujärjestelmän vastaussanomassa muiden alisanomien tapaan ReturnIndicator1-elementin sisällä.

ResultKeyList-elementin attribuutteina palautetaan seuraavat tiedot:

Nimi [min..max] Tyyppi Kuvaus Liitetään sanomaan XPath
QueryResultResponse       auth.002 /Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
    QueryKeyList [0..1] QueryKeyList Lista kyselyssä käytetyistä tunnisteista    
    ResultKeyList [0..1] ResultKeyList Lista tulostietojen tunnisteista    
Nimi [min..max] Tyyppi Kuvaus Huomioita
QueryKeyList        
    ResultKey [1..n] Max256Text Tuloksen UUID  
ResultKeyList        
    ResultKey [1..n] Max256TextAllowedEmpty Tuloksen UUID tai virhetilanteessa tyhjä Optionaaliset attribuutit: datasourceOrganisationId ja errorCode

4.7 Elementin ReturnIndicator1 käyttö

ReturnIndicator1 sisältää yksittäisen hakutulostyypin esiintymän, kuten Tiedonhakujärjestelmän kyselyrajapinnan vastaussanomassakin. fin.021 palautetaan tässä elementissä, kuten muutkin kyselyssä palautettavat alisanomat.

XPath Tyyppi Kuvaus
RtrInd/AuthrtyReqTp/MsgNmId Max35Text sisältää sanomalaajennuksen sanoma-id:n (fin.021.001.03)
RtrInd/InvstgtnRslt InvestigationResult1Choice Palautetaan Rslt elementti tyyppiä SupplementaryDataEnvelope1, joka sisältää jonkin alisanomista (fin.021, supl.027, fin.013 tai fin.002) tai elementin InvstgtnSts. InvstgtnSts palautetaan koodilla NFOU, jos kyselyssä käytetyllä tunnuksella ei löydy alisanomassa palautettavaa tietoa. InvstgtnSts palautetaan koodilla NOAP siinä tapauksessa, että luonnollisen tai oikeushenkilön nimihaulla tilirekisteristä löytyy jonkin toimijan tiedoista useita hakua vastaavia luonnollisia tai oikeushenkilöitä.

4.8 Virhetilanteiden hallinta

Virheiden hallinta ja palautettavat koodit noudattavat soveltuvin osin Tiedonhakujärjestelmän kyselyrajapinnan Kyselyrajapinnan WS-sanomaliikenteen skenaariot -kappaleen määrityksiä.

Status-rajapinnan vastaus voi olla tyhjä ResultKey ja virhekoodi, mikä tarkoittaa että kyselyn käsittelyssä on tapahtunut virhe. Tällöin kyselyä ei ole välitetty tietolähteisiin eikä kyselyyn tule noudettavia vastauksia. Tällä hetkellä “TIMEOUT” on ainoa virhekoodi, joka palautetaan tässä tilanteessa.

Status- ja tulosrajapinnoista palautuvissa vastaussanomissa fin021-alisanomassa on myös tieto mahdollisesta virheestä, joka on tapahtunut yksittäisen tiedonlähteen osalla. Tämä tieto välitetään ResultKey-elementin errorCode-attribuutissa.

Koostavan sovelluksen kautta ei ole mahdollista kysellä 1.9.2020 aikaisempia tietoja. Koostavan sovelluksen kyselyrajapinta hylkää kyselyt, joissa haettu aikaväli (InvstgtnPrd) on ennen tätä.

4.9 Esimerkkisanomat

Esimerkkisanomat kustakin kyselysanomasta ja sen vastauksesta löytyvät examples-kansiosta: