Palveluväyläliittymän käyttöönotto
Aineistojen raportoijalla on kaksi vaihtoehtoa käyttää suomi.fi -palveluväylää.
- Raportoija käyttää omaa palveluväyläliittymäänsä.
- 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.