Notifikaatiopalvelu

Palvelun tarkoitus

Notifikaatiopalvelu on lisäpalvelu, jonka tarkoituksena on tehostaa muiden Vero API rajapintojen käyttöä. Palvelu mahdollistaa määriteltyjen Notifikaatiotyyppien tilaamisen ja vastaanottamisen Verohallinnosta. Notifikaatio on yksinkertainen heräteviesti, joka kertoo, että jotakin verotukseen liittyvää on tapahtunut jollekin asiakkaalle. Esimerkiksi tilauksessa valitulle asiakkaalle on tapahtunut jokin verotustapahtuma, jonka perusteella luodaan notifikaatio, johon Vero API rajapinnan käyttäjän tulee reagoida.

Notifikaatio sisältää tiedotteen tyypin ja avaintiedon, jolla notifikaatioon liittyvä varsinainen tietosisältö on noudettavissa sopivalla rajapinnalla. Notifikaatiot ovat tilattomia ja Notifikaatiopalvelua käyttävien ohjelmistojen vastuulla on pitää kirjaa mitä tiedotteita on jo käsitelty ja miten saatuihin notifikaatioihin reagoidaan.

Käytettävissä olevat notifikaatiotyypit 17.9.2024:

• Valmisteverotuksen EMCS järjestelmä ja sen tapahtumat

Tulossa olevat notifikaatiotyypit:

• Verokortit
• Kirjeet ja päätökset
• Verokauden pituuden muutokset

Push-notifikaatio

Push-notifikaatiopalvelu on vaihtoehtoinen tapa vastaanottaa notifikaatioita suoraan Veron järjestelmästä vastaanottamalla Push-tyyppisiä JSON kutsuja. Käyttäjän ei tarvitse hakea uusimpia notifikaatioita käyttämällä säännöllisesti ListNotifications rajapintaa.

Push-notifikaatiopalvelussa käyttäjä tekee tilauksen notifikaatiotyyppien vastaanottamiseen ja sen jälkeen rekisteröi oman ohjelmistonsa push-notifikaatiopalveluun.

Palvelun hyödyt käyttäjälle

• Notifikaatiopalvelun avulla voidaan esimerkiksi nopeuttaa tietojen noutoprosesseja, koska Vero API-rajapintoja ei tarvitse tehdä kutsua aina jokaiselle asiakkaalle vaan ainoastaan niille, joilla on muutoksia käyttökohteen tiedoissa.
• Resurssien käyttö asiakkaan ja Verohallinnon järjestelmissä vähenee palvelun käytön myötä, koska kutsumäärät vähenevät, tietoja ilmoitetaan tai haetaan Vero API rajapinnoilla vain silloin, kun se on tarpeellista.
• Verkkoliikenne vähenee, mikä aiheuttaa säästöjä ohjelmistojen käyttökustannuksissa. Ohjelmistot tarvitsevat vähemmän palvelinkapasiteettia ja -resursseja. Myös pilvipalveluita käyttävien ohjelmistojen käyttökustannukset voivat laskea, koska rajapintojen käyttö tehostuu ja turhien kutsujen määrät vähenevät. Pilvipalveluiden käyttö tehostuu, kun ei ole tarvetta käyttää niin suurta määrää resursseja kutsuihin.
• Prosessointiaika nopeutuu. Käyttäjän ei tarvitse tehdä niin laajoja prosessointiajoja rajapintojen kutsujen lähettämisessä, kuin aikaisemmin. Tämä nopeuttaa ohjelmiston toimivuutta ja tehostaa oikeiden tietojen saamista käyttäjän ohjelmistoon. Prosessointiajan lyhentäminen on myös riippuvaista käyttäjän ohjelmiston toteutusratkaisusta.
• Vero API-palvelun kuormitus vähenee. Notifikaatiopalvelun käyttö tehostaa myös kokonaisuudessaan Vero API-palvelujen käyttöä, joka mahdollistaa tietojen ilmoittamisen ja hakemisen rajapintojen kautta entistä tehokkaammin ja varmemmin. Notifikaatiopalvelun käyttö vähentää rajapintojen vasteaikojen viiveitä ja kutsut tulevat nopeammin perille Verohallinnon järjestelmään sekä käyttäjän omaan ohjelmistoon.
• Push-notifikaatiot sopivat hyvin reaaliaikaisiin käyttötilanteisiin, jossa tiedon muuttumisesta tarvitaan heräte heti, esim. EMCS vientiin hyväksyminen.
  • Asiakkaan järjestelmän tietoja voidaan pitää reaaliaikaisesti yllä Verohallinnon tiedoilla ilman pitkäkestoisia eräajoprosesseja virka-ajan ulkopuolella.

Esimerkkejä tulossa olevista käyttötapauksista:

Verokorttien kysely: Käyttäjä on tehnyt tilauksen uusien verokorttien seuraamiseen. Käyttäjä on palkanmaksaja tai tilitoimisto, joka käyttää ennakonpidätystietojen kysely API rajapintaa. Tilaukseen liittyvälle asiakkaalle (palkansaaja) luodaan Verohallinnossa tai Omaverossa uusi verokortti palkkaa varten, jonka perusteella luodaan notifikaatio Veron järjestelmään. Notifikaatio haetaan ListNotifications rajapinnalla tai lähetetään käyttäjälle Push-notifikaatiopalvelun kautta. Käyttäjä voi notifikaation perusteella reagoida ja hakea uuden verokortin tiedot palkanmaksua varten ennakonpidätystietojen kysely API:lla. Käyttäjän ei tarvitse kysellä muuttuneita verokorttitietoja jatkuvasti, esimerkiksi päivittäin kaikille palkansaajilleen, vaan ainoastaan, kun verokorttitiedot ovat muuttuneet. Asiakkaan (palkansaaja) ei tarvitse toimittaa verokorttia itse palkanlaskentaan.

Kirjeiden kyselyt: Käyttäjä on tehnyt tilauksen uusien kirjeiden seuraamiseen. Käyttäjä on tilitoimisto, joka käyttää kirjeiden kysely API rajapintoja asiakkaidensa verotusasioiden hoitamisen avuksi. Tilaukseen liittyvälle asiakkaalle (tilitoimiston asiakas) lähetetään uusi kirje Verohallinnolta, jonka perusteella luodaan notifikaatio Veron järjestelmään. Notifikaatio haetaan ListNotifications rajapinnalla tai lähetetään käyttäjälle Push-notifikaatiopalvelun kautta. Käyttäjä voi notifikaation perusteella reagoida ja hakea uuden kirjeen tiedot kirjeiden kysely API rajapinnoilla. Käyttäjän ei tarvitse kysellä uusia kirjeitä jatkuvasti, esimerkiksi päivittäin kaikille asiakkailleen, vaan ainoastaan, kun uusia kirjeitä on saapunut asiakkaille.

Palvelun käytön vaiheet ylätasolla

• Tilaus (API endpoint: Subscribe)
  Asiakkaan ohjelmisto tekee aluksi tilauksen Notifikaatiotyypeistä kutsumalla Subscribe-rajapintaa asiakkaille, jotka liittyvät kiinnostuksen kohteena oleviin käyttötilanteisiin. Rajapinta palauttaa yksilöivän tilaustunnisteen.
  • Push-notifikaatiopalvelun käytössä käyttäjä rekisteröi oman ohjelmiston vastaanottavan rajapinnan palveluun saadakseen uusimmat notifikaatiot lähes reaaliaikaisesti omaan järjestelmään.
  • Käyttäjä antaa rekisteröinnissä oman tilauksensa tunnistetiedon (SubscriptionID), oman järjestelmän URL-osoitteen (CallBackURL), johon haluaa push-notifikaatioiden saapuvan sekä erillisen salaisuuden, eli avaintiedon (CallBackSecret), joka toimii autentikaation välineenä, kun push-ilmoituksia lähetetään asiakkaalle. Kyseinen salaisuus on asiakkaan järjestelmän itse määrittelemä, jolla käyttäjä varmistaa, että saapuvat push-notifikaatiot ovat peräisin ainoastaan Verohallinnolta.
• Kysele notifikaatioita (API endpoint: ListNotifications)
  Kun tilaus on onnistuneesti tallennettu, asiakkaan ohjelmisto pollaa ListNotifications-rajapintaa sopivalla aikajaksolla ja tilaustunnisteella saadakseen notifikaatiot.
  • Jos käyttäjä on ottanut käyttöön Push-notifikaatiopalvelun, hän saa uusimmat notifikaatiot automaattisesti tilauksensa ja rekisteröintinsä perusteella Push-notifikaatioina suoraan oman ohjelmistoon. Push-notifikaation sanomassa lähetään ainoastaan notifikaation avain (NotificationKey). Mitään arkaluontoisia tai henkilö- tai yritystietoja ei lähetetä Push-notifikaatio sanomissa.
  • Hae Push-notifikaatiopalvelun sanoman varsinainen tietosisältö, eli notifikaation sisältö käyttämällä GetNotification rajapintaa.
• Notifikaatioihin reagointi (asiakkaan ohjelmistossa)
  Kun notifikaation sisältö on noudettu asiakkaan ohjelmistoon, päätä mitä notifikaation perusteella tehdään, kutsu esimerkiksi muita Verohallinnon rajapintoja notifikaation avaintiedon perusteella. Aktiviteettien orkestraatio on asiakkaan ohjelmiston vastuulla ja hallinnassa. Kirjanpito käsitellyistä notifikaatioista on myös asiakkaan ohjelmiston vastuulla.