Notifikationstjänst (Notification Service)

Tjänstens syfte

Notifikationstjänsten är en tilläggstjänst vars syfte är att effektivera användningen av andra Vero API-gränssnitt. I och med tjänsten är det möjligt att beställa och ta emot fastställda notifikationstyper från Skatteförvaltningen. Notifikationen är en enkel indikator som berättar att kunden har någon händelse som hänför sig till beskattningen. Exempelvis en kund som valts i beställningen har någon beskattningshändelse och utifrån den skapas en notifikation som användaren av Vero API-gränssnittet ska reagera på.

Notifikationen innehåller meddelandetypen och nyckeluppgiften med vilken det egentliga datainnehållet i notifikationen kan hämtas med ett lämpligt gränssnitt. Notifikationerna har inget status och ansvaret för vilka meddelanden som redan har behandlats och hur de mottagna notifikationerna reagerats på ligger på programmen som använder notifikationstjänsten.

Den nuvarande notifikationstjänsten (Notification Service)

Notifikationstjänsten har planerats för allmänt bruk och för att utvidgas till olika användningsändamål med hjälp av nya notifikationstyper. År 2022 publicerades notifikationstjänsten i produktionen och det första användningsändamålet blev punktbeskattningens EMCS och dess händelser.

Under 2024 är det planerat att notifikationstjänsten ska utvidgas till andra användningsändamål, såsom förfrågan om skattekort, brev och skatteperioder. Användaren av notifikationstjänsten och Vero API-gränssnitten kan beställa och få notifikations-indikatormeddelanden också om dessa nya användningsändamål när de har tagits i bruk i tjänsten.

I den första versionen stödjer tjänsten inte sändningen av meddelanden av push-typ utan endast förfrågningar. Detta betyder att användaren av tjänsten regelbundet ska skicka förfrågningar om notifikationer i gränssnittet ListNotifications.

• Genom att hämta de nyaste notifikationerna behöver programmet inte göra enskilda anrop kontinuerligt om alla kunder som är objekt utan endast när objektkundens uppgifter på basis av notifikationen har ändrats.

Push-notifikationstjänst (Notification Service)

Push-notifikationstjänsten är en ny tilläggstjänst för den nuvarande versionen av tjänsten. Enligt planen tas tjänsten i bruk under våren 2024.

• I push-notifikationstjänsten skickas de nya notifikationerna till användaren nästan i realtid direkt från Skatteförvaltningens system genom att utnyttja JSON-anrop av push-typ.
• Användaren behöver inte hämta de nyaste notifikationerna genom att regelbundet använda gränssnittet ListNotifications.
• I push-notifikationstjänsten beställer användaren mottagandet av notifikationstyper och registrerar sedan sitt program i push-notifikationstjänsten. Vid registreringen ger användaren identifikationsuppgiften (SubscriptionID) om sin egen beställning, URL-adressen till sitt system (CallBackURL) som denne vill ha push-notifikationerna till samt en separat hemlighet, alltså nyckeluppgiften (CallBackSecret), som fungerar som redskap för autentiseringen när push-meddelanden skickas till kunden. Hemligheten i fråga är en sådan som kundens system själv har fastställt och med vilken användaren försäkrar sig om att push-notifikationerna endast kommer från Skatteförvaltningen.

Nyttan av tjänsten för användaren

• Med hjälp av notifikationstjänsten kan till exempel processen vid uppgiftshämtandet påskyndas eftersom Vero API-gränssnitten inte behöver anropas för varje kund utan endast för dem som har förändringar i uppgifterna om användningsobjektet.
• Användningen av resurserna i kundens och Skatteförvaltningens system minskar i och med tjänsten eftersom antalet anrop minskar, uppgifter anmäls eller hämtas med Vero API-gränssnitt endast när det är nödvändigt.
• Trafiken på nätet minskar vilket leder till besparingar i driftskostnaderna för programmen. Programmen behöver mindre kapacitet och resurser för servern. Också driftskostnaderna för program som använder molnbaserade datortjänster kan sjunka eftersom användningen av gränssnitten effektiveras och antalet onödiga anrop minskar. Användningen av molnbaserade datortjänster effektiveras när behovet av att använda resurser till anrop minskar.
• Processtiden påskyndas. Användaren behöver inte göra så omfattande processkörningar som tidigare vid sändningen av anrop. Detta påskyndar funktionerna i programmet och effektiverar mottagningen av rätta uppgifter i programmet. Att processtiden blir kortare beror också på implementerade lösningar i användarens program.
• Belastningen på tjänsten Vero API minskar. Användningen av notifikationstjänsten effektiverar också i sin helhet fördelningen på Vero API-tjänsterna vilket möjliggör att det blir allt effektivare och säkrare att anmäla och hämta uppgifter via gränssnitten. Användningen av notifikationstjänsten minskar fördröjningarna i svarstiderna och anropen kommer fram snabbare både till Skatteförvaltningens system och till användarens eget program.
• Push-notifikationerna lämpar sig bra till användningssituationer i realtid där en indikator om ändringar i uppgifterna behövs genast, till exempel godkännande av utförsel i EMCS.
  • Uppgifterna i kundens system kan upprätthållas i realtid med Skatteförvaltningens uppgifter utan långvariga satsvisa körningar utanför tjänstetid.

Exempel på användningen:

Förfrågan om skattekort: Användaren har beställt uppföljning av nya skattekort. Användaren är en lönebetalare eller bokföringsbyrå som använder gränssnittet API för förfrågan om förskottsinnehållningsuppgifter. Ett nytt skattekort för lön görs på Skatteförvaltningen eller i MinSkatt för en kund (löntagare) som hänför sig till beställningen, och på basis av skattekortet skapas en notifikation i Skatteförvaltningens system. Notifikationen hämtas med gränssnittet ListNotifications eller skickas till användaren via tjänsten push-notifikation. Användaren kan på basis av notifikationen reagera och hämta uppgifterna om det nya skattekortet för lönebetalningen med gränssnittet API för förfrågan om förskottsinnehållningsuppgifter. Användaren behöver inte fråga efter ändrade skattekortsuppgifter hela tiden, till exempel dagligen om alla löntagare, utan endast när skattekortsuppgifterna har ändrats. Kunden (löntagaren) behöver inte själv lämna sitt skattekort till löneberäkningen.

Förfrågan om brev: Användaren har beställt uppföljning av nya brev. Användaren är en bokföringsbyrå som använder gränssnittet API för förfrågan om brev som hjälp med att sköta sina kunders beskattningsärenden. Skatteförvaltningen skickar ett nytt brev till en kund (kund hos bokföringsbyrån) som hänför sig till beställningen och på basis av brevet skapas en notifikation i Skatteförvaltningens system. Notifikationen hämtas med gränssnittet ListNotifications eller skickas till användaren via tjänsten push-notifikation. Användaren kan på basis av notifikationen reagera och hämta uppgifterna om det nya brevet med gränssnittet API för förfrågan om brev. Användaren behöver inte fråga efter nya brev hela tiden, till exempel dagligen för alla kunder, utan endast när kunden har fått nya brev.

Faserna i användningen av tjänsten på högre nivå

• Beställning (API endpoint: Subscribe)
  Kundens program beställer först notifikationstyper genom att anropa gränssnittet Subscribe för de kunder som hänför sig till användningssituationer som är objekt av intresse. Gränssnittet returnerar en identifierande beställningskod.
  
  • Vid användningen av tjänsten push-notifikation registrerar användaren sitt eget program i tjänsten för det mottagande gränssnittet för att få de nyaste notifikationerna nästan i realtid till sitt eget system.
• Förfrågan om notifikationer (API endpoint: ListNotifications)
  När beställningen har sparats lyckat anropar kundens program gränssnittet ListNotifications under lämplig tid och med rätt beställningskod för att få notifikationer.
  
  • Om användaren har tagit i bruk tjänsten push-notifikation får hen de nyaste notifikationerna automatiskt på basis av sin beställning och registrering i form av push-notifikationer direkt i sitt eget program. I push-notifikationsmeddelandet skickas endast nyckeln till notifikationen (NotificationKey). Inga känsliga uppgifter eller person- eller företagsuppgifter skickas i push-notifikationsmeddelanden.
  • Hämta det egentliga datainnehållet i push-notifikationsinnehållet, alltså innehållet i notifikationen, genom att använda gränssnittet GetNotification.
• Att reagera på notifikationer (i kundens program)
  När innehållet i notifikationen har hämtats till programmet, ska du bestämma vad som ska göras utifrån notifikationen, anropa exempelvis andra Skatteförvaltningens gränssnitt på basis av nyckeluppgiften i notifikationen. Kundens program har ansvaret för och kontrollen över aktiviteterna. Kundens program har också ansvaret för bokföringen av behandlade notifikationer.