Verohallinnon nimissä on lähetetty huijausviestejä. Lue lisää huijauksista.

Suomi.fi valtuuden käyttö Vero API rajapinnoissa

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 8 tunnin 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ä.

Huomio alkaa.

Rajapinnan dokumentaatio

Lisätietoa rajapinnasta, sanoman skeema sekä parametrien tarkemmat kuvaukset löytyvät Vero API-portaalista:

Huomio päättyy

Suomi.fi valtuus-tokenin käyttö on pakollista kaikissa Vero API rajapinnoissa, joissa toisen puolesta asiointi edellyttää Suomi.fi-valtuutta. 

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. 

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
  • Valmisteverot
  • 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 8 tunnin sisällä, kun token on vielä aktiivinen. Kun tokenit vanhenevat, kutsu GetToken rajapintaa uudestaan ja hae uudet tokenit tilalle.
Sivu on viimeksi päivitetty 6.3.2026