Ohjelmiston rekisteröinti ja API-avain
Ohjelmistotalon tai ohjelmiston kehittäjän on rekisteröitävä rajapintoja käyttävä ohjelmisto Vero API-portaalissa 18.1.2023 alkaen. Rajapintojen käyttö edellyttää ohjelmistokohtaisen API-avaimen tuotannossa 1.6.2023 alkaen ja testiympäristön kutsuissa 18.1.2023 alkaen. Lisäksi rajapintojen käyttö edellyttää käyttäjäkohtaisen varmenteen Verohallinnon varmennepalvelusta.
Ohjelmistojen rekisteröinnin tavoitteena on parantaa rajapintojen käyttökokemusta ja integraatioiden laatua määrämuotoisen käyttöönottomenettelyn ja kohdennetun ohjauksen avulla.
Ohjelmistokehittäjän rekisteröinti
Ohjelmistoa kehittävästä organisaatiosta voi rekisteröityä yksi tai useampi kehittäjä API-portaalin käyttäjäksi. Portaaliin rekisteröidytään sähköpostiosoitteella ja salasanalla. Portaalissa ei käytetä Suomi.fi-tunnistautumista ja kehittäjän ilmoittamaa organisaatiotietoa ei tarkisteta. Portaalissa käsitellään vain kehittäjien ilmoittamia ohjelmiston tietoja.
API-portaalissa kehittäjät kuuluvat kehittäjätiimeihin, joihin he voivat kutsua sähköpostiosoitteella muita kehittäjiä. Tiimirakenteen tarkoituksena on vähentää mm. henkilövaihdoksista johtuvia haasteita päästä ylläpitämään ohjelmiston tietoja. Kaikki kehittäjät voivat luoda tiimejä ja hallita niiden jäseniä itse. Kehittäjillä on samantasoiset käyttöoikeudet keskenään, tämä on huomioitava uusia jäseniä kutsuttaessa.
Ohjelmiston rekisteröinti
Ohjelmistot rekisteröidään API-portaalissa ohjelmiston kehityksestä vastaavan kehittäjätiimin alle. Ohjelmistosta ilmoitetaan nimi, lyhyt käyttötapauskuvaus, ylläpitäjä ja yhteyshenkilön tiedot.
Rekisteröinnin jälkeen valitaan ohjelmiston käyttämät rajapinnat, jolloin ohjelmistokohtaisella API-avaimella pääsee käyttämään valittuja rajapintoja.
Ohjelmistokehittäjän vastuulla on ylläpitää ohjelmiston tietoja, kuten rajapintojen käyttötietoja.
Verohallinto seuraa ohjelmistojen rajapintakäyttöä ja voi poistaa käyttämättömiä ohjelmistoja API-portaalista. Asiasta ilmoitetaan ohjelmiston yhteyshenkilölle.
API-avain
- API-avain on nähtävissä API-portaalissa ohjelmiston tiedoissa ja niitä voi tarvittaessa luoda lisää. API-avain on tarkoitettu rakennettavaksi ohjelmiston sisälle, eikä käyttäjien hallittavaksi.
- Yhdellä ohjelmistolla on lähtökohtaisesti yksi API-avain. Se ei ole pääasiallinen pääsynhallintamekanismi Verohallinnon rajapintoihin.
- API-avain on tarkoitettu vain ohjelmiston kehittäneen organisaation tietoon.
- Ohjelmistokohtainen API-avain asetetaan vero-softwarekey -headeriin ja tulee olla jokaisessa rajapintakutsussa. Tämä on dokumentoitu API-portaalissa jokaisen rajapinnan kuvauksessa.
- API-avain vaaditaan testiympäristöissä, mutta sen sisältöä ei tarkisteta eikä se rajaa pääsyä tiettyihin rajapintoihin
Integraation verifiointi
Tarkoituksena on varmistaa ohjelmiston tuotantoyhteyden ja API-avaimen tekninen toimivuus ohjelmiston käyttämiä rajapintoja vasten. Mikäli ohjelmisto ottaa käyttöön uusia rajapintoja, ne tulee päivittää ohjelmiston tietoihin Vero API-portaalissa.
Ennen ohjelmiston tuotantokäytön aloittamista ohjelmiston kehittäjän on mahdollista 18.1.2023 alkaen verifioida ohjelmiston integraation toimivuus Vero API-rajapintoihin käyttämällä ohjelmistokohtaista API-avainta ja ohjelmistotalon omaa tuotantovarmennetta.
- Ohjelmiston tuotantoyhteyden ja API-avaimen tekninen toimivuus varmistetaan kutsumalla jokaista ohjelmiston käyttämää rajapintaa Vero API-portaalista löytyvällä testiaineistolla
- Varmistuksessa käytettävät rajapintojen osoitteet (URL Integraation verifiointi) löytyvät Vero API-portaalista
- Verifiointiosoitteeseen lähetettyjä kutsuja ei käsitellä verotusjärjestelmässä ja rajapinnan vastaukset ovat samoja staattisia vastauksia kuin alempien testiympäristöjen vastaukset.
- Varmistus tehdään ohjelmistolle vain kerran rajapintaa kohden
- Varmistuksen jälkeen rajapinnan voi ottaa tuotantokäyttöön
- Verohallintoon ei tarvitse olla erikseen yhteydessä, kun tuotantoyhteys ja API-avaimen tekninen toimivuus on varmistettu
- Integraation toimivuuden varmistamiseksi riittää esimerkiksi yksi onnistunut kutsu validilla tietosisällöllä, johon verifiointirajapinta vastaa HTTP 200 paluukoodin
- Integraation verifiointiympäristössä ei tehdä laajempaa testausta vaan ympäristö on tarkoitettu valmiin ohjelmiston integraation varmistusta ja hyväksymistä varten