Raportointi Kuntatalouden tietopalveluun Suomi.fi -palveluväylässä

KohderyhmäKunta
AsiakirjatyyppiOhje
Antopäivämäärä26.04.2021
KategoriatTietojen toimittaminen
YlläpitovastuuValtiokonttori

Palveluväyläliittymän käyttöönotto

Aineistojen raportoijalla on kaksi vaihtoehtoa käyttää suomi.fi -palveluväylää.

  1. Raportoija käyttää omaa palveluväyläliittymäänsä.
  2. Raportoija käyttää kumppaninsa palveluväyläliittymää.

Vaihtoehto 1

  • Perusta oma – raportoijan – liityntäpalvelin palveluväylän ohjeiden mukaisesti
    https://palveluhallinta.suomi.fi/fi/tuki/artikkelit/59145e7b14bbb10001966f72
  • Varmista omassa organisaatiossasi, että perustamillesi liityntäpalvelimille on avattu tarvittavat ympäristökohtaiset tietoliikenneoikeudet vähintään oheisen mukaisesti. Lähtöpalvelin on raportoijan liityntäpalvelin ja kohde on Tietopalvelun käyttämä liityntäpalvelin.
  • Huomioi myös palveluväylän antama ohje: Yhteysavaukset sallitaan raportoijan liityntäpalvelimelta – clientiltä vain ulospäin, lisäksi service-palvelimella yhteydet client-palvelimelta on sallittava kohdeportteihin. Tilattoman palomuurin tapauksessa avattujen yhteyksien paluupaketit on sallittava yläportteihin (>1024), tilallisen palomuurin pitäisi hoitaa tämä automaattisesti.

  • Pyydä palveluväylän käytön vaatimat tietoliikenneavaukset Kuntatalouden Tietopalvelun puolelta sähköpostitse ([email protected] ).
      • Kirjoita pyynnön otsikoksi ”Palveluväylän liittymäpalvelimen tietoliikenteen avaaminen”
      • Liitä pyyntöön liityntäpalvelimiesi nimet ja IP-osoitteet
      • Tietopalvelu avaa saapuvalle liikenteelle tarvittavat portit (5500 ja 5577)
      • Tietopalvelu vastaa, kun avaukset on tehty (oletusarvoisesti tähän menee noin kolme työpäivää)

Vaihtoehto 2

Raportoija asioi kumppaninsa kanssa. Kumppani hoitaa liikenteen valitsemallaan tavalla hyödyntäen yllä olevia ohjeita.

Käsitteet

Perustiedot suomi.fi roolista https://esuomi.fi/palveluntarjoajille/palveluvayla/sanasto/

Lähetys hoidetaan tyypillisesti ohjelmalla, joka tekee http-lähetyksen (HTTP POST). Aineisto lähetetään lähettäjän omalle liityntäpalvelimelle, joka välittää sen palveluväylän kautta kuntatalouden tietopalveluun.

Lähetettävän viestin mallit seuraavissa kappaleissa. Tässä lyhyt sanasto.

envelope = standardi SOAP-viesti.

client = lähettävän tahon tiedot, TOLT-yksiköillä tähän tulee emon (kunnan) tiedot. Tieto on   vain palveluväylän käyttöön, ei Tietopalvelun. Yllä on mallina CSC:n käyttämä testi-client.

service = vastaanottavan tahon eli usertestin osalta CSC:n ja tuotannon osalta Valtiokonttorin tiedot.

xrd:userId = käyttäjätunnus, esimerkiksi kunnan y-tunnus. Se pitää olla mutta Tietopalvelu ei käytä sitä. Alla olevissa malleissa on siis korvattava 1234567-1.

xrd:id = viestin yksikäsitteinen tunniste, esim. generoitu UUID tai raportoijan tunnus ja juokseva numero.

body = viestin sisältö. Tälle on olemassa WSDL-malli. Tiedot ovat samat kuin web-lähetyssivulla.

fi:fileType = aineiston tyyppi. Arvo voi olla XBRL tai CSV.

fi:file = Base 64 -koodattu aineisto. Korvaa alla olevissa malleissa <!– Base 64 -koodattu aineisto –> omalla aineistoillasi, myös alun ja lopun kulmasulkeet.

fi:email = sähköpostiosoite, johon Tietopalvelu lähettää viestin, jos aineistossa on virhe. Korvaa mallissa oleva sähköposti. Sähköpostilla pitää olla oikeus lähettää aineisto.
Huom: Jos lähetys katkeaa jo palveluväylässä, palveluväylä viestittää asiasta lähettävälle liityntäpalvelimelle jolloin tätä sähköpostia ei käytetä.

Valtiokonttori ei vaadi client-sertifikaatin käyttöä.

Aineiston lähetys usertest-ympäristössä

Esimerkkiaineisto: uploadmaterialfile-usertest.xml

Client-osioon syötetään raportoijan käyttämän liityntäpalvelimen tiedot. Yllä on mallissa Tietopalvelun tarjoaman liittymän tiedot. Usertest-ympäristössä Tietopalvelun liittymän tietoliikenneavaukset on tehty valmiiksi.

Tässä mallikomento viestin lähetykseen, missä xml-tiedoston sisältö on edellä oleva Envelope-viesti.

  • curl -kvvv -d @uploadmaterialfile-usertest.xml –header ”Content-Type: text/xml” -X POST https://digialptest.digia.com

Aineiston lähetys tuotantoympäristössä

Client-osioon syötetään raportoijan käyttämän liityntäpalvelimen tiedot. Yllä on mallissa Tietopalvelun tarjoaman liittymän tiedot. Jos tuotannossa haluaa käyttää Tietopalvelun tarjoamaa liityntäpalvelinta, raportoijan tulee olla yhteydessä Valtiokonttorin palvelukanavaan, että käyttö voidaan luvittaa.