Suomen Tilaajavastuu Oy Veronumero.fi Tarkastaja rajapinta Rajapintakuvaus veronumeroiden tarkastamiseen ja henkilötietojen noutamiseen Suomen Tilaajavastuu Oy Muutoshistoria Päivämäärä Tekijä Muutos 11.2.2013 EH v.0.9 ensimmäinen versio asiakkaille tutustuttavaksi JJ v.0.9.1 Korjattu XML:t vastaamaan toteutusta. Laajennettu FindReq:ä ja lisätty RegisterPersonReq
Sisällys Yleistä Veronumero.fi palvelusta... 2 Rajapinnan tekninen toteutus... 3 Liikenne ja tunnistautuminen... 3 Rajapinnan palauttamat HTTP- status koodit... 3 Rajapinnan toiminnallisuudet... 4 Hae henkilö (FindReq)... 4 Pyyntö (FindReq)... 5 Vastaus (FindResp)... 5 Virhetilanteet... 6 Tarkasta veronumerot... 7 Pyyntö (ValidateReq)... 7 Vastaus (ValidateResp)... 7 Virhetilanteet... 7 Ilmoita henkilön tiedot... 8 Pyyntö... 8 Vastaus... 8 Virhetilanteet... 8 Poista henkilö (TOTEUTETAAN MYÖHEMMIN)... 9 Pyyntö... 9 1
Rajapintakuvaus Yleistä Veronumero.fi palvelusta Veronumero.fi palvelussa (www.veronumero.fi) kerätään veronumerolakiin liittyviä työnantaja- ja henkilötietoja. Palveluun on olemassa www- käyttöliittymä sekä tässä dokumentissa kuvattava xml- rajapinta. Palvelun kautta työnantajat ilmoittavat henkilöiden veronumerot Verohallinnon ylläpitämään rakennusalan veronumerorekisteriin. Lisäksi työnantajat voivat palvelun kautta tilata kuvalliset, veronumerolla varustetut henkilökortit. Ilmoitettavista veronumeroista kootaan kullekin työnantajalle oma henkilörekisteri, josta löytyy keskeisimmät työnantaja- ja työntekijätiedot. Kukin työnantaja ylläpitää rekisteriä omista työntekijöistään. Kaikki työnantajien tallentamat tiedot ovat noudettavissa yksittäisinä pyyntöinä tässä dokumentissa kuvatun teknisen rajapinnan kautta myös muihin palveluihin. Myöhemmin toteutetaan rajapinta jonka kautta voidaan tarkastaa kerrallaan useiden henkilöiden veronumerotiedot. Myöhemmin toteutetaan myös rajapinta, jonka avulla voi lisätä henkilöitä veronumero.fi:hin sekä ilmoittaa heidät rakennusalan veronumerorekisteriin. 2
Rajapinnan tekninen toteutus Rajapintaa käytetään Http(s)- protokollalla. Pyynnöt ohjataan palveluun, joka luo vastauksen reaaliajassa. Yksittäiset pyynnöt ovat xml- muotoisia. XML- muotoiset pyynnöt tulee lähettää HTTP POST BODY:ssä, osoitteeseen: https://tarkastaja.veronumero.fi/tarkastaja Rajapinta palauttaa XML- muotoisen vastauksen. Pyyntöjen ja vastauksien merkistönä on käytössä UTF- 8. Koneellisesti tarkastettavien parametrien oikeellisuus varmistetaan aina ennen pyynnön käsittelyä. Liikenne ja tunnistautuminen Liikenne hoidetaan HTTPS - protokollan kautta ja käyttäjät tunnistetaan http basic authentication - menetelmällä. Tunnistamisessa tarvittava käyttäjätieto noudetaan Tilaajavastuu.fi palvelun yhteiseltä LDAP palvelimelta. Rajapinnan palauttamat HTTP- status koodit Rajapinta palauttaa aina 200 OK. Toteutukseen lisätään myöhemmin myös muita http- status koodeja joilla kerrotaan asiakasohjelmistolle mahdollisista virheistä tai todennus virheistä. 3
Rajapinnan toiminnallisuudet FindReq Pyytää yksicäisen henkilön dedot FindResp ValidateReq Tarkastaa yhden tai useamman veronumeron ja ValidateResp henkilön tunnisteen vastaavuuden Toteutetaan DeletePersonResp DeletePersonReq myöhemmin AddPersonReq Pyytää lisäämään yhden tai useamman henkilön dedot verocajan AddPersonResp veronumerorekisteriin Hae henkilö (FindReq) Rajapinnan kautta voidaan noutaa ainoastaan yksittäisen henkilön tiedot. Henkilön tiedot ovat aina jonkin työnantajan antamia, eli järjestelmässä olevalla henkilöllä on tiedossa vähintään yksi työnantaja. Jos samalla tunnisteella (hetu tai veronumero) löydetään sama henkilö usealta eri työnantajalta, palautetaan henkilön tiedot kaikilta työnantajilta. Koska kukin työnantaja ylläpitää itse työntekijöiden tietoja, voivat samaan henkilöön liittyvät tiedot olla toisistaan poikkeavia eri työnantajilla. Käytännössä tämä tarkoittaa, että samalla henkilöllä voi olla esimerkiksi eri puhelinnumero työsuhteesta riippuen. Vastauksissa palautetaan ainoastaan henkilöt, joista löytyy tarkastetut veronumerot. Henkilötunnuksia ei koskaan palauteta. 4
Pyyntö (FindReq) Esimerkkejä pyynnöistä: A) <FindReq xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Person ssn="280477-049r"/> </FindReq> B) <FindReq xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Person taxnumber="100013753145"/> </FindReq> C) <FindReq xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Person foreignssn="abc 1234-6789"/> </FindReq> D) Useiden henkilöiden tietojen tarkistus <FindReq xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Person ssn="280477-049r"/> <Person taxnumber="100013753145"/> </FindReq> Henkilöihin liittyvät tiedot voidaan noutaa, kun pyynnössä on määritelty täsmälleen yksi seuraavista: ssn (suomalainen henkilötunnus) taxnumber (veronumero) foreignssn (ulkomaalainen henkilötunnus, ei muotovaatimuksia) Vastaus (FindResp) Esimerkki vastauksesta: <FindResp result="ok" xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Employer addresscountry="finland" postoffice="espoo" postcode="02600" address="vänrikinkuja 2" homeland="fi" businessid="1789014-2" name="aspida Oy"> <Person source="veronumero.fi" dateofbirth="20.03.1984" phone="040123456" domicile="helsinki" nationality="fi (Suomi)" lastname="meikäläinen" firstname="matti" taxnumber="100013753145"></person> </Employer> </FindResp> Työnantajaan liittyvät tiedot: addresscountry (postiosoitteen maa) postoffice (postiosoitteen postitoimipaikka) address (postiosoitteen katuosoite) homeland (yrityksen kotivaltio, ISO3166-1- koodiston mukainen maatunnus) businessid (joko suomalainen tai virolainen y- tunnus) name (yrityksen nimi) 5
Työntekijään liittyvät tiedot: source(lähde josta tiedot on haettu) dateofbirth (syntymäaika muodossa pp.kk.vvvv) phone (puhelinnumero, muotoa ei tarkasteta) domicile (kotikunta) nationality (kansallisuus, kaksi ensimmäistä merkkiä ovat ISO3166-1 standardin mukainen maakoodi ) lastname (sukunimi) firstname (etunimi) taxnumber (veronumero) Esimerkki vastauksesta useille työntekijöille: <FindResp result="ok" xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Persons> <Person taxnumberstatus= Verified source= veronumero.fi taxnumber= 123456789012 /> <Person taxnumberstatus= Verified source= veronumero.fi taxnumber= 111111111111 /> <Person taxnumberstatus= TaxNumberNotFound /> </Persons> <Employer addresscountry="finland" postoffice="espoo" postcode="02600" address="vänrikinkuja 2" homeland="fi" businessid="1789014-2" name="aspida Oy"> <Person taxnumberstatus= Verified source="veronumero.fi" dateofbirth="20.03.1984" phone="040123456" domicile="helsinki" nationality="fi (Suomi)" lastname="meikäläinen" firstname="matti" taxnumber="100013753145"></person> </Employer> </FindResp> Virhetilanteet Mikäli henkilöitä ei löydy annetuilla tunnisteilla, niin rajapinta palauttaa tästä ilmoituksen. <FindResp result="notfound" errortext="person information not found!" xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> </FindResp> 6
Tarkasta veronumerot Veronumerot voidaan tarkastaa joukkona, jossa on yhdestä useampaan henkilötunnusta tai nimi + veronumero - paria. Lisäksi tarkastus voidaan tehdä myös nimellä tai nimen osalla ja veronumerolla. Veronumeroa haetaan ensi veronumero.fi palvelun tietokannasta, ja jos tietoa ei löydetä niin sitten verohallinnon palvelusta. Pyyntö (ValidateReq) Rajapinnan kautta ilmoitetaan joko henkilötunnus tai sukunimi + veronumero pari. Pyynnössä voi olla yhden tai useamman henkilön tiedot listattuna. Esimerkki pyynnöstä <ValidateReq xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Person ssn="280477-049r" lastname="iso- Anttila" /> <Person taxnumber="123456789012" lastname="iso- Anttila" /> <Person taxnumber="123456789013" foreignssn="280477-050s" /> </ValidateReq> Vastaus (ValidateResp) Vastauksena palautetaan hakuavain (sukunimi tai hetu) ja kaksi kenttää. Ensimmäisessä kentässä palautetaan veronumero jos se oli oikein, toisessa kentässä palautetaan tarkastuksen lähde (Veronumero.fi tai Verohallinto). Esimerkki vastauksesta <ValidateResp result="ok" xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Person taxnumber="123456789012" firstname="lari" lastname="iso- Anttila" nationality="fi (Suomi)" domicile="espoo" dateofbirth="28.04.1977" taxnumberstatus="verified" source="veronumero.fi" /> <Person taxnumber="123456789013" firstname="kalle" lastname="iso- Kallio" nationality="fi (Suomi)" domicile="espoo" dateofbirth="28.04.1977" taxnumberstatus="verified" source="veronumero.fi" /> </ValidateResp> Virhetilanteet Mikäli veronumero tai hetu oli teknisesti virheellinen, niin siitä palautetaan virheilmoitus. Mikäli hetu tai veronumero oli teknisesti oikein, mutta ei löytynyt, niin siitä ilmoitetaan, tässä tapauksessa ilmoitetaan myös tarkastuksen lähde. 7
Ilmoita henkilön tiedot Pyyntö Rajapinnan kautta voidaan myös lisätä henkilöt veronumero.fi- palveluun ja ilmoittaa henkilön tiedot rakennusalan veronumerorekisteriin. Ilmoituksessa tulee vähintään olla mukana henkilön kaikki pakolliset tiedot ja työnantajan Y- tunnus. Henkilöstä ilmoitettava tiedot Parametri Kuvaus Pakollinen tieto Henkilötunnus (hetu) Suomalainen henkilötunnus. Pakollinen Veronumero 12 merkkinen veronumero. Pakollinen Ulkomaalainen henkilötunnus Henkilön ulkomaalainen henkilötunnus Pakollinen, mikäli kyseessä ei ole Suomen kansalainen Sukunimi Pakollinen Etunimi Pakollinen Kansallisuustunnus Henkilön kansallisuus, esim. FIN Pakollinen Kotipaikka Henkilön kotipaikkakunta Vapaaehtoinen GSM- numero Henkilön työsuhteessa käyttämä puhelinnumero Vapaaehtoin Esimerkki pyynnöstä <RegisterPersonReq xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Employer businessid="2327327-1"> <Person taxnumber="123456789012" ssn="280477-123x" firstname="lari" lastname="iso- Anttila" foreignssn="280477-049r" nationality="suomi" domicile="espoo" phone="0405583991" /> </Employer> </RegisterPersonReq> Vastaus Vastauksena ilmoitetaan vahvistus tietojen vastaanottamisesta. Esimerkki pyynnöstä <RegisterPersonResp result="ok" xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd" /> Virhetilanteet Mikäli keskeisissä tiedoissa (veronumero tai hetu) huomataan koneellisessa tarkastuksessa virhe, niin palautetaan tästä tiedot. 8
Poista henkilö (TOTEUTETAAN MYÖHEMMIN) Poista toiminto ei poista henkilöä Verohallinnon ylläpitämästä rakennusalan veronumerorekisteristä. Toiminnallisuus poistaa ainoastaan henkilön tiedot halutulta työnantajalta. Tietokantaan jää edelleen merkintä henkilötunnus ja veronumero yhdistelmästä tietojen myöhempää tarkastamista varten. Pyyntö Rajapinnan kautta pyydetään henkilön tietojen poistamista yhdistelmällä y- tunnus + veronumero. Poistamisen voi tehdä ainoastaan sama yritys, joka on ilmoittanut henkilön. 9