Tekniska användningskrav för Push-notifikationstjänsten

• HTPS REST/JSON-gränssnitt som kan anropas från offentligt internet
• I slutet av gränssnittsadressen ska det ingå följande standarddel: “/Notify/v1”
• Exempel: https://{client host name}/Notify/v1
• Gränssnittet ska i bodyt av HTTP POST-anrop endast ta emot följande slag av JSON-notifikationsmeddelanden:

{
        "Environment": "FIP",
        "NotificationKey": 0,
        "NotificationType": "string",
        "SubscriptionId": 0,
        "Timestamp": "2021-04-22T12:01:33.478+02:00"
}

• Environment är en standardtext som anger miljön som används. “FIP” är produktionsmiljön, “FIS” är testmiljön.
• Gränssnittet ska inom 10 sekunder svara på Skatteförvaltningens notifikationsanrop.
• Gränssnittet ska svara med HTTP-koden 200 OK när gränssnittet lyckat har tagit emot ett push-notifikationsmeddelande. Detta svar fungerar som bekräftelse till Skatteförvaltningen på att push-notifikationen mottagits. Svaret ska inte innehålla bodyt.
• Vero API push-notifikationstjänsten försöker skicka samma notifikation till gränssnittet i kundens system högst tre gånger om gränssnittet inte alls svarar eller ger någon annan än HTTP-koden 200 OK. Efter tre försök gör push-notifikationstjänsten inga ytterligare försök att skicka samma notifikation igen. Ett e-postmeddelande skickas om misslyckade försök till e-postadressen för den kontaktperson som angetts i notifikationsbeställningen. Om det sker tillräckligt många mottagningsfel inom en viss tid, avbryts skickandet av push-notifikationer och ett e-postmeddelande skickas om detta. Kundens system ska utreda och korrigera orsaken till misslyckat notifikationsskickande varefter push-endpointen kan registreras på nytt.
• Skatteförvaltningen garanterar inte att push-notifikationerna kommer fram. Kundens system ska helst regelbundet anropa ListNotifications-gränssnittet och kontrollera att alla notifikationer har behandlats.
• Gränssnittet ska stödja notifikationstypen “HEALTHCHECK” och besvara omedelbart med koden HTTP 200 OK. Denna notifikationstyp är avsedd för att kontrollera att gränssnittet fungerar.
• Vero API push-notifikationstjänsten skickar notifikationstypen ”HEALTHCHECK” när adressen för det nya gränssnittet registreras. Dessutom kan health check även skickas i andra situationer för att säkerställa att anslutningen fungerar. Kundens system behöver inte reagera på något annat sätt än genom att svara 200 OK.
• Gränssnittet RegisterPush ska endast anropas när du registrerar ditt eget gränssnitt för första gången eller när det sker ändringar i ditt gränssnitt (t.ex. om callback secret ändras eller om push-prenumerationen avslutas). Användningen av gränssnittet RegisterPush är begränsad på Skatteförvaltningens sida, vilket innebär att endast ett anrop tillåts åt gången.
• Kundens system kan kontrollera Vero API push-notifikationstjänstens registreringsstatus genom att anropa ListSubscriptions-gränssnittet. Push-registreringsstatusen anger tjänstens status, active = push-notifikationer skickas, fail = anslutningen till kundens gränssnitt har misslyckats och skickandet av push-notifikationer har avbrutits, pending = health check-kontorollen pågår och push-notifikationer skickas inte till kundens system.
• När registreringen av en ny push-adress har lyckats, skickar Vero API push-notifikationsstjänsten ett e-postmeddelande om att registreringen lyckats till den kontaktpersons e-postadress som angetts i samband med notifikationsbeställningen. DoNotReply@vero.fi är avsändarens adress. Kontrollera att e-postmeddelandet tas emot, så att även inkommande felmeddelanden kan tas emot utan problem i felsituationer.
• Att gränssnittet i kundens system fungerar ska övervakas och de som ansvarar för underhållet av gränssnittet ska reagera på och åtgärda eventuella felsituationer.
• Om man vill avsluta skickandet av push-notifikationer eller behöver uppdatera kundens gränssnittsadress, kan kundens system göra dessa ändringar genom att anropa RegisterPush-gränssnittet. Genom att skicka en tom push-adress (callbackURL) avslutas skickandet av push-notifikationer. Den gamla adressen kan uppdateras till ny genom att skicka den nya adressen via RegisterPush-gränssnittet.
• Om ett serviceavbrott pågår i gränssnittet av kundens system eller om det krävs ett längre avbrott då det inte går att ta emot push-notifikationer, ska push-registreringen avslutas för avbrottstiden. Efter att avbrottet är över ska kundens system hämta notifikationerna via ListNotifications-gränssnittet. Om push-registreringen inte avslutas, avbryts skickandet av notifikationer automatiskt efter nya försök.

Säkerhetskrav för gränssnittet i kundens system

• Gränssnittet i kundens system ska använda proceduren mutual TLS / client certificate authentication och av anroparen kräva client certifikat i samband med SSL-handskakning. Att Skatteförvaltningen har beviljat certifikatet ska kontrolleras. På detta sätt verifierar kundens system att Skatteförvaltningen är anroparen.
  • Förutsätt att gränssnittsanroparna använder proceduren Client certificate authentication
  • Ett client-program som anropar Skatteförvaltningens gränssnitt ger ett certifikat i handskakningen vilket Skatteförvaltningens CA undertecknat.Kundens system ska ladda beviljarens CA-paket från vero.fi och använda det för att autentisera anroparen. CA-paketet kan laddas ner här: IRServicesIssuingCAv1-chain.cacert.zip, (ZIP)
    • Obs! Test- och produktionsmiljön har olika CA.
• Gränssnittet i kundens system ska också skyddas med en hemlighet som kundens system anger (API-nyckel).
  • Kundens system anger hemligheten som ska användas (API-nyckeln) i samband med push-endpointsregistreringen. Hemligheten (API-nyckeln) är en base64-enkodad teckensträng som är minst 32 tecken lång.
  • Skatteförvaltningen skickar hemligheten i headern “vero-callback-secret” i samband med push-gränssnittsanropen. Kundens system ska kontrollera att headern används och att värdet i den är samma som det värde som angetts vid registreringen.
• Gränssnittet i kundens system ska använda HTTPS-protokollet och TLS version 1.2 eller nyare version
• Gränssnittet måste stödja en av följande Cipher suites:
  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• Skatteförvaltningens push-notifikationstjänst skickar anropen till kundens system från molntjänsten Azure. Push-notifikationstjänsten har på förhand fastställd ip-adress:
  • Testmiljö: 57.153.39.45
  • Produktionsmiljö: 108.142.42.70
  • Kundens system måste göra nödvändiga brandväggsöppningar för att tillåta nätverkstrafiken till port 443 från dessa Azure-adresser.

Testning av push-notifikationer

I Vero API testmiljön kan testning av push-notifikationer endast utföras genom att anropa gränssnittet RegisterPush. Under anropet skickas ett HEALTHCHECK-meddelande i realtid till den angivna adressen. Anropet till RegisterPush lyckas om den angivna adressen (callbackURL) svarar med HTTP-status 200 OK på HEALTHCHECK-notifikationen.
Med detta kan man i testmiljön säkerställa att det erbjudna gränssnittet kan ta emot notifikationer från Skatteförvaltningen. Ett lyckat RegisterPush-anrop i testmiljön skickar inte e-post och registreringen sparas inte någonstans.

Med hjälp av godkännande­testning i Vero API produktionsmiljö kan man säkerställa att leveransen av push-notifikationer fungerar samt att miljön är fungerande. Under anropet till Verification/RegisterPush skickas ett HEALTHCHECK-meddelande till den angivna adressen på samma sätt som i testmiljön.