Lisätietoa OUT-integraation toteuttajalle

1. Hae organisaatiot

Listan kaikista Suomi.fi-palvelutietovarannossa olevista organisaatioista, joilla on julkaistuja palveluita ja asiointikanavia voit hakea metodilla GET Organization. Metodi palauttaa organisaatioiden nimet ja id:t.

2. Hae organisaatioiden palvelut

Kun tiedät organisaation id:n, voit hakea listan organisaation palveluista metodilla GET Organization/{id}. Metodi palauttaa organisaation palveluiden nimet ja id:t.

3. Hae palveluiden tiedot

Seuraavaksi voit hakea organisaation palveluiden tiedot organisaation tiedoissa palautetulla palvelun id:llä.

Kun palveluilla ei ole pohjakuvausta

voit hakea

• yksittäisen palvelun kaikki tiedot GET Service/{id} -metodilla
• tai useampien palveluiden kaikki tiedot GET Service/list -metodilla.

Kun palveluilla on pohjakuvaus

Osalla palveluista on taustallaan pohjakuvaus. Niitä on tehty kuntien, hyvinvointialueiden, yritysten seutupalveluiden ja seurakuntien käyttöön.

Pohjakuvausten tietojen hakeminen ei ole pakollista, mutta ne sisältävät palveluista hyödyllistä taustatietoa.

Voit hakea

• yksittäisen palvelun tiedot pohjakuvauksineen metodilla serviceWithGD/{id} tai
• useampien palveluiden kaikki tiedot pohjakuvauksineen metodilla GET Service/serviceWithGD/list.

4. Hae palveluihin liitettyjen asiointikanavien tiedot

Palveluun liitettyjen asiointikanavien nimi- ja id-tiedot palautetaan palvelun tiedoissa.

Voit hakea

• yksittäisen asiointikanavan kaikki tiedot metodilla GET ServiceChannel {id} tai
• useampien asiointikanavien tiedot metodilla GET ServiceChannel/list.

Huomaa! Verkkoasiointikanavan ja verkkosivu-asiointikanavan nimi tulee kuvata siten, että sitä voidaan käyttää linkkitekstinä, joka ohjaa asiointikanavan URL-osoitteeseen. Kun hyödynnät asiointikanavan URL-osoitetta, käytä asiointikanavan nimeä linkin nimenä. Älä näytä pelkkää URL-osoitetta, sillä se ei ole kuvaava eikä saavutettava.

Käytettävissä on useita metodeja, joilla voi rajata haettavaa tietoa. Seuraavassa esimerkkejä tärkeimmistä:

Palvelutietojen rajaaminen

Palveluiden listaa voi rajata alutiedon perusteella. Mahdolliset rajaukset ovat kunta (Municipality), maakunta (Province), ja hyvinvointialue (WellbeingServiceCounties).

• /api/v11/Service/list/area/{area}/code/{code}palauttaa kaikki palvelut, joilla on rajauksen mukainen aluetieto sekä niihin liittyvien asiointikanavien nimet ja id:t.

Palveluita on myös mahdollista rajata seuraavien arvojen perustella:

• palveluluokka (GET Service/serviceClass)
• kohderyhmä (GET Service/targetGroup)
• palvelun tyyppi (GET Service/type)
• palvelun toimiala (GET Service/industrialClass)

Löydät tarvittavat hakuparametrit seuraavasta tiedostosta.

PTV:ssä käytettävät koodistot, Digi- ja väestötietovirasto (XLSX, 14,02 kt)Avautuu uuteen ikkunaan.
Useamman parametrin yhdistelmähakuja ei valitettavasti ole käytettävissä.

Asiointikanavatietojen rajaaminen

Myös asiointikanavien listaa voi rajata aluetiedon perusteella. Mahdolliset rajaukset ovat kunta (Municipality), maakunta (Province) ja hyvinvointialue (WellbeingServiceCounties).

• /api/v11/ServiceChannel/list/area/{area}/code/{code} palauttaa kaikki asiointikanavat, joilla on rajauksen mukainen aluetieto sekä niihin liittyvien palveluiden nimet ja id:t.

Asiointikanavia on mahdollista rajata myös asiointikanavatyypin mukaan.

• Metodi /api/v11/ServiceChannel/type/{type} mahdollistaa haun rajaamisen asiointikanavatyypin mukaan. Sallitut arvot ovat EChannel (verkkoasiointi), WebPage (verkkosivu), PrintableForm (tulostettava lomake), Phone (puhelinasiointi) ja ServiceLocation (palvelupaikka).

Organisaatiotietojen rajaaminen

Palautettavien organisaatioiden listaa voi rajata aluetiedon perusteella. Mahdolliset rajaukset ovat kunta (Municipality), maakunta (Province) ja hyvinvointialue (WellbeingServiceCounties).

• GET Organisation/area/{area}/code/{code}) palauttaa kaikki julkaistut organisaatiot, joilla on rajauksen mukainen aluetieto.
• GET Organization/list palauttaa kaikki organisaatiot, joilla on rajauksen mukainen aluetieto ja sekä kaikkien näiden organisaatioiden palveluiden nimet ja id:t. Metodi palauttaa myös palvelut, joissa haettu organisaatio on palvelun muu vastuuorganisaatio (roleType: OtherResponsible).

Monella metodilla on mahdollista rajata hakua muokkauspäivämäärän perusteella ja hakea sisältöjä, jolle on tehty muutoksia

• annetun päivän jälkeen (date)
• ennen annettua päivää (dateBefore) tai
• tiettyjen päivämäärien välillä.

Tämä on käytännöllistä silloin, kun halutaan noutaa vain ne tiedot, jotka ovat muuttuneet edellisen tietojen haun jälkeen.

Kellonaika on PTV-datassa eri tarkkuudella kuin parametreissä: PTV-datassa muokkausajankohta ilmoitetaan millisekuntien tarkkuudella, mutta parametreilla on mahdollisuus rajata vain sekuntien tarkkuudella.

Organisaatiotiedot

1. Hae uudet ja päivitetyt organisaatiot metodilla

GET api/v11/Organization?date=yyyy-mm-ddThh:mm:ss

• Saat organisaation id-nimi-listauksen.
• HUOM! Metodi palauttaa kentän sivujen lukumäärän (pagecount). Jos sen arvo > 1, toista haku jokaiselle sivulle: api/v11/Organization?date=yyyy-mm-ddThh:mm:ss&page=x.
• Ota id:t talteen.
• Hae organisaation täydelliset tiedot 100 id:n ryhmissä metodilla /api/v11/Organization/list?guids=id1,id2,id3,id4.
• Lisää uudet organisaatiot omaan tietokantaasi ja päivitä muuttuneiden organisaatioiden tiedot.

2. Hae poistetut organisaatiot metodilla

GET /api/v11/Organization?status=archived&date=yyyy-mm-ddThh:mm:ss

• Saat organisaation nimi-id-listauksen.
• Poista organisaatiot omasta tietokannastasi.

3. Hae luonnostilaan palautetut organisaatiot metodilla

GET /api/v11/Organization?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• Saat organisaation nimi-id-listauksen.
• Poista organisaatiot omasta tietokannastasi.

Palvelutiedot

1. Hae uudet ja päivitetyt palvelut metodilla

GET api/v11/Service?date=yyyy-mm-ddThh:mm:ss

• Saat palvelun id-nimi-listauksen.
• HUOM! Metodi palauttaa kentän sivujen lukumäärän (pagecount). Jos sen arvo > 1, toista haku jokaiselle sivulle.
• Ota id:t talteen.
• Hae palvelun täydelliset tiedot 100 id:n ryhmissä metodilla /api/v11/Service/list?guids=id1,id2,id3,id4.
• Lisää uudet palvelut omaan tietokantaasi ja päivitä muuttuneiden palvelujen tiedot.

Päivämäärärajauksella haettaessa metodi palauttaa myös ne palvelut, joiden asiointikanaviin on tullut muutoksia: asiointikanavia on lisätty tai poistettu tai liitostietoja on päivitetty.

2. Hae poistetut palvelut metodilla

GET /api/v11/Services?status=archived&date=yyyy-mm-ddThh:mm:ss

• Saat palvelun nimi-id-listauksen.
• Poista palvelut omasta tietokannastasi.

3. Hae luonnostilaan palautetut palvelut metodilla

GET /api/v11/Service?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• Saat palvelun nimi-id-listauksen.
• Poista palvelut omasta tietokannastasi.

Asiointikanavatiedot

1. Hae uudet ja päivitetyt asiointikanavat metodilla

GET api/v11/ServiceChannel?date=yyyy-mm-ddThh:mm:ss

• Saat asiointikanavan id-nimi-listauksen.
• HUOM! Metodi palauttaa kentänsivujen lukumäärän (pagecount). Jos sen arvo > 1, toista haku jokaiselle sivulle.
• Ota id:t talteen.
• Hae asiointikanavan täydelliset tiedot 100 id:n ryhmissä metodilla /api/v11/ServiceChannel/list?guids=id1,id2,id3,id4.
• Lisää uudet asiointikanavat omaan tietokantaasi ja päivitä muuttuneiden asiointikanavien tiedot.

2. Hae poistetut asiointikanavat metodilla

GET /api/v11/ServicesChannel?status=archived&date=yyyy-mm-ddThh:mm:ss

• Saat asiointikanavan nimi-id-listauksen.
• Poista asiointikanavat omasta tietokannastasi.

3. Hae luonnostilaan palautetut asiointikanavat metodilla

GET /api/v11/ServiceChannel?status=withdrawn&date=yyyy-mm-ddThh:mm:ss

• Saat asiointikanavan nimi-id-listauksen.
• Poista asiointikanavat omasta tietokannastasi.

Palveluaikakenttien nimet ja käyttötarkoitus

Normaalit aukioloajat

'Normaali aukioloajat: viikonpäivät' -osuudessa kuvataan asiointikanavan yleisin aukioloaika. Aukioloajan voi määritellä valitulle päivälle* (00:00 - 24:00) eli aukioloaika ei voi ylittyä seuraavan vuorokauden puolelle. Yhden päivän aukioloaika voidaan jaotella erillisiin aukioloaikajaksoihin. Jaksoja voi olla yhteensä neljä (esimerkki 1).

*) Valittavissa kaikki viikonpäivät (maanantai - sunnuntai)

'Normaalit aukioloajat: viikonpäivät' -osuudessa voidaan valita aukioloajaksi myös 'Aina avoinna (24/7)' tai 'Avoinna ajanvarauksella'.

Aukioloaika voi olla joko voimassa toistaiseksi tai voimassa ajanjaksolla. Voimassa ajanjaksolla -vaihtoehdossa käyttäjä antaa aikavälin, jolloin aukioloajat ovat voimassa. Molemmissa vaihtoehdoissa on käytettävissä yllä mainitut vaihtoehdot (päivävalinnat, 24/7, ajanvarauksella).

1) toistaiseksi voimassa oleva - tiistaina ja keskiviikkona

Aukioloajat:
• Tiistai klo 8.00-12.00, 13.00-14:00, 15:00-16:00 ja 17:00-18:00
• Keskiviikko klo 9.00-16:30
• Torstai klo 00:00 - 24:00 ← Huom! 24:00 annetaan rajapintaan arvolla 00:00
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 1: toistaiseksi voimassa oleva",
"language": "fi"
}
],
"openingHour": [
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "08:00:00",
"to": "12:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "13:00:00",
"to": "14:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "15:00:00",
"to": "16:00:00"
},
{
"dayFrom": "Tuesday",
"dayTo": null,
"from": "17:00:00",
"to": "18:00:00"
},
{
"dayFrom": "Wednesday",
"dayTo": null,
"from": "09:00:00",
"to": "16:30:00"
},
{
"dayFrom": "Thursday",
"dayTo": null,
"from": "00:00:00",
"to": "00:00:00"
}
]
}

2) voimassa ajanjaksolla - keskiviikkona ja torstaina

Ajanjakso:
• 08.12.2023-10.12.2023
Aukioloajat:
• keskiviikko klo 09:30-16:30
• torstai klo 09:30-16:30
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2023-12-08T00:00:00",
"validTo": "2023-12-10T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 2:Voimassa ajanjaksolla",
"language": "fi"
}
],
"openingHour": [
{
"dayFrom": "Wednesday",
"dayTo": null,
"from": "09:30:00",
"to": "16:30:00"
},
{
"dayFrom": "Thursday",
"dayTo": null,
"from": "09:30:00",
"to": "16:30:00"
}
]
}

3) toistaiseksi voimassa oleva - aina avoinna (24/7)

Aukioloajat:
• Aina avoinna (24/7)
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": true,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 3: Toistaiseksi voimassa oleva, aina avoinna",
"language": "fi"
}
],
"openingHour": []
}

4) toistaiseksi voimassa oleva - avoinna ajanvarauksella

Aukioloajat:
• avoinna vain ajanvarauksella
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": true,
"additionalInformation": [
{
"value": "Test 4SV",
"language": "sv"
},
{
"value": "Test 4EN",
"language": "en"
},
{
"value": "Testi 4: Toistaiseksi voimassa oleva, avoinna ajanvarauksella",
"language": "fi"
}
],
"openingHour": []
},

5) voimassa ajanjaksolla - aina avoinna (24/7)

Ajanjakso:
• 03.01.2024-04.01.2024
Aukioloajat:
• Aina avoinna (24/7).
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2024-01-03T00:00:00",
"validTo": "2024-01-04T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": true,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 5: voimassa ajanjaksolla, aina avoinna",
"language": "fi"
}
],
"openingHour": []
}

6) voimassa ajanjaksolla - avoinna ajanvarauksella

Ajanjakso:
• 22.12.2023 - 24.12.2023
Aukioloajat:
• Avoinna vain ajanvarauksella
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": "2023-12-22T00:00:00",
"validTo": "2023-12-24T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": true,
"additionalInformation": [
{
"value": "Testi 6: voimassa ajanjaksolla, avoinna ajanvarauksella",
"language": "fi"
}
],
"openingHour": []
}

7) toistaiseksi voimassa - vain otsikko

Normaalin palveluaikatiedon voi lähettää hyödyntäen vain otsikko-kenttää. Päivämäärä tai aukioloaikatiedot eivät ole pakollisia.
{
"serviceHourType": "DaysOfTheWeek",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 2A: Vain otsikko",
"language": "fi"
}
],
"openingHour": []
}
],

Normaalit aukioloajat: vuorokauden yli (päivystys)

'Normaali aukioloajat: vuorokauden yli' -osuudessa kuvataan päivystystyyppisen asiointikanavan aukioloajat. Tässä osiossa aukioloaika yleisimmin alkaa valittuna päivänä ja jatkuu seuraavan vuorokauden puolelle. Aukioloaikaa ei voi jakaa erillisiin jaksoihin.

*) Valittavissa kaikki viikonpäivät (maanantai - sunnuntai)

Aukioloaika voi olla joko voimassa toistaiseksi tai voimassa ajanjaksolla. Voimassa ajanjaksolla -vaihtoehdossa käyttäjä antaa aikavälin, jolloin aukioloajat ovat voimassa.

1) toistaiseksi voimassa - tiistaista keskiviikkoon

Aukioloajat:
• tiistaista 18:00 keskiviikkoon 02:00
{
"serviceHourType": "OverMidnight",
"validFrom": null,
"validTo": null,
"isClosed": false,
"validForNow": true,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 7: toistaiseksi voimassa oleva (ti-ke)",
"language": "fi"
}
],
"openingHour": [
{
"dayFrom": "Tuesday",
"dayTo": "Wednesday",
"from": "18:00:00",
"to": "02:00:00"
}
]
}

2) voimassa ajanjaksolla - keskiviikosta perjantaihin

Ajanjakso:
• 23.12.2023 - 25.12.2023
Aukioloajat:
• keskiviikosta klo 20:00 perjantaihin klo 10:00
{
"serviceHourType": "OverMidnight",
"validFrom": "2023-12-23T00:00:00",
"validTo": "2023-12-25T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 8: voimassa ajanjaksolla (ke-pe)",
"language": "fi"
}
],
"openingHour": [
{
"dayFrom": "Wednesday",
"dayTo": "Friday",
"from": "20:00:00",
"to": "10:00:00"
}
]
},

Poikkeavat palveluajat

'Poikkeavat palveluajat' -osuudessa kuvataan asiointikanavan normaaleista aukioloajoista poikkeavat aukioloajat. Yleensä nämä ovat tilapäisiä ja niille määritellään voimassaoloajan ajanjakso.

Aukioloajan ajanjakso voi olla päivä tai pidempi ajanjakso. Tässä osuudessa on mahdollista valita myös vaihtoehto 'Suljettu koko päivän'.

1) Päivä, Ajanjakso: 26.12.2023

{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-26T00:00:00",
"validTo": null,
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 9: päivä",
"language": "fi"
}
],
"openingHour": [
{
"dayFrom": null,
"dayTo": null,
"from": "12:00:00",
"to": "15:00:00"
}
]
}

2) Päivä - suljettu koko päivän

Ajanjakso: 26.12.2023
{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-25T00:00:00",
"validTo": null,
"isClosed": true,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 10: päivä, suljettu koko päivän",
"language": "fi"
}
],
"openingHour": []
},

3) Ajanjakso, Ajanjakso: 24.12.2023-25.12.2023

Aukioloajat:
• torstaista klo 20:00 perjantaihin klo 10:00
{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-24T00:00:00",
"validTo": "2023-12-25T00:00:00",
"isClosed": false,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 11: ajanjakso",
"language": "fi"
}
],
"openingHour": [
{
"dayFrom": null,
"dayTo": null,
"from": "20:00:00",
"to": "10:00:00"
}
]
}

4) Ajanjakso - suljettu koko päivän, Ajanjakso: 26.12.2023-27.12.2023

{
"serviceHourType": "Exceptional",
"validFrom": "2023-12-26T00:00:00",
"validTo": "2023-12-27T00:00:00",
"isClosed": true,
"validForNow": false,
"isAlwaysOpen": false,
"isReservation": false,
"additionalInformation": [
{
"value": "Testi 12: ajanjakso, suljettu koko päivän",
"language": "fi"
}
],
"openingHour": []
}