Tekniset ohjeet
Tässä osiossa kerrotaan Vero API -rajapintoihin liittyvistä yleisistä teknisistä linjauksista. Tämä osio on hyödyllistä lukea erityisesti ohjelmointikehittäjälle, joka on aloittamassa Vero API -rajapintojen integraation kehittämisen ja käytön ensimmäistä kertaa. Rajapintojen omat tarkemmat tekniset kuvaukset sekä ohjeet on kerrottu API-portaalin dokumentaatioissa.
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-softwarekey
Kaikki rajapinnat edellyttävät "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.
Vero-authorizationtoken
Headeria käytetään, mikäli rajapinta edellyttää Suomi.fi-valtuutta, kun asioidaan toisen asiakkaan puolesta. Suomi.fi valtuus-tokenit tulee noutaa GetToken-rajapinnalla käsiteltävälle asiakasjoukolle. Headeriin asetetaan asiakaskohtainen token, joka täsmää kutsussa käsiteltävään yksittäiseen asiakkaaseen.
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ä.