Registrering av programvara och godkännandeförfarande
Syftet med registreringen av programvarorna är att förbättra användarupplevelsen av gränssnitten och integrationernas kvalitet genom ett formbundet ibruktagningsförfarande och en riktad styrning.
Programvaruutvecklarens registrering
I den organisation som utvecklar programvaran kan en eller flera utvecklare registrera sig som användare av API-portalen. Registreringen i portalen sker med användarens e-postadress och lösenord. I portalen används inte Suomi.fi-identifikation och den organisationsuppgift som utvecklaren har lämnat kontrolleras inte. I portalen behandlas endast de uppgifter om programvaran som utvecklarna har lämnat in.
I API-portalen hör utvecklarna till olika utvecklarteam till vilka de med e-postadress kan bjuda in andra utvecklare. Syftet med teamstrukturen är att minska utmaningarna med att få möjlighet att administrera data i programvaran, bland annat med anledning av byte av personal. Alla utvecklare kan skapa team och administrera teammedlemmarna själva. Utvecklarna har sinsemellan lika omfattande användarrättigheter, vilket ska beaktas vid inbjudningar av nya medlemmar.
Registrering av programvaror
I API-portalen registreras programvaran under det utvecklarteam som är ansvarigt för utvecklingen av programvaran. Till de uppgifter som ska lämnas om programvaran hör namn, en kort beskrivning av användningsfallet, administratör och kontaktperson.
Efter registreringen väljs de gränssnitt som programvaran använder. Sedan kan de valda gränssnitten användas med en programvaruspecifik API-nyckel.
Programvaruutvecklaren är ansvarig för att administrera data i programvaran, bland annat data om användning av gränssnitt.
Skatteförvaltningen följer upp användningen av gränssnitten i programvarorna och kan ta bort oanvända programvaror från API-portalen. Kontaktpersonen för programvaran informeras om borttagandet.
API-nyckel
- API-nyckeln visas i uppgifterna om programvaran i API-portalen och vid behov kan fler API-nycklar skapas. API-nyckeln är avsedd att byggas in i programvaran, inte att administreras av användare.
- En programvara har i princip en API-nyckel. Nyckeln är inte den huvudsakliga mekanismen för att hantera åtkomsten till Skatteförvaltningens gränssnitt.
- API-nyckeln är endast avsedd för kännedom i den organisation som har utvecklat programvaran.
- En programvaruspecifik API-nyckel ställs in i vero-softwarekey-headern och ska ingå i varje gränssnittsanrop. I API-portalen har detta dokumenterats i beskrivningen av varje gränssnitt.
- En API-nyckel krävs i testmiljön, men innehållet i nyckeln kontrolleras inte och nyckeln begränsar inte åtkomsten till vissa gränssnitt.
Godkännandeförfarande för produktionsanvändning av en programvara
Från och med den 20 november 2023 förutsätter produktionsanvändningen av gränssnitten en godkännandetestning av programmen. Godkännandetestningen av ett program ska själv genomföras i API-portalen. Den som genomför testningen ska ha ett produktionscertifikat. I förfarandet vid godkännandetestningen hämtas specifika testscenarior för gränssnitten till API-portalen. Syftet med dem är att säkerställa en smidig integration, minska de felsituationer som förekommer i användningen av gränssnitten och förtydliga processen när gränssnitten tas i bruk.
Specifika testscenarior för gränssnitten utförs genom att anropa gränssnittets verifieringsadress enligt beskrivningen. Varje gränssnitt har minst ett grundläggande scenario där programmet ska lämna ett lyckat anrop som kommer igenom gränssnittets affärsverksamhetsregler, inputkontroller och kontrollen av fel. Gränssnittet kan också ha flera testscenarior. Användaren ska då komma igenom varje testscenario för att det ska vara möjligt att bevilja ett produktionstillstånd. Efter en lyckad testning får programmet automatiskt ett produktionstillstånd.
Att observera om produktionstillståndet:
- Alla efter den 20 november 2023 registrerade nya program ska genomföra godkännandetestningen i fråga om alla gränssnitt.
- Godkännandetestningen gäller inte program som registreras före den 20 november 2023 och de gränssnitt som dessa redan använder. Dessa program kan fortsätta använda gränssnitten utan avbrott.
- Godkännandetestningen ska göras när programmet tar i bruk nya gränssnitt. Detta gäller alla registrerade program. Ett registrerat program använder för tillfället exempelvis gränssnittet för förfrågan om förskottsinnehållningsuppgifter och tar i bruk gränssnittet för anmälan om hushållsavdrag efter den 20 november. Godkännandetestningen ska genomföras i fråga om gränssnittet för anmälan om hushållsavdrag.
- Vi rekommenderar också att testscenarior genomförs beträffande befintliga program. Befintliga produktionstillstånd till gränssnitt avlägsnas inte även om testscenariorna inte går igenom.
- Testscenariorna kan genomföras på nytt även om ett produktionstillstånd redan har beviljats. Detta kan utnyttjas exempelvis för att testa en ny version av ett program i API-portalen.
- Programvaruhuset behöver inte kontakta Skatteförvaltningen separat för att inleda eller slutföra en testning. I problem- eller felsituationer kan användaren ta kontakt med hjälp av observationsblanketten.
Närmare anvisningar om att genomföra testscenarior:
- Gränssnittens adresser (verifiering av URL Integration) som används i testscenarior finns i portalen Vero API
- Anrop som har skickas till en verifieringsadress behandlas inte i beskattningssystemet, och gränssnittens svar är samma statiska svar som svaren från de tidigare testmiljöerna.
- För att genomföra testscenarior räcker det till exempel med ett sådant lyckat anrop med giltigt datainnehåll som verifieringsgränssnittet besvarar med returkoden HTTP 200
- I miljön för verifiering av integrationen utförs ingen mer omfattande testning, utan miljön är avsedd för godkännandetestning av färdiga program