Siirry tuotantoon
Tuotannon rajapintojen käyttöönotto
Ohje on jaettu rajapintaa käyttävän organisaation ja ohjelmiston kehittäjän toimenpiteisiin.
Rajapintaa käyttävä organisaatio
Rajapintojen käyttäjäorganisaatiolta, ohjelmiston käyttäjältä, edellytetään tuotantovarmennetta. Tuotantovarmenne toimii käyttäjän tunnistetietona. Rajapintojen käyttäjä voi olla asiakas eli ilmoitusvelvollinen itse tai hänen valtuuttama osapuoli rajapintojen käyttöehtojen mukaisesti.
Ohjelmiston kehittäjä
Ohjelmiston kehittäjä rekisteröi ohjelmistonsa API-portaalissa ja valitsee sen käyttämät rajapinnat ennen tuotantokäytön aloittamista. Rekisteröity ohjelmisto saa API-avaimen. API-avain on ohjelmistokohtainen ja toimii ohjelmiston tunnisteena. API-avain ei ole tarkoitettu ohjelmiston käyttäjien hallittavaksi, vaan ohjelmiston kehittäjän tulee rakentaa sen käsittely ohjelmiston sisälle.
Ohjelmiston kehittäjä varmistaa ohjelmiston tuotantoyhteyden ja API-avaimen teknisen toimivuuden käyttämiään rajapintoja vasten. Varmistus tehdään omatoimisesti API-portaalissa julkaistua integraation verifiointiosoitetta vasten (URL Integraation verifiointi).
Integraation verifioinnin jälkeen ohjelmisto on tuotantovalmis.
Lue lisää ohjelmiston rekisteröinnistä
Tuotantovarmenteen hakeminen:
Tuotantovarmennetta hakevalla organisaatiolla tulee olla suora palvelusopimus rajapintapalveluiden käyttöehtojen mukaisen asiakkaan kanssa. Mikäli ohjelmistosi on tarkoitettu esimerkiksi tilitoimistojen tai muiden palveluntarjoajien käyttöön eikä suoraan ilmoitus- tai verovelvollisille, tulee käyttäjäorganisaatioiden hakea varmenne.
Hakemus tehdään tulorekisterin sähköisessä asiointipalvelussa.
- asiointipalvelussa valitaan yritys, jolle varmennetilaus tehdään (tuotantovarmennetta voi hakea ainoastaan varmennetta hakevan tahon nimenkirjoitusoikeudellinen henkilö)
- yrityksen sivuilta valitaan; asetukset > tekninen rajapinta
- tarkista onko Voimassa olevat oikeudet -kohdassa rajapinnan käyttötarkoituksena "Palkkatiedot, ilmoittaa maksamiaan palkkoja ja Palkkatiedot, ilmoittaa palkkoja toisen tahon puolesta" sekä kanavissa "Palkkatiedot - Web Service" mahdollisten muiden oikeuksien lisäksi
- jos käyttötarkoituksessa ei jo ole palkkatietojen ilmoittaminen ja kanavana Web Service, niin tulee tehdä korvaava hakemus, valitse Tee korvaava hakemus.
- valitse korvaavaan hakemukseen rajapinnan käyttötarkoitukseen nykyisten valintojen lisäksi "Palkkatiedot, ilmoittaa maksamiaan palkkoja ja Palkkatiedot, ilmoittaa palkkoja toisen tahon puolesta" sekä kanavaksi "Palkkatiedot - Web Service". Korvaava hakemus korvaa aikaisemmat valinnat, joten hakemuksen tulee sisältää kaikki organisaation käyttämät käyttötarkoitukset ja kanavat.
- rajapinnan oikeuden tarkistuksen jälkeen tee varsinainen varmennehakemus: varmenteet > hae uutta varmennetta
- tuotannon varmenteen tyypiksi tulee valita "Palkkatiedot - Web Service"
- tuotantovarmenteen käyttäjän on hyväksyttävä ja noudatettava Verohallinnon ja tulorekisterin rajapintapalveluiden käyttöehtoja (pdf)
- varmennehakemuksessa tulee ilmoittaa tekninen yhteyshenkilö. Tekninen yhteyshenkilö suorittaa varmenteen teknisen noutamisen varmennepalvelun rajapinnasta.
- varmennehakemus lähetetään Lähetä-painikkeella. Lähetys käynnistää varmenteen tilauksen
- tekniselle yhteyshenkilölle lähetetään turvasähköpostilla tarvittavat tiedot varmenteen noutamista varten sekä matkapuhelinnumeroon tekstiviestillä PIN-koodi turvasähköpostin avaamista varten. PIN-koodi lähetetään sen jälkeen, kun varmenteen hakemisen yhteydessä lähetetyn suojatun sähköpostin "Avaa viesti" -linkkiä on painettu. Varmenne on noudettava varmennepalvelun rajapinnasta 14 vrk sisällä hakemuksen tekemisestä.
- tuotantovarmenne noudetaan varmennepalvelun Web Service -rajapinnan tuotanto-osoitteesta: https://pkiws.vero.fi/2017/10/CertificateServices (TCP portti 443)
- kun varmenne saadaan noudetuksi varmennehakemuksessa ilmoitettu tekninen yhteyshenkilö vastaa varmenteen syöttämisestä ohjelmistoon. Ilman varmennetta Vero API rajapinta ei palauta käyttäjäorganisaation pyytämää aineistoa.
- 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ä.
Varmennepalvelusta voi lukea tarkemmin tulorekisterin omilta sivuilta:
Varmennepalvelu
Kysymyksiä ja vastauksia varmennepalvelusta
Kannattaa tutustua myös tulorekisterin tekemään ohjevideoon:
Näin käytät tulorekisteriä - Hae uutta varmennetta
Huomioita ohjelmistokehittäjille:
- Tuotantovarmennetta hakevalla organisaatiolla tulee olla suora palvelusopimus rajapintapalveluiden käyttöehtojen mukaisen asiakkaan kanssa. Mikäli ohjelmistosi on tarkoitettu esimerkiksi tilitoimistojen tai muiden palveluntarjoajien käyttöön eikä suoraan ilmoitus- tai verovelvollisille, tulee käyttäjäorganisaatioiden hakea varmenne.
- Varmenteen noudon jälkeen ohjelmistotalon tulee itse ohjata käyttäjäorganisaatioitaan siihen, miten varmenteiden käsittely kyseisen ohjelmiston osalta tapahtuu.
- Käyttäjäorganisaation varmenne tulee syöttää ohjelmiston sisään, koska aineistoa haettaessa varmenne toimii käyttäjäorganisaation sähköisenä allekirjoituksena.
- Verohallinto suosittelee tuotantovarmenteen muodostamisen sekä uusimisen toteuttamista osaksi varmenteita hyödyntävää ohjelmistoa.
Tuotantoympäristö
Vero API rajapintojen dokumentaatiot ja tuotantoympäristön URL:t löydät Vero API-portaalista