Att sköta ärenden för någon annans räkning via Vero API-gränssnitt
Om du har en fullmakt kan du anmäla uppgifter eller lämna en förfrågan om dem för din egen eller någon annan organisations räkning via ett Vero API-gränssnitt. Om gränssnittsanvändaren sköter ärenden för den egna organisationens räkning behövs inte någon separat Suomi.fi-fullmakt för att använda gränssnitten. Om du däremot använder gränssnittet för att sköta ärenden för någon annan organisations räkning, kan du behöva en separat Suomi.fi-fullmakt. Behovet av en Suomi.fi-fullmakt anges alltid seprat i dokumentationen i API-portalen för gränssnittet i fråga.
Vero API-gränssnitten använder Suomi.fi-fullmaktstjänsten som tillhandahålls av Myndigheten för digitalisering och befolkningsdata (MDB). Via fullmaktsjänsten kan personer och företag bevilja andra personer eller företag fullmakt att sköta ärenden för deras räkning i olika myndighetsärenden, såsom skatteärenden. Suomi.fi-fullmakter kan begäras och beviljas i MDB:s tjänst Suomi.fi. Läs mer om fullmakter att sköta skatteärenden här Så här ger du fullmakt - vero.fi.
Nedan finns exempel på användningsfall: Hur ärenden kan skötas antingen för din organisations eller någon annan organisations räkning.
Exempel 1: Det är fråga om en bokföringsbyrå som har ett bokförings- och löneprogram som använder gränssnittet API för förfrågan om brev. Bokföringsbyrån använder gränssnittet för att sköta sina egna skatteärenden och för att skicka förfrågningar om brev som kommit från Skatteförvaltningen endast till bokföringsbyrån själv. I detta fall sköter bokföringsbyrån den egna organisationens ärenden och inte andra företags skatteärenden via gränssnittet i fråga. Förfrågningar om brev skickas alltså inte för andra organisationers räkning och då behöver bokföringsbyrån inte separat ansöka om Suomi.fi-fullmakter för att få använda gränssnittet.
Exempel 2: Det är fråga om en bokföringsbyrå som har ett bokförings- och löneprogram som använder gränssnittet API för förfrågan om brev. Bokföringsbyrån sköter skatte- och bokföringsärenden för andra företag och använder gränssnittet i fråga som hjälp i detta syfte. Bokföringsbyrån använder gränssnittet till att skicka förfrågningar om de brev som bokföringsbyråns företagskunder fått från Skatteförvaltningen. Bokföringsbyrån kan efter att ha hämtat breven reagera på dem på det sätt som behövs. Bokföringsbyrån sköter i detta fall ärenden för någon annan organisations räkning och behöver en Suomi.fi-fullmakt för att använda gränssnittet.
Suomi.fi-fullmaktstoken
Gränssnitten har kontrollerat Suomi.fi-ärendefullmakten i samband med varje gränssnittsanrop. Varje kontroll har tagit 300–500 ms. och när antalet gränssnittsanrop ökar är detta inte hållbart. Ett stort antal fullmaktskontroller orsakar tröghet i användningen av gränssnitt. I fortsättningen kontrolleras Suomi.fi-ärendefullmakten med en Suomi.fi-fullmaktstoken som det system som använder gränssnitt hämtar på förhand för de kunder som behövs i ärendehanteringen.
Användaren av gränssnittet ska hämta Suomi.fi-fullmakten med GetToken-gränssnittet innan hen anropar de gränssnitt som kräver en Suomi.fi-fullmakt. GetToken-gränssnittet skickar fullmaktstoken i retur.
- Fullmaktstoken är en undertecknad teknisk datastruktur som innehåller de Suomi.fi-fullmakter som beviljats gränssnittsanvändaren. Den tekniska datastrukturen har implementerats enligt mallen JSON Web Token. Fullmaktstoken ger rätt att uträtta ärenden för en annan organisations räkning i 60 minuter från och med den tidpunkt då den skapats.
Avgörandet fullmaktstoken
Suomi.fi-fullmaktstoken hämtas för alla de kunder på vilkas vägnar gränssnittsärendehantering utförs inom följande timme med ett gränssnittsanrop Vero API GetToken. Fullmaktstoken fås som svar från gränssnittet för varje kund vars Suomi.fi-ärendefullmakt anroparen har. Den egna fullmaktstoken för varje kund ställs i headern vero-autorizationtoken i det egentliga Vero API-anropet. Användningen av fullmaktstoken påskyndar svarstiden för Vero API med 300–500 ms. per anrop och minskar belastningen bland annat för Myndigheten för digitalisering och befolkningsdata (MDB). Med hjälp av gränssnittet Vero API GetToken kan det anropande systemet kontrollera att ärendefullmakten existerar innan andra gränssnittsanrop görs.
Nyttan av användningen av fullmaktstoken för användaren:
- Användningen av gränssnitten blir effektivare eftersom ingen separat fullmaktskontroll behöver göras hos MDB i samband med varje anrop.
- Driftssäkerheten och tjänstens kvalitet ökar i gränssnitten Vero API eftersom den extra meddelandetrafiken till MDB minskar och då fungerar också alla gränssnitt snabbare.
- Användningen av token avkortar också process- och svarstiderna för anropen i andra gränssnitt.
- Fullmaktstoken kan också användas för att kontrollera gällande Suomi.fi-fullmakter per kund vid tidpunkten i fråga. Uppgifterna om fullmakterna hämtas från fullmaktstjänsten hos MDB. Alla gällande fullmakter returneras till användaren när en ny token hämtas.
Användningen av Suomi.fi-fullmaktstoken blir obligatorisk den 1 maj 2024 i alla de Vero API-gränssnitt där ärendehantering på någon annans vägnar förutsätter en Suomi.fi-fullmakt. Fullmaktstoken kommer att ersätta kontrollen av fullmakterna direkt från fullmaktstjänsten hos MDB i samband med varje gränssnittsanrop.
Att fullmaktstoken blir obligatorisk gäller inte de gränssnitt där ingen Suomi.fi-fullmakt förutsätts för tillfället. Ändringen gäller inte heller i situationer där användaren av gränssnittet behandlar sina egna uppgifter. Om användningen av gränssnittet förutsätter en Suomi.fi-fullmakt anges detta i dokumentationen av gränssnittet. Dokumentationen av gränssnitten finns på portalen Vero API. Gränssnittet fullmaktstoken har publicerats i produktionen den 31 augusti 2023 och hittills har det varit frivilligt att ta i bruk det.
Suomi.fi-fullmakter behövs i följande Vero API-gränssnitt för tillfället:
- Gränssnitten för brev och beslut
- Uppdatering av uppgifter om rollregistrering
- Förfrågan om bransch och räkenskapsperiod
- Förfrågan om uppgifter om skatteperiod
- Förfrågan om saldouppgifter
- Transaktionssökning
- Gränssnitt för bilbeskattningsbeslut och för förfrågan om deklarationsstatus
- EMCS-gränssnitt
- Anmälan om hushållsavdragsuppgifter
- Anmälan om pensions- och förmånsuppgifter samt förfrågan om förskottsinnehållningsuppgifter till utbetalare om pensioner och förmåner
- Gränssnitt för moms och sammandragsdeklaration
- Gränssnitt för samfundsbeskattning (förskottsskatt, vinstutdelning, värdeuppgifter om aktie)
Faser i användningen av fullmaktstoken:
- Fastställ och samla ihop en förteckning över de kunder som du behandlar i programmet.
- Hämta på en gång fullmaktstoken för alla de kunder som behövs genom att skicka anropet GetToken med alla de kunders beteckningar som behövs eller hämta token satsvis, 3 000 kunder åt gången, för att få den bästa nyttan av hastigheten i GetToken API.
- Svaret från gränssnittet GetToken ska endast innehålla token för de kunder vars fullmakter den som anropar har i kraft vid tidpunkten för anropet.
- Administrera token och kundbeteckningar som anknyter till vissa kunder och ställ rätt token i headern Vero-Authorizationtoken i varje Vero API anrop som kräver användning av Suomi.fi-fullmakter.
- Genomför alla Vero API-anrop inom 60 minuter när token ännu är aktiv. När giltighetstiden för token går ut ska du anropa GetToken-gränssnittet på nytt och hämta nya ersättande token.