Puolesta asiointi Vero API -rajapinnoissa

Vero API -rajapinnoilla on mahdollista ilmoittaa tai kysellä tietoja oman organisaation puolesta tai jonkun toisen organisaation puolesta valtuutettuna. Jos rajapintojen käyttäjä asioi oman organisaation asioissa, erillistä Suomi.fi-valtuutta rajapintojen käyttämiseen ei tarvita. Sen sijaan, jos rajapintojen käyttäjä asioi toisen organisaation puolesta, voi käyttäjä tarvita erillisen Suomi.fi-valtuuden. Suomi.fi-valtuuden tarve on erikseen kerrottu aina kyseisen rajapinnan API-portaalin dokumentaatiossa.

Vero API -rajapinnat hyödyntävät Digi- ja Väestötietoviraston (DVV) tarjoamaa Suomi.fi-valtuuspalvelua, jonka kautta henkilöt ja yritykset voivat valtuuttaa toisia henkilöitä tai yrityksiä asioimaan heidän puolestaan eri viranomaisasioissa, kuten veroasioiden hoitamisessa. Suomi.fi-valtuuksia voi antaa ja pyytää DVV:n suomi.fi palvelussa. Lisätietoa veroasioinnin valtuuksista ja valtuuttamisesta löydät täältä Näin valtuutat - vero.fi.

Alla on käyttötapausesimerkkejä, miten asioiminen voi tapahtua joko oman organisaation puolesta tai toisen organisaation puolesta valtuutettuna.

Esimerkki 1: Tilitoimistolla on käytössään kirjanpito- ja palkanlaskentasovellus, jossa on käytössä kirjeiden kysely API rajapinta. Tilitoimisto käyttää rajapintaa omien veroasioidensa hoitamiseen ja kyselee rajapinnalla kirjeitä, jotka ovat tulleet Verohallinnolta vain tilitoimistolle itselleen. Tilitoimisto asioi tässä tapauksessa oman organisaation asioissa eikä se hoida muiden yritysten veroasioita kyseisellä rajapinnalla. Kirjeitä ei siis kysellä muiden organisaatioiden puolesta eikä tilitoimiston tarvitse erikseen hakea Suomi.fi valtuutta rajapinnan käyttämiseen.

Esimerkki 2: Tilitoimistolla on käytössään kirjanpito- ja palkanlaskentasovellus, jossa on käytössä kirjeiden kysely API rajapinta. Tilitoimisto hoitaa toisten yritysten vero- ja kirjanpitoasioita ja se käyttää kyseistä rajapintaa apuna tässä toiminnassa. Tilitoimisto kyselee rajapinnalla yritysasiakkaidensa kirjeitä, jotka ovat saapuneet Verohallinnolta. Tilitoimisto pystyy kirjeiden hakemisen jälkeen reagoimaan niihin sopivalla tavalla. Tilitoimisto asioi tässä tapauksessa toisen organisaation puolesta ja se tarvitsee oikean Suomi.fi valtuuden rajapinnan käyttämiseen.

Suomi.fi valtuus-token

Rajapinnat ovat tarkistaneet Suomi.fi-asiointivaltuuden jokaisen rajapintakutsun yhteydessä. Jokainen tarkastus on kestänyt 300 - 500 ms ja rajapintakutsujen määrän kasvaessa tämä ratkaisu ei ole kestävä. Suuret määrät valtuustarkistuksia aiheuttaa hitautta rajapintojen käytössä. Jatkossa Suomi.fi-asiointivaltuus varmistetaan Suomi.fi valtuus-tokenilla, jonka rajapintoja käyttävä järjestelmä hakee etukäteen kaikille asiointitapahtumassa tarvittaville asiakkaille.

Rajapintakäyttäjän on noudettava Suomi.fi-valtuus GetToken-rajapinnalla ennen kutsujen tekemistä niihin rajapintoihin, jotka edellyttävät Suomi.fi-valtuutta. GetToken-rajapinta palauttaa valtuus-tokenin.

• Valtuus-token on tekninen allekirjoitettu tietorakenne, joka pitää sisällään rajapintojen käyttäjälle myönnetyt Suomi.fi-valtuudet. Tekninen tietorakenne on toteutettu JSON Web Token -mallin mukaisesti. Valtuus-token antaa oikeuden asioida toisen organisaation puolesta 60 minuutin ajan tokenin luontihetkestä lähtien.

Valtuus-token ratkaisu

Suomi.fi valtuus-tokenit haetaan kaikille asiakkaille, joiden puolesta rajapinta-asiointia suoritetaan seuraavan tunnin aikana, yhdellä GetToken-rajapintakutsulla. Valtuus-tokenit saadaan rajapinnasta vastauksena jokaiselle asiakkaalle, johon kutsujalla on Suomi.fi asiointivaltuus. Asiakaskohtainen valtuus-token asetetaan varsinaisen Vero API-kutsun headeriin vero-authorizationtoken. Valtuus-tokenin käyttö nopeuttaa Vero APIn vasteaikaa 300 - 500 ms per kutsu ja vähentää kuormaa mm. DVV:n suuntaan. Vero API GetToken-rajapinnan avulla kutsuva järjestelmä voi tarkistaa asiointivaltuuden olemassaolon ennen muiden rajapintakutsujen tekemistä.

Valtuus-tokenin käyttö antaa seuraavia hyötyjä käyttäjälle:

• Tekee rajapintojen käytöstä tehokkaampaa, koska jokaisessa kutsussa ei tarvitse suorittaa valtuustarkistusta erikseen DVV:ltä.
• Lisää Vero API rajapintojen käyttövarmuutta sekä palvelun laatua, koska ylimääräinen sanomaliikenne DVV:n suuntaan vähenee, jolloin kaikki rajapinnat toimivat nopeammin.
• Tokenin käyttö myös lyhentää muiden rajapintojen kutsujen prosessointi- ja vasteaikoja.
• Valtuus-tokenia voi käyttää myös tarkistamaan kyseisen hetken voimassa olevat Suomi.fi valtuudet asiakaskohtaisesti. Tiedot valtuuksista haetaan DVV:n valtuuspalvelusta. Kaikki voimassa olevat valtuudet palautetaan käyttäjälle silloin, kun uusi token haetaan.

Suomi.fi valtuus-tokenin käyttö tulee pakolliseksi 1.5.2024 kaikissa Vero API rajapinnoissa, joissa toisen puolesta asiointi edellyttää Suomi.fi-valtuutta. Valtuus-token tulee korvaamaan valtuuksien tarkistamisen suoraan Digi- ja Väestötietoviraston valtuuspalvelusta jokaisen rajapintakutsun yhteydessä.

Valtuus-tokenin pakollisuus ei koske rajapintoja, joissa Suomi.fi valtuutta ei tälläkään hetkellä edellytetä. Muutos ei koske myöskään käyttötilanteita, jossa rajapinnan käyttäjä käsittelee omia tietojaan. Jos rajapinnan käyttö edellyttää Suomi.fi valtuutta, niin se on kerrottu rajapinnan dokumentaatiossa. Dokumentaatiot löytyvät Vero API portaalista. Valtuus-token rajapinta on julkaistu tuotannossa 31.8.2023 ja sen käyttöönotto on ollut tähän mennessä vapaaehtoista.

Suomi.fi valtuuksia tarvitaan tällä hetkellä seuraavissa Vero API rajapinnoissa:

• Kirjeet ja päätökset-rajapinnat
• Roolirekisteröintitietojen päivitys
• Toimialan ja tilikausien kysely
• Verokausitietojen kysely
• Saldotietojen kysely
• Tapahtumahaku
• Autoverotuksen päätösrajapinnat ja ilmoituksen tilan kyselyrajapinnat
• EMCS-rajapinnat
• Kotitalousvähennystietojen ilmoittaminen
• Eläke- ja etuustietojen ilmoittaminen sekä eläkkeiden ja etuuksien ennakonpidätystiedot maksajille -kysely
• Arvonlisäveroveron ja yhteenvetoilmoituksen rajapinnat
• Yhteisöverotuksen rajapinnat (ennakkovero, voitonjako, osakkeen arvotiedot)

Valtuus-tokenin käytön vaiheet:

1. Määritä ja kerää luettelo asiakkaista, joita käsitellään sovelluksessasi.
2. Hae valtuus-tokenit kaikille tarvittaville asiakkaille yhdellä kertaa lähettämällä GetToken kutsu, jossa on kaikkien tarvittavien asiakkaiden tunnukset tai hae tokenit 3000 asiakkaan erissä saadaksesi parhaimman nopeushyödyn GetToken API:sta.
3. GetToken rajapinnan vastaus pitää sisällään ainoastaan tokenit niillä asiakkaille, joiden asioiden hoitoon kutsujalla on valtuudet voimassa kutsun hetkellä.
4. Hallinnoi tiettyihin asiakkaisiin liittyviä tokeneita sekä asiakastunnuksia ja aseta oikea token Vero-Authorizationtoken headeriin jokaiseen Vero API kutsuun, joka vaatii Suomi.fi valtuuden käyttöä.
5. Suorita kaikki Vero API kutsut 60 minuutin sisällä, kun token on vielä aktiivinen. Kun tokenit vanhenevat, kutsu GetToken rajapintaa uudestaan ja hae uudet tokenit tilalle.