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 (kuntadata@valtiokonttori.fi ).
  • • 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.

Kehittäjän opas: palveluväylän palveluiden käyttöönotto

Digi- ja väestötietovirasto on tuottanut uuden oppaan Suomi.fi-palveluväylän käyttöönotosta.

• Tiedote
• Opas

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

UUSI : <fi:targetEntrypoints> = <fi:email> -kentän perään lisätään tämä käsite, jolla rajataan csv-lähetykset koskemaan jotain tiettyä raportointikokonaisuutta. Useammassa raportointikokonaisuudessa saattaa olla käytössä sama solutunniste ja csv-raportissa ei ole raportointikohtaisia tunnuksia. Tästä syystä csv-lähetyksen yhteydessä raportti rajataan koskemaan tiettyä raportointikokonaisuutta. Lähetyksen voi tehdä ilman tätä tunnusta, mutta tietopalvelu pyrkii aukaisemaan jokaisen raportointikokonaisuuden, missä on raportoinnin sisältämiä solutunnisteita. Tähän laitetaan arvoksi taksonomian mukainen raportointikokonaisuus. Esim. Tilinpäätösennusteen tunnus on <fi:targetEntrypoints>ktpe_gaap_ind</fi:targetEntrypoints>, KKNR neljännesvuositilaston tunnus on <fi:targetEntrypoints>kknr_gaap_ind</fi:targetEntrypoints> ja KLTR neljännesvuositilaston tunnus on<fi:targetEntrypoints>kltr_gaap_ind</fi:targetEntrypoints> .

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.

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.