POST-gränssnittet

POST-gränssnittet möjliggör förmedling och lagring av uppgifter i de blanketter som slutanvändarna har fyllt i i er e-tjänst i Suomi.fi-meddelanden. Detta gör det möjligt för er organisation att komplettera er blankettjänst utan en ärendeplattform som kan lagra uppgifter. Samtidigt blir det även tryggare att skicka in blanketter.

POST-gränssnittets funktionslogik är följande:

Slutanvändaren måste ha Suomi.fi-meddelanden i bruk eller aktivera tjänsten innan blanketten skickas.
Slutanvändaren fyller i den blankett som ni har definierat i er e-tjänst.
Inlämning av blanketten kräver stark autentisering. Om en person som inte använder Suomi.fi-meddelanden försöker skicka in blanketten, misslyckas sändningen och personen får ett felmeddelande.
Blanketten som slutanvändaren skickar överförs till Suomi.fi-meddelanden via POST-gränssnittet.
Det blankettinnehåll som är synligt för slutanvändaren lagras i slutanvändarens elektroniska brevlåda i Suomi.fi-meddelanden.
Blankettens innehåll vidarebefordras från Suomi.fi-meddelanden till er organisation via det gränssnitt som stöder svarsmöjligheten och som ni har tagit i bruk.

Observera att, som nämns i den sista punkten ovan, kräver användning av POST-gränssnittet att ni även tar i bruk ett annat gränssnitt som stöder svarsmöjligheten och som ansvarar för överföringen av blankettinnehållet till er organisation. POST-gränssnittet används enbart för att överföra blanketten till Suomi.fi-meddelanden.

På grund av autentiseringskravet är det inte möjligt att skicka blanketten för någon annans räkning via POST-gränssnittet.

Användning av POST-gränssnittet

POST-gränssnittet anropas t.ex. med ett HTML-formulär. Adressen till POST-gränssnittet anges som action-parameter på formuläret. De egentliga fälten som Suomi.fi-meddelanden behöver finns inuti formuläret och är ofta av typen hidden input. De räknas upp i tabell 2.

På formuläret placeras även de HTML-fält som visas för slutanvändaren. Deras typ och andra egenskaper kan väljas fritt, så länge namnen inte är desamma som de som används i Suomi.fi-meddelanden. Innehållet i de HTML-fält som syns för slutanvändarna införs med hjälp av en JavaScript-kod som beskrivs i slutet av denna artikel i en filbilaga som skickas tillsammans med formuläret.

I exemplen i denna anvisning (längst ner på sidan) har man använt bilagor både i PDF- och XML-format. Vid behov kan filtypen även vara någon annan, t.ex. DOC. Hur bilagan ska visas för slutanvändaren anges i fältet TiedostoPiilotettu. Bilagan kommer alltid till er organisation även om den inte skulle synas för slutanvändaren.

Varje avsändning ska ha minst en bilaga. Antalet bilagor kan vara högst 10. Sammanräknad stolek av bilagor (meddelanden) kan vara högst 10 Mb.

Tabell 1 visar POST-gränssnittets action-adresser i test- och produktionsmiljö. Om adresserna ytterligare kräver en separat identifiering, ska behövliga användarkoder skickas till er organisation.

Miljö	Adress
Testmiljö	https://viestilomake.qa.suomi.fi/form
Produktionsmiljö	https://viestilomake.suomi.fi/form

Tabell 1. POST-gränssnittets action-adresser.

Fält i POST-formuläret

Tabell 2 visar de fält i POST-formuläret som används i Suomi.fi-meddelanden.

Fält	Förklaring	Typ
ViranomaisTunnus	Den identifierare som Suomi.fi-meddelanden har tilldelat er organisation, t.ex. viranomainen_ws	string
PalveluTunnus	Den identifierare som Suomi.fi-meddelanden har tilldelat er organisations tjänst, t.ex. viranomainen_ws_palvelu	string
Nimeke	Formulärets rubrik	string
Kuvausteksti	Text som beskriver formulärets innehåll, det egentliga innehållet finns i en bilaga	string
Paluuosoite	URL-adress som man kommer tillbaka till från POST-gränssnittet. Som URL-parameter för returadressen lägger Suomi.fi-meddelanden till en uppgift om huruvida slutanvändaren har skickat meddelandet eller avbrutit avsändningen i något skede (Levererat = 1 eller 0).	string
PalaaAutomaattisesti	Flagga, om värdet är 1 återgår man automatiskt till returadressen efter avsändningen (om en sådan har angivits)	bit (0 eller 1)
ViranomaisenEmail	Er organisations e-postadress som meddelandet kan styras till. Används i fallet med SMTP-gränssnitt.	string
TiedostoNimi_1	Namnet på filbilaga 1	string
TiedostoSisalto_1	Innehållet i filbilaga 1 som base64-kodad teckensträng	string
TiedostoMuoto_1	MIME-typ för filbilaga 1	string
TiedostoPiilotettu_1	Flagga, om värdet är 1 visas filbilaga 1 inte för slutanvändare i Suomi.fi-meddelanden (t.ex. formulärets uppgifter i XML-format)	bit (0 eller 1)
…	Som ovan för bilagorna 2 – 9	-
TiedostoNimi_10	Namnet på filbilaga 10	string
TiedostoSisalto_10	Innehållet i filbilaga 10 som base64-kodad teckensträng	string
TiedostoMuoto_10	MIME-typ för filbilaga 10	string
TiedostoPiilotettu_10	Flagga, om värdet är 1 visas filbilaga 10 inte för slutanvändare i Suomi.fi-meddelanden (t.ex. formulärets uppgifter i XML-format)	bit (0 eller 1)

I det följande ges ett exempel på hur uppgifter i formuläret kan skickas som bilagor i PDF- och XML-format.

Exemplet baserar sig på nativ JavaScript och därför kan man inte garantera att det fungerar i alla webbläsarversioner. Det kan användas som modell för hur man bildar filbilagor av responsformulär. Det måste dock portas i själva tillämpningen på det sätt som tillämpningen förutsätter.

Obs! <script src="https://unpkg.com/jspdf@latest/dist/jspdf.min.js">> är en CDN-adress i tredje parts besittning. Via adressen är det i princip möjligt att attackera webbplatsen. Därför utgör adressen endast ett exempel i det här sammanhanget. Det korrekta sättet är att installera ett bibliotek på den egna servern och hänvisa till det.

<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>

I Suomi.fi-meddelanden används i fortsättningen endast REST-gränssnittet samt POST-gränssnittet för elektroniska blanketter. De gamla gränssnitten (WS, SFTP och SMTP) tas ur bruk 1.1.2027. POST-gränssnittet som används i blanketterna i Suomi.fi-meddelanden behöver alltid ett annat gränssnitt parallellt för att meddelandet ska nå organisationen. I fortsättningen ska detta andra gränssnitt vara REST.

Om ni i er organisation för närvarande får elektroniska blanketter i Suomi.fi-meddelanden per e-post (till exempel till registratorskontorets e-postadress) använder ni ett SMTP-gränssnitt. Efter 1.1.2027 går blanketterna inte längre till er organisations e-postprogram, eftersom gränssnittet tas ur bruk.

I fortsättningen ska blanketterna styras via REST-gränssnittet direkt till systemet, till exempel till er organisations ärendeportal eller ärendehanteringssystem. Kontakta systemleverantören som tillhandahåller blankettjänsten för mer information om vart blanketterna i fortsättningen kan styras i och med gränssnittsändringen.

Uppdaterad: 2.1.2026

Digitalisera din ärendestig

Förbättra informationshanteringen

Förbättra kvaliteten på tjänsterna

Säkra dina data

Öppna, dela och utnyttja data