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 / Jyri Piirainen / Jarmo arttunen / Hannu orkeala

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 päivittää viestin tiloja viranomaisjärjestelmässä tai viedä sinne uusia 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 ayttajatunnus Viranomaisjärjestelmän käyttäjän tunniste, joka on ajon suorittanut. sim. timakar

5 V.01 RAJAPINTAUVAUS V (9) SanomaTunniste SanomaVersio SanomaVarmenneNimi 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ämän rajapinnan avulla voidaan viedä uusi viestejä viranomaisjärjestelmään. 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 ViittausTunnisteTyyppi Liittyvän asian tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste

6 V.01 RAJAPINTAUVAUS V (9) 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. ohdemaara äsiteltyjen asioiden lukumäärä. ohteet äsitellyt asiat kokoava elementti. ohde Yhden asian tiedot kokoava elementti.

7 V.01 RAJAPINTAUVAUS V (9) ViranomaisTunniste Asiakas AsiakasTunnus TunnusTyyppi AsiointitiliTunniste ohteentila ohteentilauvaus 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ämän kyselyn avulla voidaan päivittää viranomaisjärjestelmässä olevan viestin tiloja. 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] ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä, jonka tulee olla pysyvä, yksilöivä tunniste. Asiakas Asiaan liittyvän asiakkaan tiedot. Sama asia voidaan lähettää usealle elementti

8 V.01 RAJAPINTAUVAUS V (9) asiakkaalle, jolloin näitä elementtejä voi olla useita. AsiakasTunnus Asiakkaan henkilötunnus TunnusTyyppi Vakiomerkkijono: SSN AsiointitiliTunniste ohteentila int 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 2.3 SOAP Fault Jos palvelun suorituksessa tapahtuu tekninen virhe, palvelu palauttaa SOAP Faultin kutsujalle. Viestin välitön uudelleen lähetys on turhaa.

9 V.01 RAJAPINTAUVAUS V (9) 3 simerkit simerkkisanomat on saatavissa erillisinä XML-tiedostoina.