VIRANOMAISEN PALUUKANAVA WS API. Suomi.fi-viestit julkinen rajapinta

Transkriptio

1 VIRANOMAISN PALUUANAVA Suomi.fi-viestit julkinen rajapinta

2 V.01 RAJAPINTAUVAUS V (9) DOUMNTINHALLINTA Omistaja Laatinut Lasse Pynnönen, VR Suomi.fi-viestit sovelluskehitystiimi Tarkastanut Hyväksynyt VRSION HALLINTA versionro mitä tehty pvm/henkilö 0.1 Dokumentin pohja tehty 0.2 Tarkastettu/esiluettu. Poistettu ylimääräisiä elementtejä ja tehty täydennyksiä, kommentoitu jne. ommenttikierrokselle. i vielä julkaisukelpoinen. 1.0 ommentit poistettu 1.1 Paremmat kuvaukset kutsuille ja kuittauksille / Jyri Piirainen / Jarmo arttunen / Hannu orkeala / Pertti Suomela

3 V.01 RAJAPINTAUVAUS V (9) Sisällysluettelo 1 Yleistä Rajapinnan tekniset yleistiedot Paluukanava URL Viestin viranomaistiedot Tilakoodien selitteet Operaatiot Vieohteita... 5 Vastaussanoma VieohdeTiloja... 7 yselysanoma... 7 Vastaussanoma SOAP Fault simerkit... 9

4 V.01 RAJAPINTAUVAUS V (9) VIRANOMAISN PALUUANAVA 1 Yleistä Tässä dokumentissa kuvataan Suomi.fi-Viestit (Viestit-palvelun) paluukanavan rajapinta. on viranomaiselle vapaaehtoinen palvelu, jonka toteuttamalla Suomi.fi-Viestit voi toimittaa viranomaisjärjestelmälle viestien toimitus- ja lukukuittauksia sekä kansalaisten lähettämiä viestejä. Viestirakenne noudattaa jo aiemmassa vaiheessa (ansalaisen asiointitili) vuoden 2010 suunniteltua rakennetta. Rajapintaan on tehty muutamia muutoksia/lisäyksiä, mutta yhteensopivuus vanhaa rajapintaa käyttävien viranomaisjärjestelmien kanssa on säilytetty. Siitä aiheutuu myös se, että rakenteessa esiintyy vanhaa Asiointitili- termiä. 1.1 Rajapinnan tekniset yleistiedot Sanomissa käytetään UTF-8 enkoodausta ja käytetty formaatti on text/xml. Taulukko 1: Rajapinnan endpoint Url Rajapinnan osoitteen määrittelee kukin viranomainen itse ja ilmoittaa Viestit-palvelulle. Taulukko 2: Viranomais SOAP API http asetukset Operaatio SoapAction Vieohteita VieohdeTiloja Paluukanava URL Soap sanoman Headerissa välitetään url viranomaisen järjestelmään: enttä Selite Tyyppi paluukanavaurl Viranomaisjärjestelmän URL 1.3 Viestin viranomaistiedot Jokaisessa viestissä on ensimmäisenä elementtinä viranomaisen tiedot. Taulukko 3: Viranomainen elementti enttä Selite Tyyppi Pakollinen ViranomaisTunnus Viranomaisen tunnus, jonka viestinvälityspalvelu on antanut. sim tai Vero PalveluTunnus Viranomaisen palvelutunnus, jonka viestinvälityspalvelu on antanut viranomaisen käyttöön. sim. TRASHA

5 V.01 RAJAPINTAUVAUS V (9) ayttajatunnus SanomaTunniste SanomaVersio SanomaVarmenneNimi Viranomaisjärjestelmän käyttäjän tunniste, joka on ajon suorittanut. sim. timakar Viestin yksilöivä tunniste. sim. GUID Viestin kutsun versionumero. sim. 1.0 Viranomaisjärjestelmän käyttämän varmenteen varmennenimi (Common Name). sim. Verohallinto 1.4 Tilakoodien selitteet Jokaisessa vastaussanomassa on Tilaoodi-elementti, joka koostuu tilakoodista, tilakoodin kuvauksesta (= virhekoodin selite) ja sanoman tunnisteesta (= viestin yksilöivä tunniste). Taulukko 4: Vastaussanoman Tilaoodi kentän arvot oodi uvaus 0 utsu onnistunut. 400 utsuviesti on sisällöltään tai muodoltaan virheellinen. 403 Viranomaistunnus ei vastaa autentikoitua. 404 Palvelutunnus ei vastaa viranomaistunnusta. 405 Toiminto ei sallittu viranomaiselle. 406 Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 Muu virhe käsittelyssä. 453 ohdepalvelu ei vastaa. 2 Operaatiot 2.1 Vieohteita Tällä kutsulla Viestit-palvelu toimittaa viranomaisjärjestelmälle kansalaisen lähettämän viestin. yselysanoma Taulukko 3: Vieohteita ysely elementti (simerkki) enttä Selite Tyyppi Pakollinen ohdemaara Lähetettävien asioiden lukumäärä int ohteet Asiat kokoava elementti elementti ohde Yhden asian tiedot kokoava elementti [0..n] Asiakas Asiaan liittyvän asiakkaan tiedot. elementti Sama asia voidaan lähettää usealle asiakkaalle, jolloin näitä elementtejä voi olla useita. AsiakasTunnus Asiakkaan henkilötunnus Sahkoposti Sähköpostiosoite Matkapuhelin Puhelinnumero TunnusTyyppi Vakiomerkkijono: SSN AsiointitiliTunniste Viittaus elementti ViittausTunniste Liittyvän asian tunniste

6 V.01 RAJAPINTAUVAUS V (9) ViittausTunnisteTyyppi Liittyvän asian tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste Nimeke Asian otsikkotieto, jonka viranomaisjärjestelmä tuottaa asiak- kaan omalla kielellä. LahetysPvm Lähetyspäivämäärä datetime LahettajaNimi Lähettäneen viranomaisen tarkempi nimi. uvausteksti Vapaamuotoinen kuvaus Tiedostot Asiaan liittyvät asiakirjat elementti Tiedosto elementti [0..n] Tiedostonuvaus Asiakirjan selite TiedostoURL Tiedoston URL, josta asiakirja on ladattavissa, jos käytetään viranomaisen omaa välivarastoa. TiedostoSisalto Tiedosto BAS64 -enkoodattuna. Tiedostooko Tiedoston koko kilotavuina. TiedostoMuoto Tiedoston formaatti (mime type). TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen. Viranomaisenmail Sähköpostiliityntä: Puolipisteellä eroteltuna joko 1 tai useampi sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. Vastaussanoma Taulukko 4: VieohteitaResponse elementti (simerkki) lementti Selite Tilaoodi Tilaoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=utsu onnistunut Virhekoodit: 400=utsuviesti on sisällöltään tai muodoltaan virheellinen. Viestit-palvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikoitua. VIA palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Viestit-palvelu palauttaa. 405=Toiminto ei ole sallittu viranomaiselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Viestit-palvelu palauttaa. 453= ohdepalvelu ei vastaa. VIA palauttaa, jos ei saa viestit-palveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). Tilaoodiuvaus Virhekoodin selitekenttä. simerkiksi kutsussa oleva ohdemaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa.

7 V.01 RAJAPINTAUVAUS V (9) ohdemaara ohteet ohde ViranomaisTunniste Asiakas AsiakasTunnus TunnusTyyppi AsiointitiliTunniste ohteentila ohteentilauvaus äsiteltyjen asioiden lukumäärä. äsitellyt asiat kokoava elementti. Yhden asian tiedot kokoava elementti. Asian yksilöivä tunniste viranomaisen järjestelmässä. Sama tunniste, kuin kutsuviestissä. Asiaan liittyvän asiakkaan tiedot. Asia liitetään kyseisen loppuasiakkaan Viestit -palvelutiliin. Loppuasiakkaan henkilötunnus. Vakiomerkkijono: SSN Asian yksilöivä tunniste, jonka Viestit -palvelu on asialle antanut. Asiointitilitunniste yksilöi viestin aina asiakaskohtaisesti. li toimitettaessa Viestit - palvelutilille sama asia, joka liittyy moneen asiakkaaseen, on asialla kaikille asiakkaille yhteinen viranomaistunniste ja asiakaskohtainen asiointitilitunniste. utsun tallennuksen käsittelytila. äsittelytila palautetaan asiakaskohtaisesti. Onnistuneet statukset: (tässä tilanteessa asia on tallennettu asiointitilipalveluun) 200=kutsu onnistunut ja tallennettu Viestit -palvelutilille. Jos ei toimitettavia liitetiedostoja, voidaan käsitellä loppuun kutsun yhteydessä. 202=kutsu onnistunut ja laitettu käsittelyyn Viestit -palvelussa, mutta se ei vielä näy asiakkaan Viestit -palvelutilillä. Lopullinen vastaus on haettavissa erikseen erillisellä kutsulla. päonnistuneet statukset: (tässä tilanteessa asiaa ei ole tallennettu Viestit -palveluun) 520=annetulla tunnisteella löytyy jo asia, joka on tallennettu Viestit -palveluun eikä se ole virheellinen 521=liitoksen kohdetta (Viittaus) ei löydy tai se on eri asiakkaan asia 522=ongelma liitetiedoston tallennuksessa 523=ongelma liitetiedoston virustarkistuksessa 524=loppuasiakas ei ota vastaan asioita Viestit palvelutilille (tili passivoitu) 525=asian tietosisällössä virheitä 528=ei sallittu liitetiedoston tyyppi 529=liian iso liitetiedoston koko 550=muu virhe Tarkempi kuvaus virheestä. simerkiksi liitetiedostoon liittyvän virheen tapauksessa tiedoston nimi. 2.2 VieohdeTiloja Tällä kutsulla Viestit-palvelu toimittaa viranomaisjärjestelmälle viestien toimitus- ja lukukuittauksia. yselysanoma Taulukko 5: VieohdeTiloja ysely elementti (simerkki) Parametri Selite Tyyppi Pakollinen ohdemaara Lähetettävien asioiden lukumäärä int ohteet Asiat kokoava elementti elementti ohde Yhden asian tiedot kokoava elementti [0..n]

8 V.01 RAJAPINTAUVAUS V (9) ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä, jonka tulee olla pysyvä, yksilöivä tunniste. Asiakas Asiaan liittyvän asiakkaan tiedot. elementti Sama asia voidaan lähettää usealle asiakkaalle, jolloin näitä elementtejä voi olla useita. AsiakasTunnus Asiakkaan henkilötunnus TunnusTyyppi Vakiomerkkijono: SSN AsiointitiliTunniste ohteentila uittauksen lajikoodi: int 200=Viesti toimitettu 220=Viesti avattu 230=Viesti kuitattu vastaanotetuksi (todisteellinen tiedoksianto) ohteentilapvm datetime ohteentilauvaus Viranomaisenmail Sähköpostiliityntä: Puolipisteellä eroteltuna joko 1 tai useampi sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. Nimeke e Vastaussanoma Taulukko 6: ViekohdeTilojaResponse elementti (simerkki) lementti Selite Tilaoodi Tilaoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=utsu onnistunut Virhekoodit: 400=utsuviesti on sisällöltään tai muodoltaan virheellinen. Viestitpalvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikoitua. VIA-palvelu palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Viestit-palvelu palauttaa. 405=Toiminto ei ole sallittu viranomaiselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Viestit -palvelu palauttaa. 453= ohdepalvelu ei vastaa. VIA -palvelu palauttaa, jos ei saa Viestit palveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). Tilaoodiuvaus Virhekoodin selitekenttä. simerkiksi kutsussa oleva ohdemaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa

9 V.01 RAJAPINTAUVAUS V (9) 2.3 SOAP Fault 3 simerkit Jos palvelun suorituksessa tapahtuu tekninen virhe, palvelu palauttaa SOAP Faultin kutsujalle. Viestin välitön uudelleen lähetys on turhaa. simerkkisanomat on saatavissa erillisinä XML-tiedostoina.