Tekniska anvisningar

I det här avsnittet beskrivs de allmänna tekniska riktlinjerna för Vero API-gränssnitten. Läs avsnittet om du är programutvecklare och för första gången börjar använda och utveckla Vero API-gränssnittsintegrationer. Närmare tekniska beskrivningar och anvisningar om varje gränssnitt finns i dokumentationen i API-portalen.

Versionering av gränssnitt

Versioneringen görs gränssnitts- eller API-produktspecifikt. Versioneringen av gränssnitten baserar sig på ett löpande nummer i slutet av adressen till vilket bokstaven v och versionsnumret läggs, till exempel https://api.vero.fi/Customer/IDs/ValidateTaxNumber/v3

Versionsnumreringen startar från 1 och numret växer alltid vid en ändring som är disruptiv (söndrande). En disruptiv ändring är exempelvis en sådan där meddelandets struktur i gränssnittet ändras genom att fält tas bort eller deras datatyp ändras. En disruptiv ändring leder till att också användarna måste göra en ändring. Observera att tillägg av nya fält inte är en disruptiv ändring.

Skatteförvaltningen stöder i regel högst två olika versioner av samma gränssnitt, den nuvarande och föregående versionen. Användare som använder den föregående versionen förväntas övergå till den nyaste versionen inom en övergångstid som varierar från fall till fall. Vi meddelar om versioneringen per gränssnitt i API-portalens dokumentation.

Gränssnittsadressens struktur

Strävan i gränssnittsadressernas (URL) struktur är att följa den operativa struktur enligt vilken Skatteförvaltningens datasystem är indelad i olika delar. Adressen är på engelska och består i produktionsmiljön till exempel av följande delar:

Vero API domain: api.vero.fi/
Kategori: Customer/
API-produktnamn eller underkategori: IDs/
Namnet på gränssnittsfunktionen: ValidateTaxNumber/
Versionsnummer: v1

Adressen till testmiljön har därtill en miljö- och testgränssnittsidentifierare, till exempel:

Vero API domain: pintatesti.vero.fi/
Testmiljöidentifierare: FIS/
Kategori: Customer/
API-produktnamn eller underkategori: IDs/
Testgränssnittsidentifierare: Test/
Namnet på gränssnittsfunktionen: ValidateTaxNumber/
Versionsnummer: v1

De uppdaterade adresserna beskrivs i API-portalen.

Header-uppgifter

Vero-softwarekey

En programvaruspecifik API-nyckel måste placeras i vero-softwarekey-headern i varje gränssnitt. I API-portalen har headern dokumenterats i beskrivningen av varje gränssnitt. API-nyckeln fås genom att registrera programvaran. Skatteförvaltningen använder vid behov uppgiften för att identifiera och kontakta utvecklaren av programvaran.

Vero-authorizationtoken

Headern används om gränssnittet kräver användning av Suomi.fi-fullmakt när man utför ärenden på någon annan kunds vägnar. Suomi.fi-fullmaktstoken måste hämtas för alla de kunder som behandlas i GetToken-gränssnittet. En kundspecifik token som stämmer överens med den enskilda kund som anropet gäller ställs in i headern.

Gränssnittsparametrar

Det frågas efter och förmedlas ofta personuppgifter via gränssnitten och som betydande parametrar används till exempel personbeteckningar. Parametrarna förmedlas inte via gränssnittsanropsadresserna (som URL-parametrar) eftersom de ofta lagras i olika serverloggar och kan avslöja hemliga personuppgifter. Därför använder alla gränssnittstjänster http:s POST-metoden och parametrarna förmedlas inom anropets body.

Datatyperna i gränssnitten

Uppgifterna förmedlas i gränssnitten i regel som JSON-meddelanden och de vanligaste JSON-uppgiftstyperna används som datatyper:

string
number
Boolean
null/empty
object
array

Filerna överförs som en del av JSON-meddelandet med base64-kryptering eller separat, i vilket fall innehållstypen är application/binary. Innehållet i textfälten ska vara utf-8-krypterat.

Datum och tidsstämplar

Datumformen är enligt ISO 8601 yyyy-MM-dd och tidsstämplarna inklusive tidszon med en millisekunds noggrannhet yyyy-MM-ddThh:mi:ss.zzz+00:00. Till exempel datumet 2022-02-25 och tidsstämpeln 2022-02-25T14:59:43.397+02:00. Tidsstämplar skickade från olika tidszoner omvandlas på Skatteförvaltningen till lokal finsk tid.

Http-returkoder

I gränssnittssvaren används standardiserade http-returkoder. Endast 200 OK innebär att anropet har lyckats. En individuell identifierare och tidsstämpel skickas typiskt som returvärde för gränssnittet. Dessa fungerar som en bekräftelse från Skatteförvaltningen på att sändningen lyckats. I andra situationer är det vanligen fråga om ett fel antingen i indata eller behandlingen av begäran. Det skickade materialet behandlas nödvändigtvis inte genast i beskattningssystemen.
Andra http-returkoder, såsom 400 eller 500, innebär att det skickade meddelandet inte har godkänts eller att det inte kan besvaras, till exempel bad request och har ett förtydligande JSON-meddelande med felkod och beskrivning av felet. Det kan vara fråga om ett strukturfel i det skickade meddelandet eller ett kontrollfel som hänför sig till indata, ett kontrollfel i affärsverksamhetsregeln, behörigheter som saknas, en överbelastningssituation eller ett driftsavbrott.
Om produktionscertifikatet har hämtats samma dag som anropsförsöket görs kan gränssnittet returnera ett http 500-fel tills certifikatet har laddats till produktionsmiljön för Vero API. Vero API-gränssnitten svarar på anrop gjorda med produktionscertifikatet först när vi har hämtat det skapade certifikatet och installerat det i vår miljö. Certifikat hämtas från inkomstregistrets certifikattjänst för att användas i Vero API. Huvudregeln är att de produktionscertifikat som skapats i certifikattjänsten under tjänstetid (kl. 8.00–16.15) fungerar senast i Vero API-gränssnittens anrop följande dag.