Tekniset vaatimukset Push-notifikaatiopalvelun käyttöön

Push-notifikaatiopalvelun käyttäjän on tarjottava Verohallinnolle rajapinta, johon push-notifikaatiot voi lähettää julkisen internetin kautta. Rajapinnan on täytettävä seuraavat tekniset- ja turvallisuusvaatimukset:

• HTTPS REST/JSON rajapinta, jota voi kutsua julkisesta Internetistä
• Rajapinnan osoitteen lopussa on oltava seuraava vakio-osa: “/Notify/v1”
  Esimerkki: https://{client host name}/Notify/v1
• Rajapinnan on otettava vastaan ainoastaan seuraavassa kuvatun kaltaisia JSON-notifikaatiosanomia HTTP POST-kutsujen bodyssä:

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

• Environment on vakioteksti, joka kertoo käytettävän ympäristön. “FIP” on tuotantoympäristö, “FIS” on testiympäristö.
• Rajapinnan on vastattava 10 sekunnin sisällä Verohallinnon lähettämään notifikaatiokutsuun.
• Rajapinnan on vastattava HTTP-koodilla 200 OK kun rajapinta on onnistuneesti vastaanottanut push-notifikaatiosanoman. Tämä vastaus toimii kuittauksena Verohallinnon suuntaan push-notifikaation vastaanottamisesta. Vastauksessa ei tule olla bodyä.
• Vero API push-notifikaatiopalvelu yrittää lähettää saman notifikaation asiakkaan järjestelmän rajapintaan korkeintaan kolme kertaa, mikäli rajapinta ei vastaa ollenkaan tai antaa muun kuin 200 OK HTTP-koodin. Kolmen yrityksen jälkeen push-notifikaatiopalvelu ei yritä lähettää samaa notifikaatiota uudelleen. Epäonnistumisesta lähetetään sähköposti notifikaatiotilauksessa annetun yhteyshenkilön sähköpostiosoitteeseen. Mikäli vastaanottovirheitä tapahtuu riittävä määrä tietyn ajan kuluessa, push-notifikaatioiden toimitus keskeytetään ja asiasta lähetetään sähköpostiviesti. Asiakkaan järjestelmän tulee selvittää notifikaatioiden toimituksen epäonnistumisen syy, korjata se ja tämän jälkeen push-endpointin voi rekisteröidä uudelleen.
• Verohallinto ei takaa push-notifikaatioiden perillemenoa. Asiakkaan järjestelmän kannattaa säännöllisesti kutsua ListNotifications-rajapintaa ja tarkistaa, että kaikki notifikaatiot on käsitelty.
• Rajapinnan on tuettava “HEALTHCHECK”-tyyppistä notifikaatiota ja vastattava siihen HTTP-koodilla 200 OK välittömästi. Tämä notifikaatiotyyppi on tarkoitettu rajapinnan toimivuuden tarkistamiseen.
• Vero API push-notifikaatiopalvelu lähettää ”HEALTHCHECK” -notifikaatiotyypin, kun uuden rajapinnan osoitteen rekisteröi. Lisäksi health check voidaan lähettää muulloinkin yhteyden toimivuuden varmistamiseksi. Asiakkaan järjestelmän ei tarvitse reagoida tähän muulla tavalla kuin vastaamalla 200 OK.
• RegisterPush -rajapintaa tulee kutsua ainoastaan silloin kun ensimmäisen kerran rekisteröi oman rajapintansa tai omaan rajapintaan tulee muutoksia (esim. callback secret muuttuu tai lopettaa push-tilauksen). RegisterPush -rajapinnan käyttö on verohallinnon puolella käyttömäärältään rajoitettu, joten rajapinta sallii ainoastaan yhden kutsun kerrallaan.
• Asiakkaan järjestelmä voi tarkistaa Vero API push-notifikaatiopalvelun rekisteröinnin tilanteen kutsumalla ListSubscriptions-rajapintaa. Push-rekisteröinnin tila kertoo palvelun tilan, active = push-notifikaatioita toimitetaan, fail = yhteys asiakkaan rajapintaan on epäonnistunut ja push-notifikaatioiden toimitus on katkaistu, pending = health check-tarkistus on meneillään ja push-notifikaatioita ei toimiteta asiakkaan järjestelmään.
• Uuden push-osoitteen rekisteröinnin onnistuttua, Vero API push-notifikaatiopalvelu lähettää sähköpostin onnistuneesta rekisteröinnistä notifikaatiotilauksen yhteydessä annettuun yhteyshenkilön sähköpostiosoitteeseen. Lähettäjänä DoNotReply@vero.fi -osoite. Varmista, että sähköposti vastaanotetaan, jotta myös poikkeustilanteissa saapuvat häiriöilmoitukset vastaanotetaan onnistuneesti.
• Asiakkaan järjestelmän rajapinnan toimivuutta on monitoroitava ja rajapinnan ylläpidosta vastaavien on reagoitava ja korjattava virhetilanteet.
• Jos push-notifikaatioiden toimitus halutaan lopettaa tai on tarve päivittää asiakkaan rajapinnan osoitetta, asiakkaan järjestelmä voi tehdä nämä muutokset kutsumalla RegisterPush-rajapintaa. Lähettämällä tyhjän push-osoitteen (callbackURL), push-notifikaatioiden toimitus lopetetaan. Vanhan osoitteen voi päivittää uudeksi lähettämällä RegisterPush-rajapinnan kautta uuden osoitteen.
• Jos asiakkaan järjestelmän rajapinnassa on huoltokatko tai tarvitaan pidempi tauko, jolloin push-notifikaatioita ei voida vastaanottaa, on push-rekisteröinti päätettävä katkon ajaksi. Asiakkaan järjestelmän on noudettava katkon päätyttyä katkon aikaiset notifikaatiot ListNotifications-rajapinnalla. Mikäli push-rekisteröintiä ei päätä, katkeaa notifikaatioiden toimitus automaattisesti uudelleen yritysten jälkeen.

Asiakkaan järjestelmän rajapinnan turvallisuusvaatimukset

Push-notifikaatioiden tietosisältö ei ole arkaluontoista ja se ei sisällä henkilötietoja. Tietosisältö koostuu ainoastaan teknisistä avaintiedoista.

• Asiakkaan järjestelmän rajapinnan on käytettävä mutual TLS / client certificate authentication-menettelyä ja pyydettävä kutsujalta client-varmenne SSL-kättelyn yhteydessä. Varmenteesta on tarkistettava, että sen myöntäjä on Verohallinto. Tällä tavalla asiakkaan järjestelmä varmistaa, että kutsuja on Verohallinto.
  • Edellytä client certificate authentication-menettelyä rajapinnan kutsujilta
  • Verohallinnon rajapintaa kutsuva client-ohjelma antaa kättelyssä varmenteen, jonka on allekirjoittanut Verohallinto CA.
  • Asiakkaan järjestelmän tulee ladata myöntäjän CA-paketti Vero.fi:stä ja käyttää sitä kutsujan tunnistamisessa. CA-paketti on ladattavissa täältä: IRServicesIssuingCAv1-chain.cacert.zip, (ZIP)
    • Huom! Testi- ja tuotantoympäristöissä on eri CA.
• Asiakkaan järjestelmän rajapinta on suojattava lisäksi asiakkaan järjestelmän ilmoittamalla salaisuudella (API-avain).
  • Asiakkaan järjestelmä ilmoittaa käytettävän salaisuuden (API-avaimen) push-endpointin rekisteröinnin yhteydessä. Salaisuus (API-avain) on base64-enkoodattu merkkijono, jonka pituus on vähintään 32 merkkiä.
  • Verohallinto lähettää push-rajapintakutsujen yhteydessä tämän salaisuuden headerissa “vero-callback-secret”. Asiakkaan järjestelmän on tarkistettava, että headeria käytetään ja siinä tullut arvo on sama mikä rekisteröinnissä on annettu.
• Asiakkaan järjestelmän rajapinnan on käytettävä HTTPS-protokollaa ja TLS 1.2 versiota tai uudempaa
• Rajapinnan on tuettavat jotakin seuraavista Cipher suiteista:
  • 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
• Verohallinnon push-notifikaatiopalvelu lähettää kutsut asiakkaan järjestelmään Azure-pilvipalvelusta. Push-notifkaatiopalvelulla ei ole etukäteen määriteltyjä ip-osoitteita. Asiakkaan järjestelmän on tehtävä tarvittavat palomuuriavaukset sallimaan liikenne porttiin 443 yleisistä Azure-osoitteista.

Push-notifikaatioiden testaus

Vero API-testiympäristössä push-notifikaatioiden testauksen voi suorittaa ainoastaan kutsumalla RegisterPush-rajapintaa. Annettuun osoitteeseen lähetetään tällöin reaaliaikaisesti yksi HEALTHCHECK-tyyppinen notifikaatiosanoma RegisterPush-kutsun aikana. RegisterPush-kutsu onnistuu, mikäli rekisteröinnissä annettu osoite (callbackURL) vastaa 200 OK HEALTHCHECK-notifikaatioon. Tämän avulla voi varmistaa testiympäristössä, että tarjottu rajapinta pystyy vastaanottamaan notifikaatioita Verohallinnosta. Onnistunut RegisterPush-kutsu testiympäristössä ei lähetä sähköpostia eikä kyseinen rekisteröinti tallennu mihinkään.

Hyväksymistestauksen avulla Vero API tuotantoympäristössä voi varmistaa tuotantoympäristön Push-notifikaatioiden toimituksen yhteydet ja ympäristön toimivuuden. Verification/RegisterPush-lähettää kutsun aikana HEALTHCHECK-notifikaation annettuun osoitteeseen samaan tapaan kuin testiympäristö.