Veronumero.fi Tarkastaja – rajapinta

 Suomen Tilaajavastuu Oy Veronumero.fi Tarkastaja – rajapinta Rajapintakuvaus veronumeroiden tarkastamiseen ja henkilötietojen noutamiseen Suomen Tilaajavastuu Oy Muutoshistoria Päivämäärä 11.2.2013 Tekijä EH 3.4.2013 JJ Muutos v.0.9 – ensimmäinen versio asiakkaille tutustuttavaksi 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 Versio 0.9.1 3.4.2013 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 Versio 0.9.1 3.4.2013 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 Versio 0.9.1 3.4.2013 Rajapinnan toiminnallisuudet FindReq Pyytää yksicäisen henkilön dedot FindResp ValidateReq Tarkastaa yhden tai useamman veronumeron ja henkilön tunnisteen vastaavuuden ValidateResp DeletePersonReq DeletePersonResp Toteutetaan myöhemmin AddPersonReq Pyytää lisäämään yhden tai useamman henkilön dedot verocajan veronumerorekisteriin AddPersonResp 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 Versio 0.9.1 3.4.2013 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)
<?xml version="1.0" encoding="UTF-­‐8"?> <FindReq xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> <Person foreignSsn="abc 1234-­‐6789"/> </FindReq> D) Useiden henkilöiden tietojen tarkistus
<?xml version="1.0" encoding="UTF-­‐8"?> <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: <?xml version="1.0" encoding="UTF-­‐8"?> <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 Versio 0.9.1 3.4.2013 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: <?xml version="1.0" encoding="UTF-­‐8"?> <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. <?xml version="1.0" encoding="UTF-­‐8"?> <FindResp result="NotFound" errorText="Person information not found!" xmlns="http://www.tilaajavastuu.fi/tarkastaja.xsd"> </FindResp> 6 Versio 0.9.1 3.4.2013 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ä <?xml version="1.0" encoding="UTF-­‐8"?> <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 <?xml version="1.0" encoding="UTF-­‐8"?> <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 Versio 0.9.1 3.4.2013 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 Henkilötunnus (hetu) Veronumero Ulkomaalainen henkilötunnus Kuvaus Suomalainen henkilötunnus. 12 merkkinen veronumero. Henkilön ulkomaalainen henkilötunnus Henkilön kansallisuus, esim. FIN Henkilön kotipaikkakunta Henkilön työsuhteessa käyttämä puhelinnumero Sukunimi Etunimi Kansallisuustunnus Kotipaikka GSM-­‐numero Pakollinen tieto Pakollinen Pakollinen Pakollinen, mikäli kyseessä ei ole Suomen kansalainen Pakollinen Pakollinen Pakollinen Vapaaehtoinen Vapaaehtoin Esimerkki pyynnöstä <?xml version="1.0" encoding="UTF-­‐8"?> <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ä <?xml version="1.0" encoding="UTF-­‐8"?> <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 Versio 0.9.1 3.4.2013 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 Versio 0.9.1 3.4.2013