Ohjelmointirajapinta (API)

Avoimuusrekisterin voi yhdistää omaan toiminnanohjausjärjestelmään tai muuhun vastaavaan työkaluun ohjelmointirajapinnan (API) avulla. Integraation avulla toimintailmoituksen tiedot voi siirtää koneellisesti avoimuusrekisteriin, mikä vähentää raportoinnista aiheutuvaa manuaalista työtä.

API (Application Programming Interface) on ohjelmointirajapinta, jolla voi siirtää tietoja eri ohjelmistojen välillä. Rajapinnan avulla ilmoitusvelvolliset voivat lähettää toimintailmoituksensa avoimuusrekisteriin.

Integraatio vähentää ilmoitusvaiheen manuaalista työtä

Integraatio tehostaa ilmoitusprosessia poistamalla siitä ylimääräisen manuaalisen vaiheen. Kun ilmoitusvelvollinen kerää vaikuttamistoimintansa tiedot käyttämäänsä järjestelmään, se voi ilmoituskauden alettua siirtää tiedot sieltä avoimuusrekisteriin koneellisesti. Tällöin prosessista jää kokonaan pois työvaihe, jossa tiedot kerätään omasta järjestelmästä ja syötetään yksitellen avoimuusrekisteriin.

Integraatiosta hyötyvät eniten sellaiset ilmoitusvelvolliset, joiden on raportoitava useita vaikuttamistoiminnan tai vaikuttamistoiminnan neuvonnan aiheita. Avoimuusrekisteriin ei ilmoiteta jokaista yksittäistä tapaamista vaan vaikuttamistyöstä ilmoitetaan aihe kerrallaan. Siksi ilmoitusvelvollinen, jolla on vain muutama eri vaikuttamistoiminnan tai vaikuttamistoiminnan neuvonnan aihe, tekee ilmoituksen näppärästi entiseen tapaan suoraan avoimuusrekisterin asiointipalvelussa.

Integraation toteuttaja vastaa integraatiosta ja sen kustannuksista

Integroituminen vaatii teknistä osaamista sekä mahdollisuuden muokata käytössä olevaa järjestelmää vastaamaan avoimuusrekisterin vaatimuksia. Ilmoitusvelvollinen voi rakentaa tai rakennuttaa integraation itselleen tai se voi hyödyntää erilaisten palveluntarjoajien valmiita, avoimuusrekisteriin integroituja palveluita.

Rajapinnan käyttö on maksutonta, mutta integraation toteuttaja vastaa itse integraatioon liittyvän kehitystyön ja toteutuksen kustannuksista.

Tilaa rajapintaa koskevat asiakastiedotteet sähköpostiisi

VTV tiedottaa integraatioon vaikuttavista teknisistä muutoksista ja muista rajapintaa koskevista asioista. Tilaa avoimuusrekisteri-integraation asiakastiedotteet, niin saat aina tarvittavat tiedot sähköpostiisi. Aiemmin lähetettyihin asiakastiedotteisiin voi tutustua arkistossa.

Ohje ilmoitusvelvolliselle

Oma integraatio avoimuusrekisteriin

Jos olet ilmoitusvelvollinen ja haluat rakentaa integraation käyttämäsi tietojärjestelmän ja avoimuusrekisterin välille, seuraa näitä ohjeita. Katso lisäksi tarkemmat ohjeet teknisestä toteutuksesta alempaa.

  1. Täytä rajapintasopimus ja toimita se osoitteeseen avoimuusrekisteri@vtv.fi.

  2. Kun sopimus on allekirjoitettu ja sillä ilmoittamasi IP-osoite lisätty pääsyrajoitettuun testiympäristöön, saat vastauksena ohjeet testiympäristöön pääsystä.

  3. Tee integraatio testiympäristöön ja testaa teknisten ratkaisujen toimivuus.

  4. Kun testaus on suoritettu sopimuksessa kuvatulla tavalla, ilmoita VTV:lle (avoimuusrekisteri@vtv.fi) tuotantoon siirtymisestä ja pyydä ”API-avaimien hallinta” -sivun aktivointia avoimuusrekisterin asiointipalveluun, jotta voitte luoda tuotannon API-avaimen.

  5. Kun asiointipalvelussa näkyy ”API-avaimien hallinta” -sivu, luo avain. Valitse integraation toteutustavaksi ”Integroimme oman järjestelmämme avoimuusrekisteriin”. Ota luotu avain heti talteen. Tietoja ei saa näkyville enää myöhemmin vaan tietojen hävittyä on luotava uusi avain.

  6. Ennen ensimmäistä tuotantoon tehtävää toimintailmoitusta, ilmoita VTV:lle (avoimuusrekisteri@vtv.fi) ajankohta, jolloin otatte tuotantorajapinnan käyttöön.

  7. Muistathan luoda ja ottaa käyttöön uuden API-avaimen, kun edellinen vanhenee.

Palveluntarjoajan integroima palvelu

Jos olet ilmoitusvelvollinen ja haluat käyttää kolmannen osapuolen tarjoamaa palvelua toimintailmoitusten tekemiseen, seuraa näitä ohjeita.

  1. Sovi käytännöistä palveluntarjoajan kanssa. Tee kirjallinen valtuutus, jossa valtuutat palveluntarjoajan toimimaan puolestasi sovituissa avoimuusrekisteriasioissa.

  2. Palveluntarjoajasi tarvitsee API-avaimen, jolla se kohdentaa toimintailmoituksenne organisaatiollenne. Ota yhteyttä osoitteeseen avoimuusrekisteri@vtv.fi ja pyydä ”API-avaimien hallinta” -sivun aktivointia avoimuusrekisterin asiointipalveluun, jotta voitte luoda avaimen.

  3. Kun asiointipalvelussa näkyy ”API-avaimien hallinta” -sivu, luo avain. Valitse käyttämäsi palveluntarjoaja valmiista listasta. Jos palveluntarjoajaasi ei löydy listalta, pyydä sitä ottamaan yhteyttä osoitteeseen avoimuusrekisteri@vtv.fi. Voit luoda API-avaimen, kun palveluntarjoaja on lisätty listalle. Ota luotu avain heti talteen. Tietoja ei saa näkyville enää myöhemmin, vaan tietojen hävittyä on luotava uusi API-avain.

  4. Lähetä API-avain palveluntarjoajallesi sen suosittelemalla tietoturvallisella tavalla, jotta avain ei joudu vääriin käsiin. Lähetä avain vain luotetulle taholle.

  5. Toimi palveluntarjoajasi ohjeiden mukaan.

  6. Muista luoda ja toimittaa palveluntarjoajallesi uusi API-avain, kun edellinen vanhenee.

Ohje palveluntarjoajalle

Jos olet palveluntarjoaja, joka rakentaa integraation oman palvelunsa ja avoimuusrekisterin välille, jotta asiakkaanne (ilmoitusvelvolliset) voivat ilmoittaa sen kautta, seuraa näitä ohjeita. Katso lisäksi tarkemmat ohjeet teknisestä toteutuksesta alempaa.

  1. Täytä rajapintasopimus ja toimita se osoitteeseen avoimuusrekisteri@vtv.fi.

  2. Kun sopimus on allekirjoitettu ja sillä ilmoittamasi IP-osoite lisätty pääsyrajoitettuun testiympäristöön, saat vastauksena ohjeet testiympäristöön pääsystä.

  3. Tee integraatio testiympäristöön ja testaa teknisten ratkaisujen toimivuus vähintään sopimuksessa kuvatulla tavalla.

  4. Pyydä jokaiselta asiakasorganisaatiolta kirjallinen valtuutus, josta ilmenee, missä avoimuusrekisteriasioissa palveluntarjoajalla on valtuudet toimia.

  5. Siirry tekemään integraatio tuotantoympäristöön.

  6. Ilmoitusvelvolliset voivat luoda organisaatiokohtaisen API-avaimen avoimuusrekisterin asiointipalvelussa ”API-avaimien hallinta” -sivulla. Sivu ei näy asiointipalvelussa automaattisesti, vaan asiakkaiden on pyydettävä sivun aktivointia osoitteesta avoimuusrekisteri@vtv.fi päästäkseen luomaan avaimen. Palveluntarjoaja voi myös keskitetysti pyytää aktivointia asiakkaidensa puolesta.

  7. Kun asiakkaalle on aktivoitu ”API-avaimien hallinta” -sivu, pyydä asiakasta luomaan asiointipalvelussa organisaatiokohtainen API-avain. Avainta luodessaan asiakkaan on määritettävä avaimelle voimassaoloaika ja ilmoitettava palveluntarjoajansa. Palveluntarjoajaksi voi merkitä vain tahon, joka on toimittanut VTV:lle täytetyn rajapintasopimuksen. Muistathan ohjeistaa asiakasta toimittamaan API-avain teknisestä toteutuksesta vastaavalle henkilölle tietoturvallisesti, jottei se joudu vääriin käsiin.

  8. Ennen ensimmäistä tuotantoon tehtävää ilmoitusta, ilmoita VTV:lle (avoimuusrekisteri@vtv.fi) ajankohta, jolloin otatte tuotantorajapinnan käyttöön.

  9. Muistathan vaihtaa API-avaimen uuteen, kun se vanhenee. Ilmoitusvelvollinen voi luoda uuden avaimen asiointipalvelussa.

API-rajapinnan testaus ja käyttöönotto

Alla nostetaan esiin tärkeimpiä huomioitavia asioita integraation tekemiseksi. Rajapinnan tarkemmat määrittelyt eli skeeman löydät Swagger-palvelusta. Ohjeessa linkitetään avoimuusrekisterin tuotantoympäristöön liittyvän Swaggerin kohtiin, joista voi tarkistaa, mitä arvoja kulloinkin kyseessä olevat kutsut ottavat vastaan tai palauttavat. Vastaavat kohdat on löydettävissä myös testiympäristön Swaggerissa.

Pääsy testiympäristöön

  1. Testaa API-rajapintaa avoimuusrekisterin testiympäristössä ennen sen käyttöönottoa. Pääsy testiympäristöön on rajoitettu, joten toimita täytetty rajapintasopimus osoitteeseen avoimuusrekisteri@vtv.fi.

  2. Sopimuksen allekirjoittamisen jälkeen ilmoittamasi IP-osoite lisätään sallittujen osoitteiden listaan. Saat myös testiympäristön osoitteen ja testihenkilötunnuksia sinne kirjautumiseen.

Huomioithan, että testiympäristö on avoinna vain arkipäivisin kello 8–20 välillä.

Testiympäristön käyttäminen

  1. Kirjaudu avoimuusrekisterin testiympäristössä asiointipalveluun oikean yläkulman ”Kirjaudu”-painikkeesta. Valitse kirjautumistavaksi testitunnistaja ja käytä testihenkilötunnusta VTV:ltä saamiesi ohjeiden mukaan. Valitse seuraavassa vaiheessa organisaatio, jota edustat. Huomioithan, että valitsemasi testihenkilötunnus saattaa olla jo käytetty. Valitse silloin toinen, käyttämätön tunnus. Tunnistat käyttämättömän tunnuksen siitä, että kirjauduttuasi sinulta kysytään suostumusta henkilötietojen käsittelyyn ja sähköiseen tiedoksiantoon, eikä organisaatiolla ole vielä rekisteröinti-ilmoitusta.

  2. Tee rekisteröinti-ilmoitus.

  3. Testiympäristössä ilmoituskausi ei aina ole auki ja tällöin toimintailmoituksia ei voi tehdä. Siirry silloin asiointipalvelussa ”Testaajan työkalut” -sivulle, jossa voit aktivoida epäaktiivisia toimintailmoituksia täytettäviksesi. Aktivoi toimintailmoitukset napsauttamalla rivin päässä olevaa salamaikonia.

  4. Avoimuusrekisterin toimintailmoituksessa ilmoitetaan kerran vuodessa kesäisin myös vaikuttamistoiminnan taloudelliset tiedot. Niiden testaamiseksi on asetettava seuraavanlainen testiasetelma:

    1. Siirrä ”Testaajan työkalut” -sivulla rekisteröinti-ilmoituksen luontipäivämäärä pari vuotta aiemmaksi, jotta testiorganisaatio on ollut rekisterissä riittävän pitkään tietojen antamiseksi (vähintään kokonainen kalenterivuosi).

    2. Aktivoi ja täytä kaksi toimintailmoitusta siten, että ne kattavat kokonaisen kalenterivuoden. Raportoi ilmoituksilla vaikuttamistoiminnasta (älä valitse laajuudeksi ”Ei lainkaan yhteydenottoja”). Aktivoi vielä kolmas peräkkäinen toimintailmoitus. Kolmannella toimintailmoituksella kysytään taloudelliset tiedot.

  5. Siirtymällä asiointipalvelun etusivulle ja napsauttamalla ”Tee toimintailmoitus” -painiketta voit testata, miltä toimintailmoituksen tekeminen näyttää käyttöliittymässä tai voit alkaa testata toimintailmoitusten tekemistä rajapinnan kautta.

API-avaimen luominen

  1. Integraatiossa käytetään API-autentikointia. Ilmoitusvelvollinen voi luoda sitä varten tarvittavan API-avaimen avoimuusrekisterin asiointipalvelussa.

  2. API-avaimet luodaan ”API-avaimen hallinta” -sivulla, joka ei ole automaattisesti näkyvillä asiointipalvelussa. Aktivoi sivu näkyville testiympäristössä ”Testaajan työkalut” -sivulla klikkaamalla ”Aktivoi API-avaimien hallinta”. Tuotantoympäristössä sivun aktivointia on pyydettävä VTV:ltä (avoimuusrekisteri@vtv.fi).

  3. Siirry ”API-avaimien hallinta” -sivulle. Luo API-avain. Muista ottaa avaimen tiedot talteen heti luotuasi sen. Tietoja ei saa näkyville enää myöhemmin, vaan tietojen hävittyä on luotava uusi API-avain.

Toimintailmoituksen tekeminen rajapinnan kautta

  1. Kirjaudu käyttämällä luomaasi API-avainta. Kirjautuminen palauttaa pääsyavaimen (access token), jota käytetään muissa kutsuissa Authorization headerissa. Pääsyavain on voimassa neljä tuntia. Huomioithan, että ilmoittamisessa käytettävät endpointit on koottu Swagger-palvelussa ”Customer API” -otsikon alle (pl. ilmoituskausien haku).

  2. Toimintailmoituksessa ilmoitetaan vaikuttamistoiminnan aiheet. Aiheet voivat olla omia vapaamuotoisesti kirjoitettuja aiheita (50–600 merkkiä) tai virallisia valtioneuvoston hankkeita. Ilmoita virallisesta hankkeesta hankenumero ja nimi siten kuin ne löytyvät Hankeikkunasta.

  3. Aiheeseen liittyvät vaikuttamistoiminnan kohteet valitaan VTV:n ylläpitämästä listasta. Hae kohteet rajapinnasta joko ilmoituskausittain tai kaikki kerralla. GET customer-api/target/all/{termId} tai GET customer-api/target/targets Kohteen ID-tunnus on ilmoituskausikohtainen. Koska moni vaikuttamistoiminnan kohde on mukana usean ilmoituskauden ajan, on kohde lisättävä käyttäen sen ilmoituskauden ID-tunnusta, jolle ilmoitusta ollaan tekemässä. VTV tekee lisäyksiä, muokkauksia ja poistoja kohdetiedoissa ilmoituskauden alkamispäivään saakka. Ilmoituskauden aikana kohteisiin tehdään vain välttämättömiä korjauksia tai lisäyksiä.

  4. Ilmoituskaudet voit hakea GET open-data-term -rajapinnasta. Se palauttaa tuloksena sekä menneiden että tulevien ilmoituskausien tiedot. Ilmoitukset on tehtävä kausille kronologisessa järjestyksessä.

  5. Tee toimintailmoituksesta ensin luonnos (”draft”). Luonnosta ei validoida tässä kohtaa. POST customer-api/draft-activity-notification Jos haluat päivittää tehtyä luonnosta, lähetä koko luonnos uudelleen PATCH-metodilla. Huomaathan, että päivitykset ylikirjoittavat mahdolliset käyttöliittymässä tehdyt muutokset. PATCH customer-api/draft-activity-notification/{draftId}

  6. Validoi luonnos ennen julkaisua. Jos validointi epäonnistuu, saat paluusanomana virheilmoituksen ja listan ilmoituksessa ilmenevistä ongelmista. GET customer-api/draft-activity-notification/validate/{draftId} Tarkista onnistuneen validoinnin jälkeen käyttöliittymästä, että luonnos näyttää oikealta ja aiheet ja kohteet ovat siirtyneet onnistuneesti.

  7. Julkaise validoinnin läpäissyt luonnos. Ilmoitus validoidaan myös julkaisun yhteydessä. POST customer-api/activity-notification/publish/{draftId} Julkaistu toimintailmoitus näkyy avoimuusrekisterin verkkosivuilla ilman kirjautumista. Tarkista käyttöliittymästä, että ilmoitus on oikein. Jos julkaistua ilmoitusta tarvitsee muokata, tee se avoimuusrekisterin käyttöliittymässä asiointipalveluun kirjautumalla.

  8. Testiympäristössä on ylimääräinen testausta helpottava rajapinta, joilla voi hakea ja poistaa yksittäisiä tai kaikki organisaation toimintailmoitukset, jotta niiden tekemistä voi testata uudelleen. Testiympäristö: DELETE customer-api/test-utils/

Tuotantoympäristöön siirtyminen

  1. Voit siirtyä rakentamaan integraation tuotantoympäristöön, kun olet testannut testiympäristössä vähintään kerran seuraavat testitapaukset:

    1. Luonut toimintailmoituksen luonnoksen rajapinnan kautta ja validoinut sen onnistuneesti

    2. Päivittänyt toimintailmoitusluonnosta onnistuneesti rajapinnan kautta

    3. Julkaissut toimintailmoituksen onnistuneesti rajapinnan kautta tai julkaissut rajapinnan kautta tehdyn toimintailmoituksen asiointipalvelun käyttöliittymässä

    4. Varmistanut, että julkaistu toimintailmoitus näkyy oikein käyttöliittymässä

    5. Huomioinut, että toimintailmoituksella annetaan kerran vuodessa myös taloudelliset tiedot.

  2. Ennen ensimmäistä tuotantoon tehtävää ilmoitusta, ilmoita VTV:lle (avoimuusrekisteri@vtv.fi) ajankohta, jolloin otatte tuotantorajapinnan käyttöön.

  3. Avoimuusrekisteriin tehdään toimintailmoitus kahdesti vuodessa. Toimintailmoituksen tiedot on toimitettava avoimuusrekisteriin ilmoituskauden ollessa auki tammi–helmikuussa ja heinä–elokuussa. Ilmoituskauden sulkeutumisen jälkeen saapuneet toimintailmoitukset merkitään myöhästyneiksi.