Ohjelmiston rekisteröinti ja hyväksyntämenettely
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.
Ohjelmiston tuotantokäytön hyväksyntämenettely
20.11.2023 alkaen rajapintojen tuotantokäyttö edellyttää ohjelmistojen hyväksymistestausta. Ohjelmiston hyväksymistestaus tehdään itsepalveluna API-portaalissa. Testauksen suorittajalla tulee olla tuotantovarmenne. Hyväksymistestausmenettelyssä API-portaaliin tuodaan rajapintakohtaiset testiskenaariot, joiden tarkoitus on varmistaa laadukas integraatio, vähentää rajapintojen käytössä esiintyviä virhetilanteita ja selkeyttää rajapintojen käyttöönottoprosessia.
Rajapintakohtaiset testiskenaariot suoritetaan kutsumalla rajapinnan verifiointiosoitetta skenaariossa kuvatulla tavalla. Jokaisella rajapinnalla on vähintään yksi perusskenaario, jossa ohjelmiston pitää antaa onnistunut kutsu, joka läpäisee rajapinnan liiketoimintasäännöt, syötetarkistukset ja virhetarkistukset. Rajapinnalla voi olla myös useampi testiskenaario. Käyttäjän tulee läpäistä silloin jokainen testiskenaarioista, jotta tuotantolupa voidaan myöntää. Onnistuneen testauksen jälkeen ohjelmisto saa automaattisesti tuotantoluvan.
Huomioitavaa tuotantoluvasta:
- Kaikkien uusien 20.11.2023 jälkeen rekisteröityjen ohjelmistojen tulee suorittaa hyväksyntätestaus kaikille rajapinnoille.
- Hyväksyntätestaus ei koske ennen 20.11.2023 rekisteröityjä ohjelmistoja ja niiden jo käyttämiä rajapintoja. Nämä ohjelmistot voivat jatkaa rajapintojen käyttöä ilman katkoa.
- Hyväksymistestaus tulee suorittaa, kun ohjelmisto ottaa uusia rajapintoja käyttöön. Tämä koskee kaikkia rekisteröityneitä ohjelmistoja. Esimerkiksi rekisteröity ohjelmisto käyttää tällä hetkellä ennakonpidätystietojen kyselyrajapintaa ja ottaa käyttöön 20.11. jälkeen kotitalousvähennyksen ilmoittamisrajapinnan. Hyväksymistestaus tulee suorittaa kotitalousvähennyksen ilmoitusrajapinnalle.
- Suosittelemme myös olemassa oleville ohjelmistoille testiskenaarioiden suorittamista. Olemassa olevan rajapinnan tuotantolupaa ei poisteta, vaikka testiskenaariot eivät menisi läpi.
- Testiskenaarioita voi suorittaa uudestaan, vaikka tuotantolupa on jo kerran myönnetty. Tätä voidaan hyödyntää esimerkiksi ohjelmiston uuden version testaamisessa API-portaalissa.
- Ohjelmistotalon ei tarvitse ottaa erikseen yhteyttä Verohallintoon testauksen aloittamisesta tai lopettamisesta. Ongelma- tai virhetilanteissa käyttäjä voi kuitenkin ottaa yhteyttä havaintolomakkeella.
Tarkentavia ohjeita testiskenaarioiden suorittamisesta:
- Testiskenaarioissa 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.
- Testiskenaarion suorittamiseksi 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 hyväksymistestausta varten.