POST-rajapinta

POST-rajapinta mahdollistaa loppukäyttäjien asiointipalvelussanne täyttämien lomakkeiden tietojen välittämisen ja säilyttämisen Suomi.fi-viesteissä. Näin organisaationne voi täydentää lomakepalveluanne ilman tallennukseen kykenevää asiointialustaa. Samalla myös lomakkeiden lähettämisestä tulee entistä turvallisempaa.

POST-rajapinnan toimintalogiikka on seuraava:

Loppukäyttäjällä tulee olla Suomi.fi-viestit käytössä tai hänen tulee ottaa palvelu käyttöönsä ennen lomakkeen lähettämistä.
Loppukäyttäjä täyttää asiointipalveluunne määrittelemänne lomakkeen.
Lomakkeen lähetys edellyttää vahvaa tunnistautumista. Jos lomaketta yrittää lähettää henkilö, jolla ei ole Suomi.fi-viestit käytössä, lomakkeen lähetys epäonnistuu ja hän saa virheilmoituksen.
Loppukäyttäjän lähettämä lomake toimitetaan Suomi.fi-viesteille POST-rajapinnan avulla.
Loppukäyttäjälle näkyvä lomakkeen sisältö tallentuu loppukäyttäjän sähköiseen postilaatikkoon Suomi.fi-viesteissä.
Lomakkeen sisältö jatkaa Suomi.fi-viesteistä edelleen organisaatiollenne käyttöönotetun vastausmahdollisuutta tukevan rajapinnan avulla.

Huomaattehan, kuten yllä olevan listan viimeisessä kohdassa mainitaan, POST-rajapinnan käyttö vaatii rinnalleen toisen vastausmahdollisuutta tukevan rajapinnan, jolla lomakkeen siirtyminen organisaatiollenne hoidetaan. POST-rajapintaa käytetään ainoastaan lomakkeen välittämiseen Suomi.fi-viesteille.

Tunnistautumisvaatimuksen takia POST-rajapinta ei mahdollista lomakkeen lähettämistä toisen puolesta.

POST-rajapinnan käyttö

POST-rajapinnan kutsuminen tapahtuu POST-kutsulla, esimerkiksi HTML-lomakkeella. Lomakkeen action-parametriksi annetaan käytettävän POST-rajapinnan osoite. Varsinaiset Suomi.fi-viestien tarvitsemat tietokentät ovat lomakkeen sisällä olevia kenttiä, yleensä hidden input -tyyppisiä. Ne on lueteltu taulukossa 2.

Lomakkeelle sijoitetaan myös loppukäyttäjälle näkyvät HTML-lomakekentät. Ne ovat tyypiltään ja muilta ominaisuuksiltaan vapaasti valittavia, kunhan niiden nimet eivät ole samoja kuin Suomi.fi-viestien käyttämien kenttien. Loppukäyttäjälle näkyvien HTML-kenttien sisällöt viedään tämän artikkelin lopussa kuvatun JavaScript-koodin avulla liitetiedostoksi, joka lähetetään lomakkeen yhteydessä.

Tämän ohjeen esimerkissä (sivun alareunassa) on käytetty sekä PDF- että XML-muotoista liitettä. Tarvittaessa liitetyyppi voi olla jokin muukin, esimerkiksi DOC. Liitteen näkyminen loppukäyttäjälle määritellään TiedostoPiilotettu-kentässä. Liite tulee aina organisaatiollenne, vaikka se ei näkyisikään loppukäyttäjälle.

Lähetyksessä on oltava aina vähintään yksi liite. Liitteitä voi olla enintään kymmenen ja liitetiedostojen (sanoman) yhteenlaskettu enimmäiskoko on 10 Mt.

Taulukossa 1 on esitetty POST-rajapinnan action-osoitteet testi- ja tuotantoympäristöissä. Jos osoitteet vaativat vielä erillisen tunnistuksen, organisaatiollenne toimitetaan tarvittavat tunnukset.

Ympäristö	Osoite
Testiympäristö	https://viestilomake.qa.suomi.fi/form
Tuotantoympäristö	https://viestilomake.suomi.fi/form

Taulukko 1. POST-rajapinnan action-osoitteet.

POST-lomakkeen kentät

Taulukossa 2 on esitetty ne POST-lomakkeen kentät, joita Suomi.fi-viesteissä käytetään.

Kenttä	Selite	Tietotyyppi
ViranomaisTunnus	Suomi.fi-viestien organisaatiollenne antama tunnus	string
PalveluTunnus	Suomi.fi-viestien organisaationne palvelulle antama tunnus	string
Nimeke	Lomakkeen otsikko	string
Kuvausteksti	Lomakkeen sisältöä kuvaava teksti, varsinainen lomakesisältö toimitetaan liitteenä	string
Paluuosoite	URL-osoite, johon POST-rajapinnasta palataan. Suomi.fi-viestit lisää paluuosoitteen URL-parametriksi tiedon siitä, onko loppukäyttäjä lähettänyt viestin vai keskeyttänyt lähetyksen jossakin vaiheessa (Toimitettu=1 tai 0).	string
PalaaAutomaattisesti	Lippu, jos arvoksi on annettu 1, lomakkeen lähetyksen jälkeen palataan automaattisesti paluuosoitteeseen (jos annettu)	bitti (0 tai 1)
ViranomaisenEmail	Organisaationne sähköpostiosoite, johon viesti voidaan ohjata. Käytössä, jos valittu paluukanava perustuu SMTP-rajapintaan.	string
TiedostoNimi_1	Liitetiedoston 1 nimi	string
TiedostoSisalto_1	Liitetiedoston 1 sisältö base64-enkoodattuna merkkijonona	string
TiedostoMuoto_1	Liitetiedoston 1 MIME-tyyppi	string
TiedostoPiilotettu_1	Lippu, jos arvoksi on annettu 1, liitetiedostoa 1 ei näytetä loppukäyttäjälle Suomi.fi-viesteissä (esim. lomakkeen tiedot XML-muodossa)	bitti (0 tai 1)
…	Vastaavasti mahdolliset liitteet 2 – 9
TiedostoNimi_10	Liitetiedoston 10 nimi	string
TiedostoSisalto_10	Liitetiedoston 10 sisältö base64-enkoodattuna merkkijonona	string
TiedostoMuoto_10	Liitetiedoston 10 MIME-tyyppi	string
TiedostoPiilotettu_10	Lippu, jos arvoksi on annettu 1, liitetiedostoa 10 ei näytetä loppukäyttäjälle Suomi.fi-viesteissä (esim. lomakkeen tiedot XML-muodossa)	bitti (0 tai 1)

Taulukko 2. Suomi.fi-viestien käyttämät POST-lomakkeen kentät.

Seuraavassa on esimerkki lomakkeen tietojen lähettämisestä PDF- ja XML-muotoisina liitteinä.

Esimerkki perustuu natiiviin JavaScriptiin, ja näin ollen sen toimivuutta ei voida taata kaikissa selainversioissa. Sitä voidaan käyttää mallina lomakkeen liitetiedostojen muodostamiselle palautelomakkeesta. Se pitää kuitenkin portata käytettävään sovellukseen itseensä sovelluksen määrittämällä tavalla.

Huom! <script src="https://unpkg.com/jspdf@latest/dist/jspdf.min.js"></script> on CDN-osoite, joka on kolmannen osapuolen hallussa. Osoitteen kautta on periaatteessa mahdollista hyökätä sivustolle. Osoite on tässä siis ainoastaan esimerkin vuoksi. Oikea tapa on asentaa kirjasto omalle palvelimelle ja viitata siihen.

<html>
<head>
  <meta charset="utf-8"/>
  <script src="https://unpkg.com/jspdf@latest/dist/jspdf.min.js"></script>
  <script>
    function b64EncodeUnicode(str) {
      return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g,
 
      function toSolidBytes(match, p1) {
        return String.fromCharCode("0x" + p1);
      }));
    }
     
    function createB64EncodedPdf(header, feedback){
      var pdf = new jsPDF();
       
      pdf.setFontSize(22);
      pdf.text(20,20, "Palaute");
      pdf.setFontSize(20);
      pdf.text(20,30, header);
      pdf.setFontSize(16);
      pdf.text(20,50, feedback);
       
      return b64EncodeUnicode(pdf.output());
    }
     
    function createB64EncodedXml(header, feedback) {
      var xml = xmlTemplate(header, feedback);
      return b64EncodeUnicode(xml);
    }
 
    function xmlTemplate(header, feedback) {
      return "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
        "<palaute>"     +
          "<otsikko>"   +
            header      +
          "</otsikko>"  +
          "<viesti>"    +
            feedback    +
          "</viesti>"   +
        "</palaute>"
    }
     
    function setFileContents(pdfContent, xmlContent) {
      document.getElementById("TiedostoSisalto_1").value = pdfContent
      document.getElementById("TiedostoSisalto_2").value = xmlContent
    }
     
    function send() {
      var header = document.getElementById("header").value;
      var feedback = document.getElementById("feedback").value;
      var base64EncodedPdfAttachment = createB64EncodedPdf(header, feedback);
      var base64EncodedXmlAttachment = createB64EncodedXml(header, feedback);
 
      setFileContents(base64EncodedPdfAttachment, base64EncodedXmlAttachment);
 
      return true;
    }
  </script>
</head>
 
<body>
<h2>Palaute asioinnista</h2>
 
Otsikko:
<div>
  <input id="header" type="text" value=""/>
</div>
 
Palaute:
<div>
  <textarea id="feedback" rows="6" cols="100" value=""></textarea>
</div>
 
<div>
  <form id="postForm" action="https://viestilomake.qa.suomi.fi/form" method="post" onsubmit="send()">
    <input type="hidden" name="ViranomaisTunnus" id="ViranomaisTunnus" value="2574261-7" />
    <input type="hidden" name="PalveluTunnus" id="PalveluTunnus" value="Vaka" />
    <input type="hidden" name="Paluuosoite" id="Paluuosoite" value="http://example.com/?testParam=1" />
    <input type="hidden" name="ViranomaisenEmail" id="ViranomaisenEmail" value="foo.bar@example.com" />
     
    <input type="hidden" name="Nimeke" id="Nimeke" value="Palaute asiointilomakkeelta" />
    <input type="hidden" name="Kuvausteksti" id="Kuvausteksti" value="Lomakkeen sisältö" />
 
    <input type="hidden" name="TiedostoNimi_1" id="TiedostoNimi_1" value="palaute.pdf" />
    <input type="hidden" name="TiedostoSisalto_1" id="TiedostoSisalto_1" value="" />
    <input type="hidden" name="TiedostoMuoto_1" id="TiedostoMuoto_1" value="application/pdf" />
    <input type="hidden" name="TiedostoPiilotettu_1" id="TiedostoPiilotettu_1" value="0" />
     
    <input type="hidden" name="TiedostoNimi_2" id="TiedostoNimi_2" value="palaute.xml" />
    <input type="hidden" name="TiedostoSisalto_2" id="TiedostoSisalto_2" value="" />
    <input type="hidden" name="TiedostoMuoto_2" id="TiedostoMuoto_2" value="text/xml" />
    <input type="hidden" name="TiedostoPiilotettu_2" id="TiedostoPiilotettu_2" value="1" />
     
    <br />
    <input type="submit" value="Lähetä" />
  </form>
</div>
</body>
</html>

Suomi.fi-viesteissä käytetään jatkossa pelkästään REST-rajapintaa ja sähköisten lomakkeiden POST-rajapintaa. Vanhat rajapinnat (WS-, SFTP- ja SMTP-rajapinta) poistuvat käytöstä 1.1.2027. Suomi.fi-viestien lomakkeissa käytettävä POST-rajapinta tarvitsee aina rinnalleen toisen rajapinnan, jotta viesti kulkee organisaatiolle asti. Jatkossa tämän toisen rajapinnan on oltava REST-rajapinta.

Jos Suomi.fi-viestien sähköiset lomakkeet tulevat tällä hetkellä organisaatiossanne sähköpostiin (esimerkiksi kirjaamon sähköpostiosoitteeseen) käytössänne POST-rajapinnan rinnalla on SMTP-rajapinta. 1.1.2027 jälkeen lomakkeet eivät enää kulkeudu organisaationne sähköpostiohjelmaan, koska rajapinta poistuu käytöstä.

Jatkossa lomakkeet on ohjattava REST-rajapinnan kautta suoraan järjestelmään, esimerkiksi organisaationne asiointiportaaliin tai asianhallintajärjestelmään. Olkaa yhteydessä ICT-tukeen tai lomakepalvelua tarjoavaan järjestelmätoimittajaan saadaksenne lisätietoja siitä, minne lomakkeet olisi mahdollista jatkossa ohjata rajapintamuutoksen myötä.

Päivitetty: 2.1.2026

Digitalisoi asiointipolkusi

Tehosta tiedonhallintaa

Paranna palveluiden laatua

Turvaa tietosi

Jaa, avaa ja hyödynnä tietoa