Rajapintaversion 12 muutosloki

Tämä muutosloki koskee Palvelutietovarannon rajapintaversiota 12 asiakastesti- ja tuotantoympäristössä.

Huom. tuotannon rajapintaversio 12 on betaversio.

Rajapintaa kehitetään parhaillaan ja siihen voi tulla hyödyntäjän kannalta rikkovia muutoksia kehitystyön aikana keväällä ja kesällä 2026.

Ennakkotietoja muutoksista

Ei-rikkovat muutokset

Postitoimipaikat - alustava julkaisupäivä 19.5.2026

Uusi rajapinta postinumeroiden ja postitoimipaikkojen hakuun.

Rikkovat muutokset

Lisätty muutoslokiin: 17.3.2026
Hakujen sivutus - mahdollisesti rikkova muutos tulossa

• Sivutetuissa hauissa on havaittu tilanteita, joissa hakutulokset eivät aina ole täysin luotettavia. Joissakin tapauksissa sama sisältö (esim. palvelu) voi esiintyä kahteen kertaan tai jäädä kokonaan pois tuloksista. Tämä voi tapahtua esimerkiksi silloin, jos sisältö arkistoidaan tai palautetaan kesken tietojen haun.

Pohjakuvaus (General description) - alustava julkaisupäivä 19.5.2026

• Pohjakuvauksen generalDescriptionType on ollut yksittäinen arvo, esim. Municipality. Jatkossa se on lista eli pohjakuvaus on voitu tehdä useampaan käyttöön (esim. Kuntien palvelut ja Työllisyysalueiden palvelut).

Muuta huomioitavaa

Tällä hetkellä ei ole rajapintaa, jolla saisi tietoonsa, mihin kuntaan tms. alueeseen tietty postinumero kuuluu.

Tuotantoympäristön resursseja säädetään kehitystyön aikana, ja kuormitus voi aiheuttaa ajoittaisia 5xx-virheitä.

Julkaistut muutokset 5.5.2026 (tuotanto- ja asiakastestiympäristö)

Lisätty muutoslokiin: 5.5.2026

Ei-rikkovat muutokset

• API-avaimen hallinnointikäyttöliittymässä voi luoda useita API-avaimia eri integraatioita varten (max. 10)​

Rikkovat muutokset

Ei rikkovia muutoksia

Julkaistut muutokset 22.4.2026 (tuotanto- ja asiakastestiympäristö)

Lisätty muutoslokiin: 22.4.2026

Rikkovat muutokset

Koodistojen name-kentässä palautuvat kieliversiot

Koodistojen haut ovat palauttaneet name -kentässä kaikki kielet, vaikka kyseiselle kielelle ei ole ollut käännöstä:

 "name": {
        "fi": "Asuminen",
        "sv": "Boende",
        "en": "Housing",
        "se": null,
        "smn": null,
        "sms": null
      }

Jatkossa rajapinta palauttaa name -kentässä vain ne kielet, joille on käännös:

   "name": {
        "fi": "Asuminen",
        "sv": "Boende",
        "en": "Housing"
      }

Muutos koskee kaikkia rajapintoja, jotka on ryhmitelty API-dokumentaatiossa (scalar) osioon Reference data.

Koodistot, maiden haku

Maiden haku (GET /api/v12/country-codes) palauttaa myös isValid - kentän.

Pohjakuvaus (General description)

• Pohjakuvauksissa on aiemmin palautettu additionalInformation kenttä, joka on sisältänyt ohjeen PTV:n käyttöliittymän käyttäjille. Tätä kenttää ei palauteta enää rajapinnasta.

Julkaistut muutokset 7.4.2026 (tuotanto- ja asiakastestiympäristö)

Lisätty muutoslokiin: 8.4.2026

Ei-rikkovat muutokset

• Scalarin rajapintadokumentaatiossa hakurajapintoihin on lisätty esimerkkejä käytettävistä arvoista.

Rikkovat muutokset

• Schema-pääte on poistettu rajapinnan tyypeistä (vaikuttaa, jos integraattori generoi koodia rajapinnan kuvauksesta).

Julkaistut muutokset 24.3.2026 (tuotanto- ja asiakastestiympäristö)

Lisätty muutoslokiin: 8.4.2026

Ei-rikkovat muutokset

• Palveluita ja kanavia voi hakea antamalla palvelukokonaisuuden id.
• Lomakkeilla on migratedAt aikaleima, joka kertoo milloin tieto on tuotu vanhasta järjestelmästä.
• Scalarissa serviceTypes valintalista on korjattu (aikaisemmin listalta ei voinut valita mitään).
• Scalarissa parametrien pakollisuus ei aina näkynyt oikein. Esim. arkistoitujen haussa archivedAtOrAfter on pakollinen, mutta scalar ei tätä näyttänyt.
• Palvelukokonaisuuksien haku tukee publishedAtOrAfter filtteriä.
• Pohjakuvausten haku tukee publishedAtOrAfter filtteriä.
• Liitosten haku tukee publishedAtOrAfter filtteriä.
• Liitokselle palautetaan publishedAt aikaleima.
• V12 rajapinnalla haettuna joidenkin asiointikanavien aluetiedoksi (area) palautui null. Tämä on korjattu.
• Muotoiltujen tekstikenttien markdownissa oli puutteita, tämä on korjattu.

Rikkovat muutokset

Ei rikkovia muutoksia

Muuta huomioitavaa

Muotoillut tekstikentät
PTV:n muotoiltuihin tekstikenttiin on tehty parannuksia, jotta sisältö toimii luotettavammin eri käyttötilanteissa – esimerkiksi silloin, kun tekstiä näytetään suoraan verkkosivuilla.
Rajapintaversio 12 tukee CommonMark‑standardiaAvautuu uuteen ikkunaan. ja CommonMarkin työkalullaAvautuu uuteen ikkunaan. voi tarkastella, miltä teksti tulee näyttämään.
Jos muotoillut tekstit näyttävät käyttötilanteissa virheellisiltä, voit siis tarkastella niitä CommonMarkin työkalulla ja tarvittaessa olla meihin yhtetydessä.

Julkaistut muutokset 3.3.2026 (asiakastestiympäristö)

Ei-rikkovat muutokset

Lisätty muutoslokiin: 10.3.2026

Pohjakuvauksen käyttöaluetyypit (käytön tyypit)

Pohjakuvauksen käyttöaluetyypeissä on useampia vaihtoehtoja.

"enum": [ "Church", "EmploymentArea", "Municipality", "Other", "WellbeingServicesCounty"]

Palvelupaikan osoitetiedoissa esteettömyyssovelluksen id

GET service-channel palvelupaikan (ServiceLocation) osoitetiedoissa palautuu esteetttömyyssovelluksen id (accessibilityRegisterServicePointId).

Scalar-dokumentaatiossa kerrotaan miten id:n avulla voi hakea estettömyystiedot palvelupaikalle. Katso scalarista Service channel by content id -> valitse "service location" tyyppinen asiointikanava ja ja sen vastauksessa on location, jonka sisältä löytyy streetAddresses.

Julkaistut muutokset 17.2.2026 (asiakastestiympäristö)

Ei-rikkovat muutokset

Lisätty muutoslokiin: 10.3.2026

Scalarin dokumentaatiota parannettu

Arkistoituneiden haku pohjakuvauksille

GET /api/v12/service-collection/archived

Palvelukokonaisuuden haku

Palvelukokonaisuuden haku palauttaa myös listan palveluista ja asiointikanavista (content id, tyyppi) jotka kuuluvat palvelukokonaisuuteen.

Hakurajapintojen parametrien validointi

Parannettu hakurajapintojen parametrien validointia alueeseen liittyvien hakuparametrien osalta.

Rikkovat muutokset

Lisätty muutoslokiin: 10.3.2026

Palvelukokonaisuuden rajapinta

Poistettu palvelukokonaisuuden rajapinta /contentId/items jolla voi hakea palvelukokonaisuuteen kuuluvat lomakkeet.

Muutos rajapintojen polkuihin (content-id)

Rajapintojen polut muuttuneet ja content-id poistettu esim.

/api/v12/service/content-id/{contentId} -> /api/v12/service/{contentId}

Lisätty muutoslokiin: 9.2.2026

Wellbeing services counties haku

api/v12/wellbeing-service-county-codes -> api/v12/wellbeing-services-county-codes

Kanavien, palveluiden ja organisaatioiden haku

wellbeingServiceCountiesMatch -> wellbeingServicesCountiesMatch
wellbeingServiceCounties -> wellbeingServicesCounties

Kanavan, palvelun ja organisaation aluetiedoissa

area.wellbeingServiceCounties -> area.wellbeingServicesCounties

Lisätty muutoslokiin: 5.2.2026

Kaikki rajapinnat joilla haetaan yksittäinen lomake

Polusta on poistettu ylimääräinen content-id esim. 

api/v12/service-channel/content-id/{contentId} -> api/v12/service-channel/{contentId}

Kaikki asiointikanavien rajapinnat

Rajapintojen polut ovat muuttuneet siten että /channel -> /service-channel esim. kanavien haku

/api/v12/channel/search -> /api/v12/service-channel/search

Yksittäisen kanavan haku ja kanavien hakurajapinta

Kenttä channelType -> serviceChannelType

Kentässä channelType palautuvat arvot ovat muuttuneet:

ElectronicChannel -> EService
PhoneChannel -> TelephoneService
PrintableFormChannel -> PrintableForm
ServiceLocationChannel -> ServiceLocation
WebChannel -> WebPage

Verkkoasiointikanava (EService channel)

signature -> electronicSignature
signature.quantity -> electronicSignature.numberOfRequiredSignatures
authentication -> electronicIdentification
link -> webAddress

Puhelinasiontikanava (TelephoneService)

link -> webAddress

Verkkosivu asiointikanava (WebPage)

link -> webAddress

Pohjakuvaus

Rajapinta palauttaa summary kentän.

keywords -> freelyAssginedKeywords

Provinces -> Regions

/api/v12/province-codes -> /api/v12/region-codes

Kanavien, palveluiden ja organisaatioden hakurajapinta:

provinces -> regions
provincesMatch, regionsMatch
area.provinces -> area.regions (vastauksessa)

Kanavien, palveluiden ja organisaatioden haku content id:llä, vastauksessa:

area.provinces -> area.regions