Vero API yleiskuvaus

Yleisohjeita Vero API rajapintojen käyttäjille

• Vero API-rajapintapalvelujen käyttö edellyttää client-varmennetta. Autentikaatiotapana käytetään client certificate authentication -tapaa, mikä tarkoittaa, että suojatun yhteyden muodostumisessa SSL-kättelyssä tarkistetaan client-varmenteen olemassaolo. Tämä tarkoittaa, että kutsujan varmenne sekä siihen liittyvä yksityinen avain on oltava mukana. Verohallinto ei voi antaa tarkempia ohjeita, miten varmenne liitetään kutsuun, koska tapa riippuu asiakkaan järjestelmäratkaisuista. Lisätietoja autentikaatiotavasta ja sen käyttämisestä löytyy useimmilla hakukoneilla avainsanoilla ”client certificate authentication.”

• Ohjelmistotalon tulee testata integraatio Vero API testirajapintoihin käyttäen testivarmennetta. Testiskenaarioiden tulee sisältää mm. tyypillisimmät käyttötilanteet, rajapinnan palauttaman hyväksytyn syötteen sekä virheilmoitusten käsittelyn, varautuminen käyttökatkotilanteisiin sekä odottamattomiin virheisiin.

• Ohjelmistotalo rakentaa rajapintoja käyttävään ohjelmistoon rajapintojen kuvauksissa (API-portaalissa) olevat syötetarkistukset ja loogiset riippuvuustarkistukset, jotta rajapinnoille lähetetty syöte on mahdollisimman laadukasta ja vältytään tarpeettomilta muototarkistuksiin liittyviltä virhetilanteilta. Esimerkiksi ohjelmiston tulee tarkistaa syötteen päivämäärät, jotka eivät saa olla menneisyydessä. 

• Verohallinto seuraa rajapintojen käyttöä ja niissä esiintyviä virhetilanteita. Verohallinto voi olla yhteydessä ohjelmiston kehittäjään tai käyttäjään tarpeen mukaan virhetilanteiden selvittämiseksi. Ohjelmistotalo vastaa kehittäjien yhteystietojen oikeellisuudesta lähettämällä päivitetyn testauksen aloitusilmoituslomakkeen, mikäli tiedot muuttuvat. Mikäli ohjelmiston käyttäjällä on oma tuotantovarmenne, käyttäjä vastaa yhteystietojensa oikeellisuudesta tulorekisterin sähköisessä asiointipalvelussa. 

• Verohallinto voi sulkea varmenteen tai ohjelmiston pääsyn rajapintapalveluihin, mikäli epäilee väärinkäytöstä tai hyökkäystä.

• Rajapinnat estävät tahallisten tai tahattomien ylikuormitustilanteiden mahdollisesti aiheuttamien palvelunestohyökkäyksien onnistumisen rajoittamalla asiakkailta saapuvaa liikennevolyymia. Suositus on, että yhteen rajapintaan lähetetään yhdestä sovelluksesta maksimissaan 50 - 125 yhtäaikaista kutsua.

  • Rajapintoja kutsuvien ohjelmistojen tulee varautua ruuhkatilanteisiin, jolloin rajapinnat voivat vastata 429 – too many requests tai 403 forbidden. Ruuhkatilanteessa kutsujen yhtäaikaista määrää tulee vähentää ja yrittää myöhemmin uudelleen.

• Verohallinto ei takaa rajapintapalveluille 24/7/365 palvelua. Rajapinnoissa on säännöllisiä eri pituisia huoltokatkoja. Ohjelmiston on varauduttava katkotilanteisiin ja tarvittaessa säilytettävä lähetettävää materiaalia tai yritettävä kutsua määräajan jälkeen uudelleen. Huoltokatkoista tiedotetaan sivulla Huoltokatkot ja häiriöt Verohallinnon palveluissa. 

Rajapintojen tekniset linjaukset

Rajapintojen versiointi

• Versiointi tehdään rajapinta- tai API-tuotekohtaisesti. Rajapinnan versiointi perustuu juoksevaan numerointiin osoitteen lopussa, johon lisätään kirjain v ja versionumero, esimerkiksi https://api.vero.fi/Customer/IDs/ValidateTaxNumber/v3
• Versionumerointi aloitetaan numerosta 1 ja numeroa kasvatetaan aina kun rajapintaan tehdään rikkova muutos. Rikkova muutos on esimerkiksi sellainen, jossa muutetaan rajapinnan sanomarakennetta poistamalla kenttiä tai muuttamalla niiden tietotyyppiä. Rikkovan muutoksen vuoksi rajapinnan käyttäjien on myös tehtävä muutos. Huomioitavaa, että uusien kenttien lisääminen ei ole rikkova muutos.
• Verohallinto tukee pääsääntöisesti korkeintaan kahta eri versiota samasta rajapinnasta, nykyistä versiota ja edellistä. Edellisen version käyttäjien odotetaan siirtyvän uusimman version käyttöön tapauskohtaisen siirtymäajan puitteissa. Versioinnista tiedotetaan rajapintakohtaisesti API portaalin dokumentaatioissa.

Rajapintojen osoitteen rakenne

Rajapintojen osoitteiden (URL) rakenteessa pyritään seuraamaan Verohallinnon tietojärjestelmän toiminnallisten jaon mukaista rakennetta. Osoite on englannin kielellä ja se koostuu tuotantoympäristössä esimerkiksi seuraavista osista:

• Vero API domain: vero.fi/
• Kategoria: Customer/
• API-tuotenimi tai alikategoria: IDs/
• Rajapinnan toiminnon nimi: ValidateTaxNumber/
• Versionumero: v1

Testiympäristöissä osoitteessa on lisäksi ympäristön sekä testirajapinnan tunniste, esimerkiksi:

• Vero API domain: vero.fi/
• Testiympäristön tunniste: FIS/
• Kategoria: Customer/
• API-tuotenimi tai alikategoria: IDs/
• Testirajapinnan tunniste: Test/
• Rajapinnan toiminnon nimi: ValidateTaxNumber/
• Versionumero: v1

Ajantasaiset osoitteet on kuvattu API-portaalissa.

Header-tiedot

Vero API -rajapinnat edellyttävät headeria nimeltä ”vero-softwareid”, johon rajapinnan kutsujan on asetettava ohjelmistonsa yksilöllinen tunniste. Suositus on käyttää sovelluksen kehittäneen yrityksen y-tunnusta sekä yksilöllistä tunnistetta tai kuvausta.

Rajapinnat edellyttävät lisäksi "vero-softwarekey" -headeria, johon asetetaan ohjelmistokohtainen API-avain.  Header on dokumentoitu Vero API-portaalissa jokaisen rajapinnan kuvauksessa. API-avaimen saa rekisteröimällä ohjelmiston.

Verohallinto käyttää tarvittaessa tietoa tunnistaakseen ja ottaakseen yhteyttä ohjelmistokehittäjään.

Rajapintojen parametrit

Rajapinnoilta kysellään ja niille välitetään usein henkilötietoja ja merkitsevänä parametrina käytetään esimerkiksi henkilötunnuksia. Parametreja ei välitetä rajapintakutsujen osoitteissa (URL parametreina), koska ne usein jäävät eri palvelinten lokeille ja voisivat paljastaa salassa pidettävää henkilötietoa. Tämän vuoksi kaikki rajapintapalvelut käyttävät http:n POST metodia ja parametrit välitetään kutsun bodyn sisällä.

Tietotyypit rajapinnoissa

Tiedot välitetään rajapinnoissa pääsääntöisesti JSON-sanomina ja tietotyyppeinä käytetään yleisimpiä JSON-tietotyyppejä:

• string
• number
• Boolean
• null/empty
• object
• array

Tiedostot siirretään osana JSON sanomaa base64 enkoodattuina tai erikseen, jolloin sisällön tyyppinä on application/binary. Tekstikenttien sisältö tulee olla utf-8-enkoodattua.

Päivämäärät ja aikaleimat

Päivämäärät muotoillaan ISO 8601:n mukaisesti yyyy-MM-dd ja aikaleimat aikavyöhykkeen kera millisekunnin tarkkuudella yyyy-MM-ddThh:mi:ss.zzz+00:00. Esimerkiksi päivämäärä 2022-02-25  ja aikaleima 2022-02-25T14:59:43.397+02:00. Eri aikavyöhykkeillä lähetetyt aikaleimat muunnetaan Verohallinnossa käyttämään paikallista Suomen aikaa.

Http-paluukoodit

• Rajapintojen vastauksissa käytetään standardeja http-paluukoodeja. Vain 200 OK tarkoittaa kutsun suoriutumista onnistuneesti. Tyypillisesti rajapinnan paluuarvona lähetetään yksilöllinen tunniste sekä aikaleima, jotka toimivat Verohallinnon kuittauksena onnistuneesta lähetyksestä. Muissa tilanteissa kyse on tyypillisesti virheestä joko syötteessä tai pyynnön käsittelyssä. Lähetettyä aineistoa ei välttämättä käsitellä välittömästi verotusjärjestelmissä.
• Muut http-paluukoodit, kuten 400 tai 500 tarkoittavat, että lähetettyä sanomaa ei ole hyväksytty tai siihen ei pystytä vastaamaan esim. bad request sekä virhettä selventävä JSON sanoma, jossa virhekoodi sekä virheen selite. Kyse voi olla esimerkiksi lähetetyn sanoman rakenteen virheestä, syötteeseen liittyvästä tarkistusvirheestä, liiketoiminnan säännön tarkistusvirheestä, valtuuksien puuttumisesta, kuormitustilanteestä tai käyttökatkosta.
• Jos tuotantovarmenne on noudettu samana päivänä, kun kutsua yritetään, rajapinta saattaa palauttaa http 500 virheen kunnes varmenne on latautunut Vero API tuotantoympäristöön. Vero API rajapinnat vastaavat tuotantovarmenteella tehtyihin kutsuihin vasta, kun olemme noutaneet muodostetun varmenteen ja asentaneet sen ympäristöömme. Varmenteet noudetaan Vero API käyttöön tulorekisterin varmennepalvelusta. Pääsääntönä voidaan pitää sitä, että virka-aikana varmennepalvelussa (klo 8.00-16.15) muodostetut tuotantovarmenteet toimivat Vero API rajapintojen kutsuissa viimeistään seuraavana päivänä.