Allmän beskrivning av Vero API

Allmänna anvisningar för användare av gränssnitten Vero API

• Användningen av Vero-API gränssnitt förutsätter client-certifikat. Som autentiseringsmetod används client certificate authentication -metoden, som betyder att client-certifikatet kontrolleras i SSL-handskakningen då den skyddade anslutningen bildas. Detta betyder att anroparens certifikat och till den tillhörande privata nyckeln krävs. Skatteförvaltningen ger inte noggrannare information om hur certifikatet kopplas till anropet, eftersom metoden beror på användarens system. Mera information om autentiseringsmetoden och dess användning hittas på de flesta sökmotorer med nyckelorden "client certificate authentication."
• Till de program som använder gränssnitt bygger programvaruleverantörerna kontroller av indata och logiska bundenhetsundersökningar enligt beskrivningarna av gränssnitten (i API-portalen), så att indata som skickas till gränssnitten ska uppnå så hög kvalitet som möjligt och för att undvika onödiga felsituationer vid kontrollen av formen. Programmet ska till exempel kontrollera datum i indata och det får inte infalla i det förflutna.
• Programvaruleverantörer ska testa integrationen till Vero API-testgränssnitten genom att använda ett testcertifikat. Testscenarierna ska innehålla bland annat typiska användningssituationer, godkända indata som gränssnittet returnerar, behandling av felmeddelanden samt förberedelser både för driftsavbrott och oväntade fel.
• Ett produktionstillstånd för ett specifikt gränssnitt förutsätter att testscenarier genomförs i portalen API. Testscenarierna utförs genom att anropa gränssnitten i miljön för verifiering av integrationen med produktionscertifikatet.
• Skatteförvaltningen följer användningen av gränssnitten och felsituationer som förekommer i dem. Skatteförvaltningen kan för att utreda felsituationer vid behov kontakta programutvecklaren eller användaren.
• En ändamålsenlig övervakning av användningen av gränssnitten Vero API ska byggas i programmet så att felsituationer kan upptäckas och programvaruhuset eller användaren av programmet kan reagera på dem. Vanliga fel är att giltighetstiden för ett certifikat gått ut, en Suomi.fi-fullmakt saknas, felaktig input eller problem med förbindelsen.
• Programvaruhuset ansvarar för att uppgifterna i programmet och utvecklarnas kontaktuppgifter är rätt i API-portalen. Programvaruhuset ska dessutom också upprätthålla kontaktpersonerna som hänför sig till certifikaten. Kontaktpersonerna för ett testcertifikat upprätthålls genom att skicka en uppdaterad anmälan om inledningen av testningen med nya uppgifter. Uppgifterna om produktionscertifikatet ska upprätthållas i inkomstregistrets e-tjänst.
• Skatteförvaltningen kan stänga certifikatet eller tillgången till gränssnittstjänsten för programmet om det finns misstankar om missbruk eller cyberattack.
• Gränssnitten hindrar att eventuella avsiktliga eller oavsiktliga överbelastningsattacker lyckas genom att begränsa den inkommande volymen av datakommunikation från kunden. Rekommendationen är att högst 50 - 125 samtidiga anrop skickas från ett program till ett gränssnitt.
  • Program som anropar gränssnitt ska vara beredda på överbelastningar. I dessa situationer kan gränssnitten svara 429 – too many requests eller 403 forbidden. Vid överbelastningar ska antalet samtidiga anrop minskas och ett nytt försök göras senare.
• Skatteförvaltningen garanterar inte service 24/7/365 för gränssnittstjänsterna. Gränssnitten har regelbundet olika långa driftsavbrott. Programmet ska beredas på avbrott och på att vid behov spara materialet som ska skickas eller på nytt göra ett anrop efter en utsatt tid. Skatteförvaltningen meddelar om driftsavbrott på sidan Serviceavbrott och störningar - vero.fi.

Tekniska riktlinjer för gränssnitt

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

Tjänsterna Vero API förutsätter en header med namnet ”vero-softwareid” i vilken anroparen av gränssnittet ska ange den individuella identifieraren för sitt program. Rekommendationen är att använda FO-numret och en individuell identifierare eller beskrivning för det företag som har utvecklat programmet. Skatteförvaltningen använder uppgiften vid behov för att identifiera och kontakta utvecklaren av programvaran.

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.