Suomi.fi-palvelutietovaranto Kaikki oleellinen julkishallinnon palveluista yhdessä paikassa PTV-rajapintojen ajankohtaiset asiat
Tavoitteet ja sisältö Tavoitteet Tiedottaa PTV:n IN-rajapinnan seuraavaan versioon suunnitelluista muutoksista Vastata käyttäjien kysymyksiin
PTV API-versiossa 7 tulevat muutokset
Ylätason muutokset Organisaatio Organisaatio metodien muutokset (POST/PUT/GET): Laskutustietojen kuvaaminen ja näyttäminen (julk 1.8) Osoitetietojen määrittely muuttunut (esimerkki katso viimeinen sivu) Katuosoite, postilokero-osoite, ulkomainen osoite omissa lohkoissa Pääorganisaatiotieto näkyviin GET-metodilla sourceid kenttä lisätty GET Organization/{id} metodiin tieto tulee näkyviin vain kirjautuneelle käyttäjälle, muutoin Null.
Ylätason muutokset Palvelu Palvelun metodien muutokset (POST/PUT/GET): Pohjakuvauksella ehdotettujen kanavien liittäminen (liitoksen hyväksyminen) sourceid kenttä lisätty GET Service/{id} metodiin tieto tulee näkyviin vain kirjautuneelle käyttäjälle, muutoin Null. Liitoksen tekeminen Palvelun kautta (ei mahd. lisätietojen antamista) Luodut liitokset näkyvät GET Service/{id} metodilla Näkyviin tulevat myös yhteispalvelupisteiden uudet kentät
Ylätason muutokset Kanavat Kanavien metodien muutokset (POST/PUT/GET): sourceid kenttä lisätty GET ServiceChannel/{id} metodiin tieto tulee näkyviin vain kirjautuneelle käyttäjälle, muutoin Null. Sijaintietojen (osoitetietojen) määrittely muuttunut (lisää esimerkki) Tulostettava lomake: Katuosoite, Postilokero-osoite, Toimitustieto sanallisesti omissa lohkoissa Palvelupiste: Katuosoite, Postilokero-osoite, liikkuva kanava, Ulkomainen osoite omissa lohkoissa >> Katso käsittelysäännöt dialta lisätietoa o Monta sijaintia (ent. Liikkuva kanava) julkaisu 1.8 Liitoksen tekeminen Kanavan kautta (ei mahd. lisätietojen antamista) Luodut liitokset näkyvät GET ServiceChannel/{id} metodilla Näkyviin tulevat myös yhteispalvelupisteiden uudet kentät
Ylätason muutokset Liitokset Liitokset metodien muutokset (POST/PUT/GET): Liitokset siirretty omaksi osiokseen Swaggerissa api/v7/connection Palvelun ja Palvelupisteen liitokselle voidaan antaa aukioloaika ja yhteystieto lisätietoja Lisätty mahdollisuus päivittää liitostietoja kanavan kautta (id) PUT /api/v7/connection/servicechannelid/{servicechannelid} Liitoksen GET metodeissa yhteispalvelupisteiden kentät uutena tietona
Vanhat metodit, tärkeimmät muutokset Organisaatio Tiivistelmä kenttä lisätty Laskutusosoitetiedot lisätty (julk. 1.8) Osoite rakenne muuttunut Palvelu Päävastuu ja muut vastuuorganisaatiot rakennetta muutettu Aukioloajat ja yhteystiedot näkyviin palveluun liitetyn asiointikanavassa tiedoissa Palveluluokkien Finto-kuvaus näkyville Kanava (Tulostettava lomake & Palvelupiste) Osoite rakenne muuttunut
Käsittelysääntöjä Lisätty tarkastus: PTV-pääkäyttäjä voi lisätä alaorganisaation vain sen organisaation alle, johon hänelle on oikeudet Lisätty tarkastus: organisaation tai alaorganisaation arkistointi ei sallittu, jos niille on kuvattu palveluja tai kanavia. Alla olevat metodit palauttavat jatkossa vain kysytyn tiedon ID:n ja nimen (lista) GET Service/serviceChannel/{serviceChannelId} GET ServiceChannel/type/{type} GET ServiceChannel/organization/{organizationId} GET ServiceChannel/organization/{organizationId}/type/{type} Palvelupisteen sijaintitiedot Yksi sijainti (ent. katuosoite) Monta sijaintia (ent. liikkuva palvelupiste) julk. 1.8 Sijainti ulkomailla (ent. ulkomainen osoite)
Uudet metodit CodeList viisi uutta metodia. Voidaan palauttaa käytettyjä koodistoja (Kunta-, Maa-, postinumero-, kieli-, Maakunta-, Sairaanhoitopiiri- sekä yritysseutualuekoodit) Common kaksi uutta metodia. Ensimmäinen palauttaa tiedot organisaation julkaistuista palveluista ja kanavista (id ja nimi). Toinen palauttaa samat tiedot mutta kuntatieto rajauksella ServiceCollection - Palvelukokonaisuus Lisäksi Swagger sisältää uusia metodeja, joiden käyttö on rajoitettu metodeissa on tästä maininta.
Tuetut versiot Julkaisun numero Julkaisun päivä Tuetut rajapintaversiot 1.45 18.4.2017 V5, V4, V3, V2 Lisätieto 1.5 5.6.2017 V6, V5, V4, V3 1.6 14.8.2017 V6, V5, V4 1.7 2.10.2017 * V7, V6, V5, V4 Rajapintaversiota V4 ei tueta - voi käyttää 1.8 27.11.2017 V7, V6, V5 Ei uutta raja-pintaversiota 1.9 29.1.2018 (alustava) 2.0 26.3.2018 (alustava) V8, V7, V6, V5 Rajapintaversiota V5 ei tueta - voi käyttää Ei uutta raja-pintaversiota (alustava suunnitelma)
Esimerkki osoitetietokentistä "addresses": [ { "type": "string", "subtype": "string", "postofficeboxaddress": { "postofficebox": [ {"value": "string", "language : string } ], "postalcode": "string", "municipality": "string", "additionalinformation": [ { "value": "string", "language": "string" } ] }, "streetaddress": { "street": [ { "value": "string", "language": "string" } ], "streetnumber": "string", "postalcode": "string", "municipality": "string", "additionalinformation": [ { "value": "string", "language": "string" } ], "latitude": "string", "longitude": "string" }, "foreignaddress": [ { "value": "string", "language": "string" } ], "country": "string" } ],
Liitokset Palvelu Liitos Asiointikanava Perheneuvola palvelut Perhe- ja ryhmäterapia Ma, ti, to 10:00-14:00 Sisäänkäynti 3 kerros Hammashoidon päivystys Lastensuojelun palvelut Työterveys palvelut Hammashoitola Ma-pe 8:00 16:00 Lastensuojelu Ma-pe 9:00 15:30 Vain ajanvarauksella Työterveyden hoitaja Ma-pe 8:00 16:00 Ilmoittautuminen 1 kerros Terveyskeskus Normaalit aukioloajat: Ma-pe 8:00 18:00 Vahtimestari 044 1122 3344 www.terveyskeskus.fi
PTV OUT rajapinta
Palvelujen hakeminen GET service/{id} metodi tuo pohjakuvaukselta vain ne tiedot näkyviin, jotka ovat pakollisia ja joita käyttäjä ei ole itse syöttänyt: Palvelutyyppi Kohderyhmä Palveluluokka Asiasanat Pohjakuvauksen tiedot haetaan metodilla GET GeneralDescription/{id} Yhden organisaation palvelujen ja asiointikanavien hakeminen Hae organisaation palvelut (id, y- tunnus, oid) Palvelun tiedot, pohjakuvaus id, listaus kanavista: id, nimi Listaus palveluista: Id, nimi Hae jokaisen palvelun tiedot (id) Hae pohjakuvauksen tiedot (id) Hae jokaisen kanavan tiedot (id)
Ennakko kysymyksiä Onko tulossa muutoksia rajapintaan jotka vaikuttaa nykyisiin toteutuksiin? Vanhat V5, V6 versiot säilyvät ennallaan eli ei tule niihin muutoksia. V7 muuttaa vanhojakin metodeja. Rautalangasta: Mitä kunnan tulee tehdä saatuaan Palvelutietovarannon valmiiksi? Ylläpitää tietoja päivittää säännöllisin välein ja tarkastaa ettei tiedoissa ole virheitä Miten rajapintojen vanhoja versiota tuetaan? Eli millainen elinkaari niissä on. Uusin + kaksi edellistä. Sovimme jo, että jätetään v4 näkyviin mutta ei tueta sitä. Olisin kiinnostunut kuulemaan, onko muuallakin kuin Varsinais-Suomessa ollut vaikeuksia saada rajapintaratkaisun tekninen toteuttaja ymmärtämään PTV:n ominaisuuksia ja toimituspolitiikkaa? Suomi.fi laaduntarkkailu on kiinnittänyt tähän huomiota ja mietimme ratkaisua, jolla sovellustoimittajia voidaan auttaa ymmärtämään PTV:n tietomalli ja ohjeistamaan omia käyttäjiään oikein Käytännön kokemuksia kuulisin onko toiminut ja onko hyötyä lähinnä OUT-rajapintaa koskien OUT-rajapinnan käyttäjistä VRK:lla ei ole saman lailla tietoa kuin IN-rajapinnan käyttäjistä. Suurin hyödyntäjä on Suomi.fiverkkopalvelu. Muita ovat tassa.fi, Ruokolahden kunta, Tampereen palvelut (pilotti) Lokilta selviää että esim. syyskuun aikana on GET kutsuja ollut noin 9 miljoonaa 7-version muutokset verrattuna 5-versioon 7-version aikataulu Uudet metodit, Liitoksien siirtäminen omaan osioon, liitoksen lisätiedot, osoiterakenteen muuttuminen Julkaisu lokakuu 2017, versiotiedote lähetetään viikkoa ennen versiopäivitystä.
Liitemateriaalia
IN API rajapinnassa 1/2 Järjestelmäpääkäyttäjä PTV pääkäyttäjä PTV ylläpitäjä API käyttäjä Lisätietoa Pääorganisaation luonti Ei sallittu Ei sallittu Ei sallittu Ei sallittu Vain Palvelunhallinnan kautta (tulossa) Pääorganisaation arkistointi* Sallittu Ei sallittu Ei sallittu Ei sallittu * Arkistointi poistaa organisaation suomi.fi verkkopalvelusta Pääorganisaation tietojen muokkaus (lisäys/muutos/poisto) Organisaatiorakenteen (puun) muutokset Sallittu Sallittu Ei sallittu Sallittu Ei sallittu Ei sallittu Ei sallittu Ei sallittu Alaorganisaation luonti Sallittu Sallittu Ei sallittu Sallittu Alaorganisaation arkistointi Sallittu Sallittu Ei sallittu Sallittu Alaorganisaation tietojen muokkaus (lisäys/muutos/poisto) Palvelujen tai asiointikanavien luonti Palvelujen tai asiointikanavien arkistointi Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu
IN API rajapinnassa 2/2 Palvelu tai asiointikanavien tietojen muokkaus (lisäys/muutos/poisto) Järjestemä pääkäyttäjä PTV pääkäyttäjä PTV ylläpitäjä API käyttäjä Lisätietoa Sallittu Sallittu Ei sallittu Sallittu Liitosten luonti Sallittu Sallittu Ei sallittu Sallittu Liitosten poisto Sallittu Sallittu Ei sallittu Sallittu Liitosten lisätietojen muokkaus (lisäys/muutos/poisto) Sallittu Sallittu Ei sallittu Sallittu Pohjakuvausten luonti Sallittu Ei sallittu Ei sallittu Ei sallittu Pohjakuvausten poisto Sallittu * Ei sallittu Ei sallittu Ei sallittu Pohjakuvausten tietojen muutokset Sallittu * Ei Sallittu Ei sallittu Ei sallittu Pohjakuvausten käyttö palveluissa Sallittu Sallittu Ei sallittu Sallittu
Lisätietoja esuomi.fi ja PTV-tuki@vrk.fi PTV-in rajapinta materiaalia löytyy esuomi.fistä https://esuomi.fi/palveluntarjoajille/palvelutietovaranto/ptv-arkkitehtuuri/ PTV:n versiotiedotteet: https://esuomi.fi/palveluntarjoajille/palvelutietovaranto/ptvarkkitehtuuri/ptv-versiotiedotteet/ IN-rajapinnan testausohje löytyy esuomi.fin ladattavista aineistoista täältä: https://esuomi.fi/mdocs-posts/in-rajapinnan-testausohje/ IN-rajapinta Apin kuvaukset löytyvät osoitteesta https://esuomi.fi/aineisto/suomi-fipalvelutietovaranto/?mdocs-cat=mdocs-cat-19&att=suomi.fi-palvelutietovaranto PTV-rajapintojen skeemat ovat saatavilla swaggerissa osoitteessa https://api.palvelutietovaranto.suomi.fi/swagger/ui/index.html HUOM! Swaggerissa on valittava haluttu versio erikseen. Pohjakuvausten tiedot ja tuotantoympäristön ID:t löytyvät: https://esuomi.fi/mdocs-posts/pohjakuvaukset-ja-idt-tuotantoymparistossa/ 20
Kiitos! Yhteydenotot: ptv-tuki@vrk.fi Lisätietoja: http://esuomi.fi/palveluntarjoajille/palvelutietovaranto/ PTV-video: https://www.youtube.com/watch?v=2vhqaxbqnws 21