OpusCapita TYVI AJL 1 (24) OpusCapitaTYVI asiakasjärjestelmäliittymä 2.2 Tekninen kuvaus versio 1.5 OpusCapita Group Oy Keilaranta 13 FI-02150 ESPOO, FINLAND Tel. +358 20 452 3000 Fax +358 20 452 9271 VAT FI14655702 www.opuscapita.com
OpusCapita TYVI AJL 2 (24) Sisällysluettelo 1 Yleistä...3 2 Termien selitykset...3 3 Palvelun kutsuminen...3 4 Paluuviesti...4 5 Sanoman lähettäminen...5 5.1 Sisäänkirjautuminen... 6 5.2 Autentikoinnin vastausviestin lukeminen... 7 5.3 Ilmoitettavan yrityksen lisääminen... 8 5.4 Tiedoston lähetys... 9 5.5 Tiedonsiirron paluuviestin lukeminen... 10 5.6 Tiedoston noutaminen... 12 5.7 Hakukomennon paluuviestin lukeminen... 13 5.8 Saapuvan aineiston lataus... 13 5.9 Katso-kirjautuminen... 14 5.10 Katso-kirjautumisviestin lukeminen... 15 5.11 Katso- ja Raksi-välilehden listaaminen... 16 5.12 Katso- ja Raksi-välilehden listauksen vastauksen lukeminen... 16 5.13 Katso- ja Raksi-ilmoituksen lähettäminen... 17 5.14 Katso- ja Raksi-ilmoituksen lähetyksen vastauksen lukeminen... 17 5.15 Uloskirjautuminen palvelusta... 18 5.16 Vastausviesti ja yhteyden katkaisu... 18 6 Testaamiseen liittyviä huomioita...18 7 Uudet ominaisuudet versiossa 2.2...20 8 Viitteet...22 9 Versiohistoria...22
OpusCapita TYVI AJL 3 (24) 1 YLEISTÄ Tämä dokumentti kuvaa OpusCapitan ohjelmistotaloille tarjoaman HTTPS-protokollaa [1] käyttävän yleisen rajapinnan ohjelmistojen integrointiin OpusCapitaTYVI-palveluun. Rajapinta tarjoaa sovellusohjelmoijalle käsitteellisen sanomaversiosta tai tyypistä riippumattoman tiedonsiirtorajapinnan OpusCapitaTYVI- palvelun kautta viranomaisille. Rajapinta tarjoaa turvallisen ja yksinkertaisen tavan siirtää aineistoa TYVI-palveluun suoraan sovelluksesta ilman että käyttäjä joutuu tekemään manuaalisia toimenpiteitä. 2 TERMIEN SELITYKSET Termi TYVI OpusCapitaTYVI Lähetyskerta Sanoma 3 PALVELUN KUTSUMINEN Selitys Tietovirrat Yritysten ja Viranomaisten Välillä OpusCapita toteuttama TYVI-palvelu Kaikki saman lähetyksen aikana yhdellä tunnuksella lähetettävät tiedot. Lähetyskerta voi sisältää 0 n sanomaa. Lähetyskerran osa. Yksi yksittäinen ilmoitus yhdelle vastaanottajalle. Esimerkiksi yksi ilmoittavan yrityksen työnantajasuoritus Verohallintoon. Kutsut palveluun tehdään käyttämällä tiettyjä ennalta määriteltyjä URL:a [2]. URL (Uniform Resource Locator) on nimensä mukaisesti osoitin resursseihin. Se on merkkijono, joka kuvaa yksiselitteisesti palvelun (järjestelmä, palvelun nimi sekä palvelun versio) johon sanoma liittyy sekä komennon, joka määrittelee millaista kutsua palveluun ollaan tekemässä. Suurin osa URL:n tiedoista on kiinteitä eri lähetyskertojen välillä samaa palvelua käytettäessä, mutta komento riippuu siitä mitä kyseisellä hetkellä tehdään. Lähetettävään sanomaan liittyvä URL on muotoa: https://konteksti/iea/palvelu/versio/komento Konteksti sisältää palvelun sijainnin (koneen nimi tai osoite sekä portti). Palvelun looginen sijainti määrää myös käytetyn järjestelmän. URL:n osa iea on kiinteä merkkijono, joka kertoo vastaanottavalle järjestelmälle, että kyseessä on ohjelmistotaloliittymä (iea tulee sanoista Interface for External Applications). Palvelu ja versio kertovat käytetyn palvelun ja sen halutun version. Komento määrittelee mitä kyseisen kutsun halutaan tekevän. Mahdolliset komennot on lueteltu allaolevassa taulukossa:
OpusCapita TYVI AJL 4 (24) Komento auth transmit terminate query add_company katso/login katso/list katso/send Kirjaudutaan sisään palveluun, paluuviestissä saadaan session tunniste, jota käytetään siirrettäessä aineistoa ja kirjauduttaessa ulos palvelusta. Siirretään aineisto palveluun, paluuviestissä saadaan sanomakohtainen tieto siirron onnistumisesta. Kirjaudutaan ulos palvelusta. Noudetaan erityyppistä aineistoa palvelusta (ei toteutettu draftversiossa) Lisätään ilmoitettava yritys Aktivoidaan Katso-tiedot nykyiseen istuntoon. Mahdollistaa Katso- ja Raksi-välilehdillä olevien ilmoitusten lähettämisen 10 minuutin aikaikkunan aikana. Tämän jälkeen tunnistautuminen Katsoon on tehtävä uudestaan. Listaa Katso-ja Raksi-välilehtien sisältämät ilmoitukset (ilmoitukset, joiden lähettämiseen vaaditaan Katso-tunnus) Lähettää halutun ilmoituksen eteenpäin Katso-tunnuksella Esimerkki: Tehdään kutsu OpusCapita TYVI-.palveluun rajapintaversiolla 2.1. Kyseessä tunnistautuminen. Itse autentikointitiedot lähetetään HTTPS:n POST-datassa eivätkä ne näy URL:ssa https://www.tyvi.fi/ec/tyvi-r5/p/iea/auth/ 4 PALUUVIESTI Lähetykseen liittyvä paluuviesti on XML-sanoma [3], jossa kerrotaan tilakoodin avulla lähetyksen onnistumisesta, viitataan lähetyksen sessiotunnisteeseen ja kerrotaan tarvittaessa sanomakohtaisesti vastaanottokuittaus tai mahdollinen virheilmoitus lähetetyistä tiedoista. Paluuviestin merkistö on UTF-8. Paluuviestin XML Schema [4] on esitetty liitteessä 1. Esimerkkejä erilaisista paluuviesteistä on kappaleessa 5. Oheisessa taulukossa on käytössä olevat tilakoodit ja niiden mukana palautuvat selitteet. Tilakoodi teksti Tarkennus 0 OK Pyyntö palveluun on onnistunut. 100 Authentication failure Annettu käyttäjätunnus tai salasana on väärä. Tarkista käyttäjätunnus ja salasana. Ota tarvittaessa yhteys helpdeskiin. 101 No active session Session tunniste ei ole oikea tai sessio on jo vanhentunut. 102 No command verb in url Palvelimelle on lähetetty pyyntö, jossa ei ole komentoosaa. 103 Internal Server Error Määrittelemätön virhetilanne palvelussa. Tilanne on luonteeltaan sellainen, että palvelu ei ole osannut käsitellä virhettä. 104 Transfer format error Lähetyssä aineiston esitystavassa on virhe ts. tiedon esitysmuoto on epävalidi. Virhe tulee myös silloin jos
OpusCapita TYVI AJL 5 (24) kyseisellä tunnuksella ei ole sallittua lähettää tällaista aineistoa. 105 Transfer content error Aineiston tietosisältö on virheellinen. 106 No data transmitted Varsinainen tietosisältö puuttuu kokonaan. 107 Transmitted data contained extraneous Ylimääräisiä rivejä sanoman lopussa. 108 109 110 lines No rights to send forms of this type Unknown or unsupported query type Invalid parameters for query 111 Duplicate file transferred 112 Unsupported protocol version 113 Authentication redirected 114 Katso ID is needed Kirjautuneella asiakkaalla ei ole oikeutta lähettää kyseistä aineistotyyppiä. Parametrin type arvo on joko tuntematon tai käyttäjällä ei ole oikeutta noutaa tyypin mukaista aineistoa Joku query-komennon parametreista on väärä tai vaihtoehtoisesti joku pakollinen parametri puuttuu. Tiedostosiirrossa on havaittu identtisen tiedoston aikaisempi siirtäminen. Asiakasohjelmiston ehdottamaa protokollaversiota ei tueta (uusi 2.1:ssä.) Sisäänkirjautuminen ei ole mahdollista tässä osoitteessa. Asiakasohjelmiston tulee käyttää kentässä <use-base> olevaa järjestelmän URL:a ja yrittää uudelleen. (uusi 2.1:ssä) Katso/send-käskyllä lähetetty ilmoitus vaatii Katsoistunnon. Istunto oli joko vanhentunut tai Katsotunnuksella ei ole riittäviä oikeuksia ilmoituksen lähettämiseen. 5 SANOMAN LÄHETTÄMINEN Lähetys tapahtuu käyttämällä HTTPS-protokollaa lomakepohjaiseen lähetykseen. Lähetys on luonteeltaan hyvin yksinkertainen. Lähetykseen liittyy tietty URL, jonka perusosa (https://fqdn) kertoo suoraan käytetyn protokollan, autentikointitiedot, palvelimen sekä portin. URL:n absoluuttinen polkuosa (perusosan jälkeinen osa mukaan lukien ensimmäinen kauttamerkki sekä kaikki parametrit) kuvaa lähetyksen palvelimen sisällä. Lähetys voidaan jakaa seuraaviin osiin: 1. Sisäänkirjautuminen palveluun. Kirjautumiseen tarvittavat tiedot välitetään HTTPS:n POST-metodilla. 2. Sisäänkirjautumisen vastausviestin lukeminen. Luetaan ja tarkastetaan palvelimen lähettämä tilakoodi, session tunniste ja muu mahdollinen informaatio. Jos vastausviestissä ilmoitetaan, että sisäänkirjautuminen tulee tehdä toisessa osoitteessa, hypätään takaisin kohtaan 1 käyttäen annettua osoitetta. 3. Tiedoston lähetys. Lähetetään tiedosto HTTPS:n POST-metodilla 4. Tiedonsiirron vastausviestin lukeminen. Luetaan ja tarkastetaan HTTP-palvelimen lähettämä siirron tilakoodi ja mahdollinen muu viestissä tuleva informaatio.
OpusCapita TYVI AJL 6 (24) 5. Mahdollisten palvelussa olevien tiedostojen noutaminen. Kerrotaan HTTPS-POSTkomennolla mitä halutaan noutaa ja samalla voidaan antaa joitain rajaavia hakuehtoja nuodettaville tiedostoille. 6. Tiedoston noutoon tarkoitettuun pyyntöön palautetaan paluuviesti, jossa on osoitin itse noudettavaan tiedostoon. Luetaan paluuviesti ja siellä oleva osoitin itse noudettavaan tiedostoon. 7. Noudetaan itse tiedosto käyttämällä paluuviestissä saatua osoitinta. Kyse on normaalista tiedostonlatauksesta HTTPS-palvelimelta. 8. Uloskirjautuminen palvelusta. Kirjaudutaan ulos ja suljetaan sessio eksplisiittisesti ennen yhteyden sulkemista. 9. Vastausviestin lukeminen. Luetaan palvelimen lähettämä tilakoodi ja tarkastetaan, että uloskirjautuminen onnistui. 5.1 Sisäänkirjautuminen Pyyntö lähetetään URL:n, jossa komento on auth, esimerkiksi https://www.tyvi.fi/ec/tyvir5/p/iea/auth/ Kutsulle voi antaa parametreina seuraavat tiedot: Pakolliset parametrit: username password software Vapaaehtoiset parametrit: protocol-version käyttäjätunnus OpusCapita TYVIpalveluun salasana OpusCapita TYVI-palveluun kirjautuvan ohjelmiston nimi ja versio Pyytää palvelinta käyttämään annettua protokollaversiota (2.0, 2.1 tai 2.2) force-redirect Ei-nolla arvo (esim 1 tai "yes") pyytää palvelinta antamaan vastauskoodin 113 "Authentication redirected" kirjautumiseen, joko asiakasohjelmiston testausta tai järjestelmän URL:n verifiointia varten. Parametrilla software on tarkoitus kertoa mikä ohjelmisto ja sen versio on kyseessä samaan tyyliin kuin www-selain lähettää www-palvelimelle user-agent parametrilla tiedon siitä mikä selain ja sen versio on kyseessä. Suositeltava muoto software parametrin arvoksi on <ohjelmisto> <versiotieto>. Esimerkiksi OpusCapitan testiohjelman tapauksessa: ElmaIEA C# DEMO $Revision: 1.6 $
OpusCapita TYVI AJL 7 (24) Esimerkki: autentikointi palvelimelle https://www.tyvi.fi käyttäjänä user123 POST /ec/tyvi-r5/p/iea/auth HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 366 Content-Disposition: form-data; name="username" user123 Content-Disposition: form-data; name="password" passwd1234 Content-Disposition: form-data; name="software" ElmaIEA C# DEMO $Revision: 1.6 $ - Huomaa, että merkkijono Boundary-string-should-not-appear-in-data on ainoastaan esimerkinomainen MIME Multipart-sanoman erotin [5] [6]. Merkkijonon tulisi olla satunnainen generoitu merkkijono, jonka sisältö on sellainen ettei sitä esiinny itse sanomalla. Esimerkkiohjelmistossa on tämä osuus toteutettu lisäämällä kiinteä merkkijono, jota ei esiinny itse sanomalla. Lisäksi kannattaa kiinnittää huomiota erottimen yhteydessä oleviin aloitus- ja lopetusmerkkeihin. Jokainen erotinmerkki alkaa kahdella viivalla -- ja viimeinen erotin päättyy lopetusmerkkiin, joka on myöskin kaksi viivaa --. Välissä olevien erottimien lopussa ei ole viivoja. 5.2 Autentikoinnin vastausviestin lukeminen Palvelu palauttaa paluuviestissä paluukoodin <status>-elementin id-attribuutin arvona, ja sessiotunnisteen <session>-elementissä. Paluukoodi on joko 0 kirjautumisen onnistuessa, 100 kirjautumisen epäonnistuessa tai 103 (Internal Server Error) jos kirjautumisen yhteydessä on tapahtunut virhetilanne, jota palvelu ei ole osannut käsitellä oikein. Kun käytetään protokollaversiota 2.1 tai suurempaa, vastaussanomassa voi olla elementti <usebase>. Tämän sisältö on järjestelmän URL:n perusosa, jota asiakasohjelmiston pitää käyttää istunnon seuraavissa pyynnöissä. <use-base> voi esiintyä kaikissa järjestelmän tuottamissa vastaussanomissa, myös muissa toiminteissa kuin sisäänkirjautumisessa. Esimerkki: paluuviestin sisältö onnistuneen kirjautumisen jälkeen: HTTPS/1.1 200 OK Transfer-Encoding: chunked Content-Type: text/xml b4 <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea"> <status id="0">ok</status> <session>aqsyoakgkljpxn3</session>
OpusCapita TYVI AJL 8 (24) <use-base>https://www.tyvi.fi/c/ec/tyvi-r5/p/iea/</use-base> </iea-response> 0 Esimerkki: epäonnistunut kirjautuminen palveluun: HTTP/1.1 200 OK Transfer-Encoding: chunked Content-Type: text/xml b4 <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea"> <status id="100">authentication failure</status> </iea-response> 0 5.3 Ilmoitettavan yrityksen lisääminen Jotta yritykselle voidaan tehdä ilmoitus, on kyseinen yritys lisättä ilmoitettavien listaan. Pakolliset parametrit s company_name company_id sessiotunniste lisättävän ilmoitettavan yrityksen/henkilön nimi lisättävän ilmoitettavan yrityksen y-tunnus tai henkilön henkilötunnus POST /ec/tyvi-r5/p/iea/add_company HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 373 Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 Content-Disposition: form-data; name="company_name" Testi Asiakas Content-Disposition: form-data; name="company_id"
OpusCapita TYVI AJL 9 (24) 1234567-1 - Vastausviesti on yksinkertaisesti ok tai virhe (ei kerättäviä tietoja varsinaisesti). Mikäli ilmoitettava yritys löytyy jo listalta, annetaan virhe 111 - Duplicate file transferred. Mikäli annettu company_id ei ole hetu tai y-tunnus, annetaan virhe 110 - Invalid parameters for query. Mikäli käyttäjällä ei ole oikeutta lisätä ilmoitettavaa, annetaan virhe 108 - No rights to send forms of this type. 5.4 Tiedoston lähetys Pyyntö lähetetään URL:n, jossa komento on transmit. esimerkiksi https://www.tyvi.fi/ec/tyvi-r5/p/iea/transmit Kutsulle voi antaa parametreina seuraavat tiedot: Pakolliset parametrit: s records Vapaaehtoiset parametrit: test sessiotunniste itse lähetettävä lähetyskerta ts. lähetettävät sanomat saa aina arvon 1, tätä parametria ei anneta ollenkaan jos kyseessä on tuotantolähetys. Huomatkaa, että testiparametria käytettäessä, aineistoa ei tallenneta kantaan ollenkaan. Esimerkki: Tiedonsiirto. Verohallinnolle menevä vuosi-ilmoitus. Palkansaajakohtainen erittely. Kirjautumisen yhteydessä on saatu URL: https://www.tyvi.fi/ec/tyvi-r5/p/iea/. POST /a/iea/transmit HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 577 Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 -- Content-Disposition: form-data; name="test" 1 Content-Disposition: form-data; name="records"; filename="tyvi-data.txt" Content-Type: application/octet-stream 000:VSPSERIE 101:0
OpusCapita TYVI AJL 10 (24) 110:P 109:2004 102:6666662-2 098:1 111:010101-XX1X 115:54217 116:10858 117:5000 135:3000 140:1200 141:6604 143:1 146:1 150:875 153:1 999:1 -- Huomiotavaa on, että lähetettävän sanoman tyyppiä ei kerrota lähetyksessä. Se päätellään lähetettävästä sanomasta. Jos sanomaa ei tunnisteta, palautetaan virheilmoitus. Aineistoa lähetettäessä kannattaa kirjautuneen käyttäjän koko lähetyskerta lähettää yhdellä transmit-kutsulla. Palvelu pystyy erottelemaan ja käsittelemään sanomalajista ja vastaanottajasta riippumatta kaikki samassa lähetyskerrassa tulleet sanomat, joten lähettävässä päässä ei ole tarvetta pilkkoa niitä useiksi lähetyksiksi. 5.5 Tiedonsiirron paluuviestin lukeminen Paluuviesti pitää sisällään vähintään paluukoodin <status>- elementin id-attribuutin arvona, session <session>-elementissä ja sanomakohtaisen kuittauksen siirretyistä sanomista <transfer>-elementin alla <record>-elementeissä. Esimerkki: Paluuviesti onnistuneesta tiedonsiirrosta testimoodissa versiossa 2.1 tai aiempi: HTTP/1.1 200 OK Transfer-Encoding: chunked Content-type: text/xml 110 <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea"> <status id="0">ok</status> <session>aqsyoakgkljpxn3</session> <use-base>https://www.tyvi.fi/c/ec/tyvi-r5/p/iea/</use-base> <transfer mode="test"> <record num="1"> <type id= vheritp >Palkansaajakohtainen erittely</type> </record> </transfer> </iea-response> 0
OpusCapita TYVI AJL 11 (24) Esimerkki: Paluuviesti onnistuneesta tiedonsiirrosta testimoodissa versiossa 2.2: HTTP/1.1 200 OK Transfer-Encoding: chunked Content-type: text/xml 110 <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/201408/iea"> <status id="0">ok</status> <session>aqsyoakgkljpxn3</session> <use-base>https://www.tyvi.fi/c/ec/tyvi-r5/p/iea/</use-base> <transfer mode="test"> <record num="1"> <type id= vheritp >Palkansaajakohtainen erittely</type> <message_id>12345678</message_id> </record> </transfer> </iea-response> Erona aiempiin versioihin, on paluusanomassa message_id -tieto, jonka avulla voidaan kohdentaa lähetetty ilmoitus välittömästi Tyvin oikeaan ilmoitusnumeroon katso/sendkäskyä varten. Jos sanomalla on ollut virheitä, tulee <record>-elementin sisällä myös sanomakohtainen virheilmoitus. Virheilmoitus palautetaan <error>-elementissä. Elementin <record> numattribuutti kertoo kyseisen sanoman järjestysnumeron siirtovaiheessa. Esimerkki: Paluuviesti virheellisestä tiedonsiirrosta testimoodissa TYVI-VAHTI-palveluun: HTTP/1.1 200 OK Transfer-Encoding: chunked Content-type: text/xml 110 <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea/"> <status id="105">transfer content error</status> <session>kq2ivnllejtou7x</session> <use-base>https://www.tyvi.fi/c/ec/tyvi-r5/p/iea/</use-base> <transfer mode="test"> <record num="1"> <type id= ym_tuotanto >Tuotanto</type> </record> <record num="2"> <type id= ym_jatevesi >Veteen johdetut paastot</type> <error id="105">no customer number</error> </record> <record num="3"> <type id= ym_ilmaanjohd > Ilmaan johdetut jatteet</type> <error id="105">invalid parameter: 369</error> </record> <record num="4"> <type id= ym_ilmaanjohd >Ilmaan johdetut jatteet</type> <error id="105">invalid parameter: 369</error>
OpusCapita TYVI AJL 12 (24) </record> <record num="5"> <type id= ym_perustied >Perustiedot</type> </record> </transfer> </iea-response> 0 5.6 Tiedoston noutaminen Tiedoston nouto on kaksiosainen tapahtuma. Ensin tehdään palveluun pyyntö, jolla määritellään mitä halutaan noutaa. Sen jälkeen paluuviestissä olleen viitteen avulla noudetaan itse aineisto toisella pyynnöllä. Aineisto merkitään noudetuksi vasta kun se on todellisuudessa haettu. Tiedoston nouto aloitetaan tekemällä pyyntö URL:n, jonka komento osa on query, esimerkiksi https://www.tyvi.fi/ec/tyvi-r5/p/iea/query Kutsulle voi antaa parametreina seuraavat tiedot: Pakolliset parametrit: S Type Year Vapaaehtoiset parametrit: Bid New Sessiotunniste Tyyppi määrittelee mitä aineistoa halutaan hakea. Esimerkiksi VK_VAST määrittelee, että haetaan verokorttien suorasiirtopyyntöjen vastauksia. Määrittelee minkä vuoden aineistoa haetaan (pakollinen jos type = VK_VAST). Y-tunnus. Määrittelee minkä yrityksen tietoja ollaan hakemassa. Jos tätä ei anneta, haetaan kaikkien yritysten tiedot, joihin hakijalla on oikeus. Saa aina arvon 0. Määritellään haetaanko myös jo kerran haetuksi merkityt aineistot. Oletus on, että haetaan vain uudet ja tällöin koko parametri kuuluu jättää pois. Esimerkki: Query-komento, jolla haetaan vuoden 2004 verokortteja. Kirjautumisen yhteydessä on saatu URL: https://tyvi.elma.fi/ec/tyvi-r5/p/iea/. POST /ec/tyvi-r5/p/iea/query HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 345
OpusCapita TYVI AJL 13 (24) Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 Content-Disposition: form-data; name="type" vk_vast Content-Disposition: form-data; name="year" 2004 Content-Disposition: form-data; name="bid" 1234567-1 5.7 Hakukomennon paluuviestin lukeminen Paluuviesti pitää sisällään paluukoodin <status>- elementin id-attribuutin arvona ja viitteen ladattavaan aineistoon <query>-elementin alla <download-token>-elementeissä. Lisäksi sanomalla tulee tieto ladattavien sanomien määrästä <query> -elementin results - attribuutin arvona. Esimerkki: Paluuviesti, jossa kerrotaan, että Verokortin suorasiirron vastauksia 12 kappaletta noudettavana. HTTPS/1.1 200 OK Transfer-Encoding: chunked Content-type: text/xml 110 <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea"> <status id="0">ok</status> <use-base>https://www.tyvi.fi/c/ec/tyvi-r5/p/iea/</use-base> <query results="12"> <type id="vk_vast" count="12">verokortin vastaus</type> <download-token>7</download-token> </query> </iea-response> 0 5.8 Saapuvan aineiston lataus Kun aineistoon on saatu viite query -komennolla voidaan aineisto lopuksi noutaa laittamalla pyyntö URL:n, jonka komento-osa on download, esimerkiksi https://www.tyvi.fi/ec/tyvi-r5/p/iea/download Kutsulle voi antaa parametreina seuraavat tiedot:
OpusCapita TYVI AJL 14 (24) Pakolliset parametrit: s token Sessiotunniste Query-komennon vastauksena saatu tiedostoviite ts. <download-token> - elementin sisältö. Esimerkki: Download -komento POST /ec/tyvi-r5/p/iea/download HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 123 Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 Content-Disposition: form-data; name="token" 7 Kutsun vastaus pitää sisällään aina kaikki vastaussanomat ja noudattaa kulloisenkin sanoman määrityksiä. Esimerkiksi verokorttien vastaussanomat ovat Verohallinnon määrittelemää rivipohjaista dataa, jossa rivierottimena on merkki #10 ns. unix-rivinvaihto. 5.9 Katso-kirjautuminen Jotta Katso-välilehdellä olevia ilmoituksia (TVR, Vero, Tulli) voi lähettää, tulee sessiossa olla tieto hyväksytystä Katso-kirjautumisesta. Tyvin ilmoituksista OTP-tunnistautumisen vaativia ilmoituksia ovat kausiveroilmoituikset sekä tuloveroilmoitukset. Näistä Katsovälilehden kautta voi lähettää vain kausiveroilmoituksia. Muille Katsoa vaativille ilmoituksille PWD on riittävä tunnistautumistaso. Pakolliset parametrit: s Sessiotunniste username Katso-kirjautumistunnus, normaalisti 6 merkkiä, esim. d27ri2. password logintype Katso-tunnuksen salasana. Joko PWD tai OTP. Jos OTP, pitää myös parametri otp antaa. Vapaaehtoiset parametrit:
OpusCapita TYVI AJL 15 (24) otp logintype ollessa OTP, seuraava käyttämättömän OTP-salasana OTPlistalta. Vaaditaan Veron kausiveroilmoituksien lähettämiseen. Esimerkki: Katso-kirjautumiskomento POST /ec/tyvi-r5/p/iea/katso/login HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 521 Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 Content-Disposition: form-data; name="username" d27ri2 Content-Disposition: form-data; name="password" katsosalasana Content-Disposition: form-data; name="logintype" OTP Content-Disposition: form-data; name="otp" 123456 5.10 Katso-kirjautumisviestin lukeminen Vastaus kertoo, kuka on kirjautunut Katsolla sovellukseen sekä milloin tunnistautuminen menee vanhaksi (deadline). Deadline ilmoitetaan GMT-aikana ja on voimassa 10 minuuttia kerrallaan. Esimerkkivastaus: HTTPS/1.1 200 OK Transfer-Encoding: chunked Content-type: text/xml <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea"> <status id="0">ok</status> <session> aqsyoakgkljpxn3</session> <use-base>https://www.tyvi.fi/a/ec/tyvi-r5/p/iea/</use-base> <deadline>2014-08-11t05:04:32.740z</deadline> <kid>d27ri2</kid> <version>katso-1.1</version> <personname>test Person </personname> <accountexpiring>false</accountexpiring>
OpusCapita TYVI AJL 16 (24) <nextotpcode>null</nextotpcode> </iea-response> 5.11 Katso- ja Raksi-välilehden listaaminen Vastaavantyylinen komento kuin query, mutta hakee kaikki Katso- ja Raksi-välilehdellä olevat ilmoitukset. Pakolliset parametrit: s sessiotunniste Esimerkki: Katso-välilehden listaaminen: POST /ec/tyvi-r5/p/iea/katso/list HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 149 Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 5.12 Katso- ja Raksi-välilehden listauksen vastauksen lukeminen Vastaus kertoo lomakkeen tunnisteen (message_id), itse lomakkeen tyypin (form), ilmoitettavan yrityksen y-tunnuksen (identifier) sekä nimen (common_name) ja mille ajalle ilmoitus kohdistuu (period). Esimerkkivastaus: HTTPS/1.1 200 OK Transfer-Encoding: chunked Content-type: text/xml <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea"> <status id="0">ok</status> <session> aqsyoakgkljpxn3</session> <use-base>https://www.tyvi.fi/a/ec/tyvi-r5/p/iea/</use-base> <forms> <form> <message_id>12345</message_id> <form>veroraksi.vsurakka</form> <identifier>1234567-1</identifier> <common_name>test Company</common_name> <period>2014-01</period>
OpusCapita TYVI AJL 17 (24) </form> </forms> </iea-response> 5.13 Katso- ja Raksi-ilmoituksen lähettäminen Tapahtuu ilmoittamalla message_id parametri katso/send-toiminnolle. Pakolliset parametrit: s message_id sessiotunniste Lähetettävän viestin tunniste, saatu katso/list-toiminnosta. Esimerkki: Raksi-ilmoituksen lähettäminen POST /ec/tyvi-r5/p/iea/katso/send HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 253 Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 Content-Disposition: form-data; name="message_id 12345 5.14 Katso- ja Raksi-ilmoituksen lähetyksen vastauksen lukeminen Onnistunut lähetys tuottaa paluuviestin, jossa status_id=0 (OK). Raksi-ilmoituksissa tulee vielä ilmoituksen Veron puolen tunniste kentässä s807. Kyseistä tunnistetta tulee käyttää mm. kyseisen lomakkeen korjausilmoituksissa. Katso-välilehteä käyttävät ilmoitukset (ei Raksi-ilmoitukset) eivät sisällä tätä kenttää. Esimerkkivastaus: HTTPS/1.1 200 OK Transfer-Encoding: chunked Content-type: text/xml <?xml version="1.0" encoding="utf-8"?> <iea-response xmlns="http://tyvi.elma.fi/schema/200710/iea"> <status id="0">ok</status> <session> aqsyoakgkljpxn3</session> <use-base> https://www.tyvi.fi/a/ec/tyvi-r5/p/iea/</use-base> <message_id>12345</message_id> <s087>v14077376774692</s087> </iea-response>
OpusCapita TYVI AJL 18 (24) 5.15 Uloskirjautuminen palvelusta Sessio tulee sulkea tiedonsiirron lopuksi. Sulkeminen tapahtuu tekemällä pyyntö URL:n, jonka komento-osa on terminate, esimerkiksi https://www.tyvi.fi/ec/tyvi-r5/p/iea/terminate Kutsulle voi antaa parametreina seuraavat tiedot: Pakolliset parametrit: s sessiotunniste Esimerkki: Uloskirjautuminen palvelusta POST /ec/tyvi-r5/p/iea/terminate HTTPS/1.1 Host: www.tyvi.fi Content-type: multipart/form-data; boundary=boundary-string-should-not-appear-in-data Content-length: 157 Content-Disposition: form-data; name="s" aqsyoakgkljpxn3 5.16 Vastausviesti ja yhteyden katkaisu Tämän jälkeen vastausviesti voidaan lukea ulkoskirjautumisesta. 6 TESTAAMISEEN LIITTYVIÄ HUOMIOITA Lähdettäessä kehittämään ja testaamaan integrointikoodia OpusCapita TYVI-palvelua vasten, seuraavat asiat tulisi huomioida. 1. Testaamiseen tarvitsette OpusCapita TYVI-testitunnuksen ja salasanan. Jos teillä ei ole tunnuksia, ottakaa yhteys OpusCapitan Service Deskiin 2. Palvelua testataan OpusCapita TYVI-tuotantopalvelimella testitunnuksin. Vaikka palvelu on tuotanto-palvelu, mikään aineisto ei siirry oikeasti eteenpäin, koska tunnukset ovat palvelussa testistatuksella. 3. Itse lähetettävän aineiston oikeellisuus kannattaa testata ennen kuin aineistoa yrittää lähettää ohjelmistointegraatiokoodilla. Hyvin usein ongelmana on joko se, että data on epävalidia tai sitä ei voi lähettää kyseiselle testitunnuksella ollenkaan. Nämä asiat on syytä tarkastaa ennen kuin testaus oman koodin kanssa aloitetaan. 4. Tyypillisesti ohjelmistotalolle annetulla testitunnuksella voi ilmoittaa ainoastaan yhden yrityksen tietoja. Tämä yritys on testaava yritys ts. ohjelmistotalo itse. Y- tunnus testiaineistossa tulisi siis olla testitunnuksen omaavan yrityksen oma y- tunnus.
OpusCapita TYVI AJL 19 (24) 5. Kun testiaineisto on oikeanlaista, kannattaa sen lähettämistä testata seuraavaksi curl-ohjelman avulla esim. curl --insecure -d "username=testitunnus&password=salasana&software=test" https://www.tyvi.fi/ec/tyvi-r5/p/iea/auth/. 6. Tämän jälkeen kannattaa aloittaa testaaminen omalla sovelluksella. Jos kehityksen ja testauksen aikana tulee ongelmia, niistä kannattaa ilmoittaa OpusCapitan Service Deskiin. Mukaan tulisi liittää mieluusti lyhyt ongelman kuvaus, testattava aineisto sekä tuloste tehdystä pyynnöstä ja palvelun antamasta vastauksesta sekä testausajankohdasta. Testauksen tukipalvelu on maksullista ja siitä veloitetaan tuntityöperusteisesti voimassa olevan hinnaston mukaisesti.
OpusCapita TYVI AJL 20 (24) 7 UUDET OMINAISUUDET VERSIOSSA 2.2 25.8.2014 Version 2.2 muutokset o Vastaussanoman XML-nimiavaruus riippuu käytetystä seuraavasti: protokollaversiosta 1. 2.0 = http://tyvi.elma.fi/schema/200411/iea 2. 2.1 = http://tyvi.elma.fi/schema/200710/iea 3. 2.2 = http://tyvi.elma.fi/schema/201408/iea o Transmit-käskyn paluusanomaan lisätty message_id -elementti ilmoitukselle. 11.8.2014 versiomuutokset (ei uutta protokollaversiota) o Katso/logi, katso/list ja katso/send käskyt lisätty. Käskyjen myötä täysi tuki Katso-lähetykselle integraatiorajapinnan läpi. Käskyt dokumentoitu kappaleessa 5. o Katso-id parametri poistettu vanhentuneena auth-käskyn parametrilistalta. o Virhekoodia 114 muutettu vastaamaan nykyistä tarkoitusta. o Lisätty add_company käsky. o Päivitetty schema-kuvaus Edeltävät 2.1 muutokset o Sisäänkirjautumisessa on kaksi uutta vapaaehtoista parametriä force-redirect ja protocol-version, jotka on dokumentoitu kappaleessa 5. o Sisäänkirjautuminen voi johtaa redirektiin o Kaksi uuttaa virhekoodia 112 ja 113 on dokumentoitu kappaleessa 4. o Vastaussanomat voivat aina sisältää tagin <use-base> o Vastaussanoman XML-nimiavaruus riippuu käytetystä seuraavasti: protokollaversiosta 1. 2.0 = http://tyvi.elma.fi/schema/200411/iea 2. 2.1 = http://tyvi.elma.fi/schema/200710/iea o Versiossa 1.2 lisätty KATSO- tunnistautumiseen liittyvät osat. 1. Sisäänkirjautumisessa uusi vapaaehtoinen parametri katso-id, joka on dokumentoitu kappaleessa 5.