Viestinvälityspalvelu Viranomais API Kuvaus v. 0.3

Transkriptio

1 Viestinvälityspalvelu Viranomais API Kuvaus v. 0.3

2 Contents Yleistä... 3 Versiohistoria... 3 Viranomais API... 3 Viestin viranomaistiedot... 3 Lisää Kohteita... 6 Pyyntöparametrit... 6 Vastauselementit SOAP Fault simerkit Hae Asiakkaita Pyyntöparametrit Vastauselementit SOAP Fault simerkit Hae Tila Tieto Pyyntöparametrit Vastauselementit SOAP Fault Lähetä Viesti Pyyntöparametrit Vastauselementit SOAP Fault simerkit... 32

3 Yleistä Tässä dokumentissa kuvataan viestinvälityspalvelun (VVP) tarjoamat viranomaisrajapinnat. Nämä rajapinnat julkaistaan viranomaisjärjestelmille ja julkaisu tapahtuu VIA palveluväylän kautta. Versiohistoria Versio Päivä Tekijä Kuvaus Tero Rönkä Versio jossa alustavasti kuvattu paperipostituksen rajapinta Mikko Päivitetty paperipostituksen rajapinta. Alakunnas Mikko Alakunnas Lisätty uusia viranomaisrajapintoja. Viranomais API Viranomais API on VIA julkaistu rajapinta, jolla voidaan käsitellä viestinvälityspalvelun viestejä ja tilejä rajoitetusti. Viestirakenne noudattaa jo aiemmassa vaiheessa n tienoilla suunniteltua rakennetta. Joitain muutoksia on tehty, mutta yhteensopivuus vanhaa rajapintaa käyttävien järjestelmien kanssa on säilytetty. Siitä aiheutuu myös seikka että rakenteessa esiintyy vanhaa Asiointitili- termiä. Vastausformaatti on text/xml. API sisältää seuraavat operaatiot: Lisää Kohteita (lähetetään viestejä) Hae Asiakkaita (haetaan tilejä) Hae Tila Tieto (haetaan vvp-palvelun status) Lähetä Viesti (lähetetään viesti, joka tulostetaan ja lähetetään vastaanottajalle postissa) Operaatiot parametreineen ja esimerkkeineen on kuvattu tässä dokumentissa. Hae Tila Tieto -operaatiota ei ole vielä toteutettu viestinvälityspalveluun. Viestin viranomaistiedot Jokaisessa viestissä on ensimmäisenä elementtinä viranomaisen (=lähettäjän) tiedot:

4 Kuva 1. Viranomainen -elementti.

5 Viranomaisen tietorakenteen kenttien kuvaukset. Header Selite Tyyppi Pakollinen Viranomaisen tunnistava tieto, jonka ViranomaisTunnus viestinvälityspalvelu on i (käytännössä K) antanut sim tai Vero Viranomaisen palvelutunnus, jonka viestinvälityspalvelu PalveluTunnus on antanut viranomaisen käyttöön. i (käytännössä K) KayttajaTunnus sim. TRASHA Viranomaisjärjestelmän käyttäjän tunniste, joka on ajon suorittanut. i SanomaTunniste SanomaVersio SanomaVarmenneNimi sim. timakar Viestin yksilöivä id sim. GUID Viestin kutsun versionumero sim. 1.0 Viranomaisjärjestelmän käyttämän varmenteen varmennenimi (Common Name). sim. Verohallinto i (käytännössä K) Osoitetiedot Viranomaisen osoitetiedot lementti i Nimi Katuosoite Postinumero Paikkakunta Maa Yhteyshenkilo Viranomaisen nimi K Viranomaisen käyntiosoite K Postinro K Toimipaikka K Maa Yhteyshenkilön nimi ja puhelin. Henkilöä kontaktoidaan esim. virhetapauksissa manuaalisesti. Kyllä Kyllä

6 Lisää Kohteita Tämän rajapinnan avulla viranomaisjärjestelmä voi lähettää viestinvälityspalveluun asiointiasioita, tiedoksiantoja ja vastauksia kyselyihin. Lähetetyt asiat voivat sisältää linkkejä viranomaisen välivarastossa oleviin asiakirjoihin tai kokonaisia asiakirjoja, jotka tallennetaan viestinvälitypalvelun välivarastoon. Lähetetty asia voidaan liittää viestinvälitypalvelussa jo olevaan asiaan, jolloin kyseinen asia näkyy asiakkaalle kyseisen asiointiasian yhteydessä (esimerkiksi lisäselvityspyyntö tai vastaus kysymykseen). Lähetetty asia voi olla myös todisteellinen tiedoksianto, jolloin paluukanavan kautta (WSPA4) saadaan tieto tiedoksiannon kuittauksesta. Viranomaisen tulee toimittaa asialle tunniste, jonka tulee olla viranomaisen palvelun sisällä yksilöllinen ajasta riippumatta. Kutsun vastauksena voidaan toimittaa lähetettyjen asioiden tallennustiedot asiakohtaisesti (synkroninen) tai pelkkä kuittaus asioiden vastaanottamisesta (asynkroninen). Viestintätyyppi on valittavissa liittymisen yhteydessä viranomaiskohtaisesti. Pyyntöparametrit Kuva 2. LisaaKohteita -elementti.

7

8 Kuva 3. Kohde -elementti Kohde -elementti (0..n). Parametri Selite Tyyppi Pakollinen Asiakas Asiaan liittyvän asiakkaan tiedot. Sama asia voidaan lähettää usealle asiakkaalle, jolloin näitä elementtejä voi olla useita. lementti AsiakasTunnus Asiakkaan HTU Sahkoposti Matkapuhelin TunnusTyyppi Nimi Katuosoite Postinumero Paikkakunta Maa mail-osoite Puhelinnumero SSN Asiakkaan nimi Jakeluosoite Postinumero Toimipaikka Maakoodi ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä, jonka tulee olla pysyvä, yksilöivä tunniste. Viittaus lementti ViittausTunniste Liittyvän asian tunniste ViittausTunnisteTyyppi VahvistusVaatimus Liittyvän asian tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste Todisteellinen tiedoksianto, joka vaatii kuittauksen lukemisesta: 1=kyllä, 0=ei

9 VaadiLukukuittaus Parametrin avulla voidaan pakottaa viestinvälityspalvelu lähettämään kuittausviesti kohteesta, vaikka lukukuittausten lähettäminen olisi muuten disabloitu. AsiaNumero Viestinvälityspalvelussa näytettävä asiakirjan tunniste (esim. päätöksen numero) Nimeke Asian otsikkotieto, jonka viranomaisjärjestelmä tuottaa asiakkaan omalla kielellä. LahetysPvm Lähetyspäivämäärä datetime K LahettajaNimi Lähettäneen viranomaisen tarkempi nimi KuvausTeksti Vapaamuotoinen kuvaus K Maksullisuus Tieto maksullisuudesta MaksamisKuvausTeksti Maksun vapaamuotoinen kuvaustieto. sim. hinta ja maksuohjeet. Tila Asian viranomaiskäsittelyn tilatieto Asian TilaKoodi viranomaisjärjestelmässä olevaa käsittelyn tilaa kuvaava määrämuotoinen tilatieto Tila Asian viranomaisjärjestelmässä olevaa käsittelyn tilaa kuvaava vapaamuotoinen tieto TilaKuvaus tekijä Tilaan liittyvä lisätieto. simerkiksi päätöksen

10 TilaPvm Tilan päivämäärätieto. li milloin päätös on tehty datetime K Tiedostot (0..n) Asiaan liittyvät asiakirjat TiedostonKuvaus Asiakirjan selite String TiedostoURL Tiedoston URL, josta asiakirja on ladattavissa, jos käytetään viranomaisen omaa välivarastoa TiedostoSisalto Tiedosto BAS64 - enkoodattuna TiedostoKoko Tiedoston koko kilotavuina TiedostoMuoto Tiedoston formaatti (mime type) TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen Alkusivu Paperitulostuksessa käytettävän etusivun numero Sivumaara Paperitulostuksessa käytettävä sivumäärä Sähköpostiliityntä: Puolipisteellä eroteltuna joko yksi tai useampi Viranomaisenmail sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. Heräteviestin sisältö, SmsLisatieto joka välitetään matkapuhelimeen Heräteviestin otsikko, maillisatietootsikko joka välitetään sähköpostiin Heräteviestin sisältö, maillisatietosisalto joka välitetään sähköpostiin Asiakkaalle TavoitettavuusTietoSMS tallennettava SMSnotifikaatin String

11 lähetysnumero, joka tallennetaan asiakaan tietoihin, mikäli kutsun seurauksena asiakkaalle luodaan pikatili. Mikäli asiakkaalla on tili käytössä, ei kenttää huomioida. TavoitettavuusTietomail Kenttä ei ole vielä käytössä. Asiakkaalle tallennettava sähköpostinotifikaatin lähetysnumero, joka tallennetaan asiakaan tietoihin, mikäli kutsun seurauksena asiakkaalle luodaan pikatili. Mikäli asiakkaalla on tili käytössä, ei kenttää huomioida. Vastauselementit Kuva 4. LisaaKohteitaResponse -elementti.

12 Kuva 5. Kohde -elementti. lementti TilaKoodi Selite Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=kutsu onnistunut Virhekoodit: TilaKoodi 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. viestinvälityspalvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikaatiotietoa. VIA palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. viestinvälityspalvelu palauttaa. 405=Toiminto ei ole sallittu kyseiselle viranomaistunnukselle ja palvelutunnukselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. viestinvälityspalvelu palauttaa. 453= Kohdepalvelu ei vastaa. VIA palauttaa, jos ei saa viestinvälityspalveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet).

13 Virhekoodin selitekenttä. TilaKoodiKuvaus simerkiksi kutsussa oleva KohdeMaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa. KohdeMaara Kohteet Kohde Käsiteltyjen asioiden lukumäärä. Käsitellyt asiat kokoava elementti. Annetaan vain jos synkroninen yhteystapa. Yhden asian tiedot kokoava elementti. ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä. Sama tunniste, kuin kutsuviestissä. Asiakas Asiaan liittyvän asiakkaan tiedot. Asia liitetään kyseisen asiakkaan viestinvälityspalvelutiliin. Asiakas Asiaan liittyvän asiakkaan tiedot. Asia liitetään kyseisen asiakkaan asiointitiliin. AsiakasTunnus Asiakkaan tunniste, tunnisteen tyyppi seuraavassa elementissä. TunnusTyyppi Asiakkaan tunnisteen tyyppi. AsiointitiliTunniste KohteenTila Asian yksilöivä tunniste, jonka viestinvälityspalvelu on asialle antanut. Asiointitilitunniste yksilöi viestin aina asiakaskohtaisesti. li toimitettaessa viestinvälityspalvelutilille sama asia, joka liittyy moneen asiakkaaseen, on asialla kaikille asiakkaille yhteinen viranomaistunniste ja asiakaskohtainen asiointitilitunniste. Kutsun tallennuksen käsittelytila. Käsittelytila palautetaan asiakaskohtaisesti. Onnistuneet statukset: (tässä tilanteessa asia on tallennettu asiointitilipalveluun) 200=kutsu onnistunut ja tallennettu viestinvälityspalvelutilille. Jos ei toimitettavia liitetiedostoja, voidaan käsitellä loppuun kutsun yhteydessä. 202=kutsu onnistunut ja laitettu käsittelyyn viesinvälityspalvelussa, mutta se ei vielä näy asiakkaan viestinvälityspalvelutilillä. Lopullinen vastaus on haettavissa erikseen erillisellä kutsulla. päonnistuneet statukset: (tässä tilanteessa asiaa ei ole tallennettu viestinvälityspalveluun) 520=annettulla tunnisteella löytyy jo asia, joka on tallennettu viestinvälityspalveluun eikä se ole virheellinen

14 521=liitoksen kohdetta (Viittaus) ei löydy tai se on eri asiakkaan asia 522=ongelma liitetiedoston tallennuksessa 523=ongelma liitetiedoston virustarkistuksessa 524=asiakas ei ota vastaan asioita viestinvälityspalvelutilille 525=asian tietosisällössä virheitä 528=ei sallittu liitetiedoston tyyppi 529=liian iso liitetiedoston koko 550=muu virhe KohteenTilaKuvaus Tarkempi kuvaus virheestä. simerkiksi liiitetiedostoon liittyvän virheen tapauksessa tiedoston nimi. SOAP Fault Palautetaan SOAP Fault jos tapahtuu tekninen virhe ja viestin välitön uudelleen lähetys on turhaa. simerkit simerkki 1: Lisätään kohde liitteellä simerkkipyyntö <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s=" <s:header> <Action s:mustunderstand="1" xmlns=" velut/lisaakohteita</action> </s:header> <s:body xmlns:xsi=" xmlns:xsd=" <LisaaKohteita xmlns=" <Viranomainen> <ViranomaisTunnus>VANTAA</ViranomaisTunnus> <PalveluTunnus>PÄIVÄHOITOHAKMUS</PalveluTunnus> <KayttajaTunnus>kkayttaja</KayttajaTunnus> <SanomaTunniste>1234</SanomaTunniste> <SanomaVersio>1.0</SanomaVersio> <SanomaVarmenneNimi>innofactor.com</SanomaVarmenneNimi> </Viranomainen> <Kysely> <KohdeMaara>1</KohdeMaara> <Kohteet> <Kohde> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN" /> <ViranomaisTunniste> </ViranomaisTunniste> <Viittaus ViittausTunniste=" " ViittausTunnisteTyyppi="ViranomaisTunniste" />

15 <VahvistusVaatimus>0</VahvistusVaatimus> <AsiaNumero> </AsiaNumero> <Nimeke>Työttömyyskorvauspäätös</Nimeke> <LahetysPvm> T12:54:00</LahetysPvm> <LahettajaNimi>Kirjavalan työvoimatoimisto</lahettajanimi> <KuvausTeksti>Päätös työttömäksi työnhakijaksi ilmoittautuneelle myönnettävästä työttömyyspäivärahasta</kuvausteksti> <Maksullisuus>0</Maksullisuus> <Tila> <TilaKoodi>123</TilaKoodi> <Tila>Käsitelty</Tila> <TilaKuvaus>Käsittelijä: Kalle Käyttäjä</TilaKuvaus> <TilaPvm> T14:45:00</TilaPvm> </Tila> <Tiedostot> <Tiedosto> <TiedostonKuvaus>Päätös työttömyyspäivärahasta</tiedostonkuvaus> <TiedostoSisalto>AFD8AW4NRCA8PPA3R...A384WNRC9N2</TiedostoSisalto> <TiedostoKoko>34</TiedostoKoko> <TiedostoMuoto>application/pdf</TiedostoMuoto> <TiedostoNimi> pdf</TiedostoNimi> </Tiedosto> <Tiedosto> <TiedostonKuvaus>Muutoksenhakulomake annettuun päätökseen</tiedostonkuvaus> <TiedostoSisalto>AFD8AW4NRCA8PPA3R...A384WNRC9N2</TiedostoSisalto> <TiedostoKoko>125</TiedostoKoko> <TiedostoMuoto>application/pdf</TiedostoMuoto> <TiedostoNimi>muutoksenhakulomake.pdf</TiedostoNimi> </Tiedosto> </Tiedostot> </Kohde> </Kohteet> </Kysely> </LisaaKohteita> </s:body> </s:nvelope> simerkkivastaus <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s=" <s:body xmlns:xsi=" xmlns:xsd=" <LisaaKohteitaResponse xmlns=" <LisaaKohteitaResult> <TilaKoodi> <TilaKoodi>200</TilaKoodi> <TilaKoodiKuvaus>kutsu onnistunut</tilakoodikuvaus> <SanomaTunniste>1236</SanomaTunniste> </TilaKoodi> <KohdeMaara>1</KohdeMaara> <Kohteet> <Kohde> <ViranomaisTunniste> </ViranomaisTunniste> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <AsiointitiliTunniste> </AsiointitiliTunniste>

16 <KohteenTila>202</KohteenTila> <KohteenTilaKuvaus></KohteenTilaKuvaus> </Asiakas> </Kohde> </Kohteet> </LisaaKohteitaResult> </LisaaKohteitaResponse> </s:body> </s:nvelope> Hae Asiakkaita Tämän kyselyn avulla viranomaisjärjestelmä voi tarkistaa, mitkä sen asiakkaista ovat viestinvälityspalvelun käyttäjiä ja voivat siis vastaanottaa viestejä viestinvälityspalvelun kautta sähköisessä muodossa. Kyselyn avulla voi hakea kaikki omat asiakkaat tai tarkistaa annetun tai annettujen hetujen osalta, ovatko he ottaneet viestinvälityspalvelun käyttöön. Vastauksessa saadaan tieto, onko asiakas viestinvälityspalvelun käyttäjä. Kyselyä voidaan myös rajata ajan suhteen siten, että haetaan vain tietyllä aikavälillä viestinvälityspalvelun käyttäjäksi liittyneet. Kuva 6. HaeAsiakkaita -elementti.

17 Kuva 7. Asiakas -elementti. Pyyntöparametrit Parametri Selite Tyyppi Pakollinen Kysely Tyhjä elementti ei sisällä mitään tietoa. Kysely_WS10 Kyselytyypin kertova elementti. Joko kaikki asiakkaat Kaikki tai annettujen asiakkaiden tiedot Asiakkaat. KyselyLaji Kyselylajin "Kaikki" tapauksessa, tulee antaa myös KyselyAlku ja KyselyLoppu-tiedot. Kyselylajin "Asiakkaat" tapauksessa, tulee antaa Asiakkaat-elementissä tarkistettavat HTUT.

18 KyselyAlku Mikäli hakuehto palauttaa liian paljon asiakkaita, Mikäli elementti on annettu, palautetaan vain annettua hetkeä myöhemmin tapahtuneet viestinvälityspalvelun käyttöönotot ja viestinvälityspalvelun poiskytkennät. datetime K KyselyLoppu HUOM! Pakollinen, jos haetaan Kyselytyypillä Kaikki. Mikäli elementti on annettu, palautetaan vain annettua hetkeä aiemmin tapahtuneet viestinvälityspalvelun käyttöönotot ja viestinvälityspalvelun poiskytkennät. datetime K Asiakkaat HUOM! Pakollinen, jos haetaan Kyselytyypillä Kaikki. Asiakkaat kokoava elementti, jos haetaan annetun LISTAn sisältämien asiakkaiden tiedot ArrayOfAsiakas *=pakollinen jos haetaan KyselyTyypillä Asiakkaat Asiakas Yhden asiakkaan tiedot kokoava elementti Asiakas Asiakkaan tunniste, AsiakasTunnus tunnisteen tyyppi seuraavassa elementissä. TunnusTyyppi SSN Vastauselementit

19 Kuva 8. HaeAsiakkaitaResponse -elementti. Kuva 9. Asiakas -elementti. HaeAsiakkaitaResult -elementti. lementti TilaKoodi Selite Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: TilaKoodi 0=kutsu onnistunut Virhekoodit: 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. viestinvälityspalvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikaatiotietoa. VIA palauttaa.

20 404=Palvelutunnus ei vastaa viranomaistunnusta. viestinvälityspalvelu palauttaa. 405=Toiminto ei ole sallittu kyseiselle viranomaistunnukselle ja palvelutunnukselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. viestinvälityspalvelu palauttaa. 453= Kohdepalvelu ei vastaa. VIA palauttaa, jos ei saa viestinvälityspalveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). Virhekoodin selitekenttä. TilaKoodiKuvaus simerkiksi kutsussa oleva KohdeMaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa Asiakkaat Asiakkaat kokoava elementti. AsiakasTunnus Asiakkaan tunniste, tunnisteen tyyppi seuraavassa elementissä. TunnusTyyppi Asiakkaan tunnisteen tyyppi. Tila TilaPvm TiliPassivoitu Asiakkaan tilatieto 300=asiakkaalla on tili käytössä (muut arvot tarkoittavat, että tili ei ole käytössä) 310=asiakkaalla ei ole viestinvälityspalvelua käytössään (ei ole ottanut käyttöön koko tiliä tai tili ei ole aktiivisena) 320=asiakkaalla on tili käytössä, mutta asiakas ei ota vastaan asioita (asiakas on estänyt viestien lähetyksen itselleen kyseiseltä viranomaiselta) Asiakkaan suostumuksen viimeisimmän tilan voimaanastumispäivä. Mikäli ei ole antanut suostumusta, tilan päivämääränä on tyhjä tieto. Mikäli suostumus annettu, suostumuksen tekohetki. Mikäli suostumus on poistettu, suostumuksen poistohetki. Lisätietokenttä joka kertoo, onko asiakas passivoinut asiointitilinsä. Jos tili passivoitu niin saa arvon 1, muuten aina 0. SOAP Fault

21 Palautetaan SOAP Fault, jos tapahtuu tekninen virhe ja viestin välitön uudelleen lähetys on turhaa. simerkit simerkki 1: Hae Asiakkaita simerkkipyyntö <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s=" <s:header> <Action s:mustunderstand="1" xmlns=" velut/haeasiakkaita</action> </s:header> <s:body xmlns:xsi=" xmlns:xsd=" <HaeAsiakkaita xmlns=" <Viranomainen> <ViranomaisTunnus>VANTAA</ViranomaisTunnus> <PalveluTunnus>PÄIVÄHOITOHAKMUS</PalveluTunnus> <KayttajaTunnus> </KayttajaTunnus> <SanomaTunniste>1234</SanomaTunniste> <SanomaVersio>1.0</SanomaVersio> <SanomaVarmenneNimi>innofactor.com</SanomaVarmenneNimi> </Viranomainen> <Kysely> <KyselyLaji>Kaikki</KyselyLaji> <KyselyAlku> T17:18:00</KyselyAlku> <KyselyLoppu> T17:18:00</KyselyLoppu> </Kysely> </HaeAsiakkaita> </s:body> </s:nvelope> simerkkivastaus <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s=" <s:header /> <s:body xmlns:xsi=" xmlns:xsd=" <HaeAsiakkaitaResponse xmlns=" <HaeAsiakkaitaResult> <TilaKoodi> <TilaKoodi>200</TilaKoodi> <TilaKoodiKuvaus>kutsu onnistui</tilakoodikuvaus> <SanomaTunniste>1234</SanomaTunniste> </TilaKoodi> <Asiakkaat> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN">

22 <Tila>300</Tila> <TilaPvm> T21:42:00</TilaPvm> <TiliPassivoitu>0</TiliPassivoitu> </Asiakas> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <Tila>310</Tila> <TilaPvm> T00:00:00</TilaPvm> <TiliPassivoitu>0</TiliPassivoitu> </Asiakas> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <Tila>310</Tila> <TilaPvm> T20:02:00</TilaPvm> <TiliPassivoitu>1</TiliPassivoitu> </Asiakas> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <Tila>320</Tila> <TilaPvm> T22:54:00</TilaPvm> <TiliPassivoitu>0</TiliPassivoitu> </Asiakas> </Asiakkaat> </HaeAsiakkaitaResult> </HaeAsiakkaitaResponse> </s:body> </s:nvelope> Hae Tila Tieto HUOM! Tätä operaatiota ei ole vielä toteutettu viestinvälityspalveluun. Tällä pyynnöllä viranomaisjärjestelmä voi tarkistaa Viestinvälityspalvelun tilan. Kuva 10. HaeTilaTieto -elementti. Pyyntöparametrit Parametri Selite Tyyppi Pakollinen Kysely Tyhjä elementti ei sisällä mitään tietoa. Kysely_WS10 Vastauselementit

23 Kuva 11. HaeTilaTietoResponse -elementti. lementti TilaKoodi Selite Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=kutsu onnistunut Virhekoodit: TilaKoodi 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. Asiointitili palauttaa. 403=Viranomaistunnus ei vastaa autentikaatiotietoa. VIA palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Asiointitilipalvelu palauttaa. 405=Toiminto ei ole sallittu kyseiselle viranomaistunnukselle ja palvelutunnukselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Asiointitili palauttaa. 453= Kohdepalvelu ei vastaa. VIA palauttaa, jos ei saa asiointitilipalveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). TilaKoodiKuvaus Virhekoodin selitekenttä. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa SOAP Fault

24 Palautetaan SOAP Fault jos tapahtuu tekninen virhe ja viestin välitön uudelleen lähetys on turhaa. Lähetä Viesti Tällä pyynnöllä viranomaisjärjestelmä voi lähettää viestejä käyttäjille, jotka päätyvät paperitulostukseen. LahetaViesti -elementti Kysely tietorakenteen kenttien kuvaukset. Pyyntöparametrit Parametri Selite Tyyppi Pakollinen KohdeMaara Lähettävien asioiden lukumäärä int K Kohteet Kohteet sisältävä elementti ArrayOfKohde_WS2

25 Kohde elementti (0..n)

26 Parametri Selite Tyyppi Pakollinen Asiakas Asiaan liittyvän asiakkaan tiedot. Sama asia voidaan lähettää usealle asiakkaalle, jolloin näitä elementtejä voi olla useita. lementti AsiakasTunnus Asiakkaan HTU Sahkoposti Matkapuhelin TunnusTyyppi Nimi Katuosoite Postinumero Paikkakunta Maa mail-osoite Puhelinnumero SSN Asiakkaan nimi Jakeluosoite Postinumero Toimipaikka Maakoodi ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä, jonka tulee olla pysyvä, yksilöivä tunniste. Viittaus lementti ViittausTunniste Liittyvän asian tunniste ViittausTunnisteTyyppi VahvistusVaatimus VaadiLukukuittaus Liittyvän asian tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste Todisteellinen tiedoksianto, joka vaatii kuittauksen lukemisesta: 1=kyllä, 0=ei Parametrin avulla voidaan pakottaa viestinvälityspalvelu

27 lähettämään kuittausviesti kohteesta, vaikka lukukuittausten lähettäminen olisi muuten disabloitu. AsiaNumero Viestinvälityspalvelussa näytettävä asiakirjan tunniste (esim. päätöksen numero) Nimeke Asian otsikkotieto, jonka viranomaisjärjestelmä tuottaa asiakkaan omalla kielellä. LahetysPvm Lähetyspäivämäärä datetime K LahettajaNimi Lähettäneen viranomaisen tarkempi nimi KuvausTeksti Vapaamuotoinen kuvaus K Maksullisuus Tieto maksullisuudesta MaksamisKuvausTeksti Maksun vapaamuotoinen kuvaustieto. sim. hinta ja maksuohjeet. Tila Asian viranomaiskäsittelyn tilatieto Asian TilaKoodi viranomaisjärjestelmässä olevaa käsittelyn tilaa kuvaava määrämuotoinen tilatieto Tila Asian viranomaisjärjestelmässä olevaa käsittelyn tilaa kuvaava vapaamuotoinen tieto TilaKuvaus tekijä Tilaan liittyvä lisätieto. simerkiksi päätöksen TilaPvm Tilan päivämäärätieto. li milloin päätös on tehty datetime K Tiedostot (0..n) Asiaan liittyvät asiakirjat

28 TiedostonKuvaus Asiakirjan selite String TiedostoURL Tiedoston URL, josta asiakirja on ladattavissa, jos käytetään viranomaisen omaa välivarastoa TiedostoSisalto Tiedosto BAS64 - enkoodattuna TiedostoKoko Tiedoston koko kilotavuina TiedostoMuoto Tiedoston formaatti (mime type) TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen Alkusivu Paperitulostuksessa käytettävän etusivun numero Sivumaara Paperitulostuksessa käytettävä sivumäärä Sähköpostiliityntä: Puolipisteellä eroteltuna joko 1 tai useampi Viranomaisenmail sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. Heräteviestin sisältö, SmsLisatieto joka välitetään matkapuhelimeen Heräteviestin otsikko, maillisatietootsikko joka välitetään sähköpostiin Heräteviestin sisältö, maillisatietosisalto joka välitetään sähköpostiin Asiakkaalle tallennettava SMSnotifikaatin lähetysnumero, joka TavoitettavuusTietoSMS tallennetaan asiakaan tietoihin, mikäli kutsun seurauksena asiakkaalle luodaan pikatili. Mikäli asiakkaalla on tili String

29 käytössä, ei kenttää huomioida. TavoitettavuusTietomail Kenttä ei ole vielä käytössä. Asiakkaalle tallennettava sähköpostinotifikaatin lähetysnumero, joka tallennetaan asiakaan tietoihin, mikäli kutsun seurauksena asiakkaalle luodaan pikatili. Mikäli asiakkaalla on tili käytössä, ei kenttää huomioida.

30 Vastauselementit Vastaus_WS2 lementti TilaKoodi Selite Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=kutsu onnistunut Virhekoodit: TilaKoodi 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. Viestinvälityspalvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikaatiotietoa. VIA palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Viestinvälityspalvelu palauttaa. 405=Toiminto ei ole sallittu kyseiselle viranomaistunnukselle ja palvelutunnukselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Viestinvälityspalvelu palauttaa. 453= Kohdepalvelu ei vastaa. VIA palauttaa, jos ei saa asiointitilipalveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). Virhekoodin selitekenttä. TilaKoodiKuvaus simerkiksi kutsussa oleva KohdeMaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa KohdeMaara Käsiteltyjen asioiden lukumäärä. Kohteet ->Kohde (0..n) Yhden asian tiedot kokoava elementti ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä. Sama tunniste, kuin kutsuviestissä.

31 Asiakas Asiaan liittyvän asiakkaan tiedot. Asia liitetään kyseisen asiakkaan viestinvälityspavelutiliin. o AsiakasTunnus Asiakkaan tunniste l. hetu o TunnusTyyppi o AsiointitiliTunniste o KohteenTila o KohteenTilaKuvaus SSN Asian yksilöivä tunniste, jonka VVP on asialle antanut. Asiointitilitunniste yksilöi viestin aina asiakaskohtaisesti. li toimitettaessa viestinvälityspalvelulle sama asia, joka liittyy moneen asiakkaaseen, on asialla kaikille asiakkaille yhteinen viranomaistunniste ja asiakaskohtainen asiointitilitunniste. Kutsun tallennuksen käsittelytila. KäsittelyTila palautetaan asiakaskohtaisesti. Onnistuneet statukset: (tässä tilanteessa asia on tallennettu viestinvälityspalveluun) 200=kutsu onnistunut ja tallennettu asiointitilille. Jos ei toimitettavia liitetiedostoja, voidaan käsitellä loppuun kutsun yhteydessä. 202=kutsu onnistunut ja laitettu käsittelyyn asiointitilipalvelussa, mutta se ei vielä näy asiakkaan asiointitilillä. Lopullinen vastaus on haettavissa erikseen erillisellä kutsulla. päonnistuneet statukset: (tässä tilanteessa asiaa ei ole tallennettu asiointitilipalveluun) 520=annettulla tunnisteella löytyy jo asia, joka on tallennettu asiointitilipalveluun 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 (Näitä tiloja ei palauteta tässä, koska virustarkitus tapahtuu työjonon kautta.) 524=asiakas ei ota vastaan asioita viestinvälityspalveluntilille. 525=asian tietosisällössä virheitä 528=ei sallittu liitetiedoston tyyppi 529=liian iso liitetiedoston koko 550=muu virhe Tarkempi kuvaus virheestä. simerkiksi liiitetiedostoon liittyvän virheen tapauksessa tiedoston nimi.

32 SOAP Fault Palautetaan SOAP Fault jos tapahtuu tekninen virhe ja viestin välitön uudelleen lähetys on turhaa. simerkit simerkki 1: Lähetetään viesti liitteellä simerkkipyyntö <s:nvelope> <s:header> <Action s:mustunderstand="1"> </s:header> <s:body> <LisaaKohteita> <Viranomainen> <ViranomaisTunnus>VANTAA</ViranomaisTunnus> <PalveluTunnus>PÄIVÄHOITOHAKMUS</PalveluTunnus> <KayttajaTunnus>kkayttaja</KayttajaTunnus> <SanomaTunniste>1234</SanomaTunniste> <SanomaVersio>1.0</SanomaVersio> <SanomaVarmenneNimi>innofactor.com</SanomaVarmenneNimi> </Viranomainen> <Kysely> <KohdeMaara>1</KohdeMaara> <Kohteet> <Kohde> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"/> <ViranomaisTunniste> </ViranomaisTunniste> <Viittaus ViittausTunniste=" " ViittausTunnisteTyyppi="ViranomaisTunniste"/> <VahvistusVaatimus>0</VahvistusVaatimus> <AsiaNumero> </AsiaNumero> <Nimeke>Työttömyyskorvauspäätös</Nimeke> <LahetysPvm> T12:54:00</LahetysPvm> <LahettajaNimi>Kirjavalan työvoimatoimisto</lahettajanimi> <KuvausTeksti>Päätös työttömäksi työnhakijaksi ilmoittautuneelle myönnettävästä työttömyyspäivärahasta</kuvausteksti> <Maksullisuus>0</Maksullisuus> <Tila> <TilaKoodi>123</TilaKoodi> <Tila>Käsitelty</Tila> <TilaKuvaus>Käsittelijä: Kalle Käyttäjä</TilaKuvaus> <TilaPvm> T14:45:00</TilaPvm> </Tila> <Tiedostot> <Tiedosto> <TiedostonKuvaus>Päätös työttömyyspäivärahasta</tiedostonkuvaus> <TiedostoSisalto>AFD8AW4NRCA8PPA3R...A384WNRC9N2</TiedostoSisalto> <TiedostoKoko>34</TiedostoKoko> <TiedostoMuoto>application/pdf</TiedostoMuoto> <TiedostoNimi> pdf</TiedostoNimi> </Tiedosto> <Tiedosto> <TiedostonKuvaus>Muutoksenhakulomake annettuun päätökseen</tiedostonkuvaus> <TiedostoSisalto>AFD8AW4NRCA8PPA3R...A384WNRC9N2</TiedostoSisalto> <TiedostoKoko>125</TiedostoKoko> <TiedostoMuoto>application/pdf</TiedostoMuoto> <TiedostoNimi>muutoksenhakulomake.pdf</TiedostoNimi> </Tiedosto> </Tiedostot> </Kohde> </Kohteet>

33 </Kysely> </LisaaKohteita> </s:body> </s:nvelope> simerkkivastaus <s:nvelope> <s:body> <LisaaKohteitaResponse> <LisaaKohteitaResult> <TilaKoodi> <TilaKoodi>200</TilaKoodi> <TilaKoodiKuvaus>kutsu onnistunut</tilakoodikuvaus> <SanomaTunniste>1236</SanomaTunniste> </TilaKoodi> <KohdeMaara>1</KohdeMaara> <Kohteet> <Kohde> <ViranomaisTunniste> </ViranomaisTunniste> <Asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <AsiointitiliTunniste> </AsiointitiliTunniste> <KohteenTila>202</KohteenTila> <KohteenTilaKuvaus/> </Asiakas> </Kohde> </Kohteet> </LisaaKohteitaResult> </LisaaKohteitaResponse> </s:body> </s:nvelope>