Rajapintaversion 12 muutosloki

Tämä muutosloki koskee Palvelutietovarannon rajapintaversiota 12.

Ympäristöjen tilanne

Hakurajapinta

Hakurajapinnan version 12 betaversio on julkaistu asiakastesti- ja tuotantoympäristöön.

• Rajapintaan voi tulla lokakuun 2026 loppuun saakka rikkovia muutoksia esimerkiksi virhekorjausten vuoksi.
• Marraskuun 2026 alusta lähtien rikkovia muutoksia ei enää tehdä. Rajapintaan voidaan kuitenkin lisätä uusia kenttiä.

Tuontirajapinta

Tuontirajapinnan versio 12 julkaistaan ensin asiakastestiympäristöön.

• Tuontirajapintaa kehitetään parhaillaan ja siihen voi tulla hyödyntäjän kannalta rikkovia muutoksia kehitystyön aikana.

Ennakkotietoja muutoksista

Ei-rikkovat muutokset

Ei tiedossa olevia muutoksia.

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.

Muuta huomioitavaa

Tuontirajapinnan kutsuissa ei ole vielä mukana palveluaikojen tuontia.

Asiakastestiympäristön tuontirajapinnan käyttöön tarvittavat testitunnukset (API-käyttäjätunnus + salasana tokenin hakuun) on julkaistu kehittäjille sivuston ohjeessa Tuonti-integraation testaus asiakastestiympäristössä.

Julkaistut muutokset 6.10.2026

Lisätty muutoslokiin: 6.10.2026

Ei-rikkovat muutokset

Hakurajapinta externalId/contentId mäppäykselle (asiakastestiympäristö)

• GET /api/v12/service/external-ids
• GET /api/v12/organization/external-ids
• GET /api/v12/service-channel/external-ids

Tuontirajapinnan ensimmäiset versiot rajapintakutsuista ja autentikaatio on julkaistu testikäyttöön (asiakastestiympäristö) Täydennetty muutoslokiin: 7.10.2026

• POST/PUT/DELETE organization
• POST/PUT/DELETE service
• POST/PUT/DELETE connection
• POST/PUT/DELETE service-channel
• POST/PUT/DELETE service-collection
• Huom. tuontirajapinnan kutsuissa ei ole vielä mukana palveluaikojen tuontia.

Rikkovat muutokset

Muutos Palvelukokonaisuuden items -taulukossa (tuotanto- ja asiakastestiympäristö)

Palvelukokonaisuuden (Service collection) items -taulukon ItemType -kentän arvoissa muutos: Channel -> Service Channel

Muutoksen jälkeen:

 "itemType": {
            "enum": [
              "Service",
              "ServiceChannel"
            ],
            "type": "string"
          },

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

Lisätty muutoslokiin: 8.9.2026

Ei-rikkovat muutokset

Arkistoitujen liitosten haku
Uusi rajapinta arkistoitujen liitosten hakuun.

GET /api/v12/connection/archived

Rikkovat muutokset

Ei muutoksia

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

Lisätty muutoslokiin: 25.8.2026

Ei-rikkovat muutokset

Haku kieliversioiden perusteella

Organisaatioita, palveluita ja asiointikanavia voi hakea julkaistujen kieliversioiden kielien perusteella. Tuki usealla kielellä hakuun normaalin any/all valinnan kanssa. Voit esimerkiksi hakea:

• palvelut, joissa on fi-kieliversio, sv-kieliversio tai en-kieliversio
• asiointikanavat, joissa on fi-kieliversio ja sv-kieliversio.

Rikkovat muutokset

Ei muutoksia

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

Lisätty muutoslokiin: 25.8.2026

Rikkovat muutokset

Virheviestit: Virheviestien path-osio muuttuu: ennen polku oli JSONPath ja jatkossa käytössä on JSON Pointer.

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

Lisätty muutoslokiin: 30.6.2026

Ei-rikkovat muutokset

Ei muutoksia

Rikkovat muutokset

Hakurajapinta: poistettu hakeminen externalId:n perusteella. Tämän osalta päivitetty ohjetta: Keskeiset parannukset ja muutokset.

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

Lisätty muutoslokiin: 10.6.2026

Ei-rikkovat muutokset

Verkkosivu- ja verkkoasiointikanavalle palautuu uutena kenttänä verkkosivun nimi. Nimi -kenttä on tässä vaiheessa tyhjä, koska tietoa ei voi version 11 puolella antaa. Kenttä on tulossa versiossa 12 käyttöön (tuontirajapinta ja version 12 mukainen UI).

Rikkovat muutokset

Ei muutoksia

Muuta huomioitavaa

Ohjelmalliset rajapintakutsut ilman API-avainta poistuu
Mahdollisuus tehdä ohjelmallisia rajapintakutsuja asiakastestiympäristössä ilman API-avainta (esim. curl) ei enää ole mahdollista.

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

Lisätty muutoslokiin: 2.6.2026

Ei-rikkovat muutokset

Ei muutoksia

Rikkovat muutokset

Pohjakuvaus (General description)

• Pohjakuvauksen tiedoista poistuu tiivistelmä eli summary-kenttä.

Muuta huomioitavaa

Rajapinnan vakauteen on tehty parannuksia, jotka vähentävät 5xx-virheitä merkittävästi.

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

Lisätty muutoslokiin: 19.5.2026

Ei-rikkovat muutokset

Postitoimipaikat

Uusi rajapinta postinumeroiden ja postitoimipaikkojen hakuun.  Suosittelemme, että integraattorit hakevat tiedot omaan välivarastoonsa sen sijaan, että hakevat yksittäisiä postinumeroita rajapinnasta.

GET /api/v12/postal-codes

Rikkovat muutokset

Pohjakuvaus (General description)

• Pohjakuvauksen kenttä generalDescriptionType muuttuu yksittäisestä arvosta listaksi ja sen nimi muuttuu muotoon generalDescriptionTypes. Muutoksen jälkeen pohjakuvaus voidaan tehdä useaan käyttöön (esim. Kuntien palvelut ja Työllisyysalueiden palvelut).

Muuta huomioitavaa

Kuormitus voi aiheuttaa ajoittaisia 5xx-virheitä, mutta tilannetta on parannettu versiopäivityksen myötä.

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