Tiedot voidaan siirtää automaattisesti siten, että lähettävä järjestelmä tekee REST-pyynnön HTTPS-protokollalla ja välittää (POST-metodilla, Content-type: multipart/form-data) kenttinä käyttäjätunnuksen ja salasanan, sekä itse siirtotiedoston. Automatisoidussa siirrossa tulee lähettävän pään IP-osoitteen olla kiinteä ja se tulee toimittaa Vismalle yhteyden avaamista varten. Siirtoon täytyy loppuasiakkaan varata Fivaldi-käyttäjätunnus, jota ei käytetä muuhun tarkoitukseen. Käyttäjätunnus toimitetaan rajapinnan avauksen yhteydessä. Rajapinnan voi tilata Visma Fivaldin myynnistä.
Tiedoston lähetys REST-rajapinnalla
Rajapinnan käyttö vaatii lähettävältä päältä julkisen, muuttumattoman IP-osoitteen. Osoite pitää ilmoittaa [email protected] ennen rajapinnan testauksen aloittamista. Tämän jälkeen voidaan tehdä REST-pyyntö, jossa on seuraavat parametrit:
p_filename | tiedosto |
p_username | käyttäjätunnus, huomioi iso ja pienet kirjaimet! |
p_password | salasana |
p_yt | Fivaldi-yritystunnus, jota vasten lähetyksen käyttöoikeus tarkistetaan (tarkistus erikseen myös aineiston sisällön perusteella) |
Sivupyynnön tulee olla multipart/form-data-muodossa, eli jokainen kenttä/tiedoston sisältö erotellaan boundary-määrityksen mukaisella rivillä. Kenttiä ei siis URL-enkoodata yhdeksi riviksi.
Tekstimuotoisessa paluusanomassa on kolme kenttää, joista kaksi ensimmäistä ovat kokonaislukuja ja tulkitaan välilyönnein erotettuna: <virhekoodi> <tiedoston koko tavuina> <selväkielinen ilmoitus> Esim. "0 12123 ok".
"Selväkielinen ilmoitus" voi olla useampirivinen ja sisältää välilyöntejä. Tiedoston koko tavuina on Fivaldin vastaanottaman tiedoston koko. Virhekoodi on 0 jos luku onnistui, < 0 jos tietokannan ilmoittama virhe (esim. parsiminen ei onnistunut) tai > 0 jos jokin liittymän havaitsema ongelma esim. käyttöoikeuksissa.
Nollasta poikkeavista virhekoodeista on hyvä tarkistaa/raportoida arvo 2, tämä tarkoittaa väärää käyttäjätunnusta ja salasanaa. Jokainen kirjautumisyritys väärällä salasanalla lasketaan ja viiden virheellisen yhteydenoton jälkeen tunnus lukitaan. Joissain tilanteissa voi siis syntyä tilanne, että liittymä lakkaa toimimasta vaikka tunnus ja salasana ovat oikein. Tällöin pääkäyttäjä voi vapauttaa tunnuksen lukittu-tilasta Palvelunhallinnassa.
jossa X on ohjeen XML-siirron käyttöönotto mukainen asiakaskohtainen skeemanumero 1-6.
Visma Fivaldilla ei ole tarjota ratkaisua siirron vastapään toteuttamiseen. Yksi valmis ratkaisu siirron toteuttamiseen skriptikielissä on käyttää melko vapaasti (~MIT) lisensoitua curl-nimistä ohjelmaa. Se tulee valmiina useimmissa Linux-jakeluissa ja sen saa myös muihin ympäristöihin. Esimerkki miten tällä tehtäisiin siirto, jos kone on luotettu (komentorivillä/prosessitaulussa muille näkyvä salasana ei ole ongelma):
curl https://asp.fivaldi.net/pls/fv00X/xml_web.sisaanluku -Fp_username=fvdemo-xxx -Fp_password=salasana -Fp_yt=123456 [email protected]
Jos tätä käytetään oikeasti, ei salasanaa pitäisi antaa komentoriville, vaan kirjoittaa argumentit tiedostoon ja lukea ne -K-vivulla.
Tiedoston nouto REST-rajapinnalla
Rajapinnan käyttö vaatii noutavalta päältä julkisen, muuttumattoman IP-osoitteen. Osoite pitää ilmoittaa Vismalle ennen rajapinnan testauksen aloittamista. Tämän jälkeen voidaan tehdä REST-pyyntö, jossa ovat seuraavat parametrit:
p_username | käyttäjätunnus |
p_password | salasana |
p_yt | yritystunnus |
Yritysrekisteri:
p_yrek | haetaanko yritysrekisteri, arvoina 1 = noudetaan kaikki tai 2 = noudetaan annetun päivämäärän jälkeen muutetut, tyhjä tai puuttuu = ei haeta |
p_yrekpvm | päiväys jonka jälkeiset haetaan, muoto YYYYMMDDHH24MISS tai DD.MM.YYYY |
Tuoterekisteri:
p_tuoterek | haetaanko tuoterekisteri, arvoina 1 = noudetaan kaikki tai 2 = noudetaan annetun päivämäärän jälkeen muutetut, tyhjä tai puuttuu = ei haeta |
p_tuoterekpvm | päiväys jonka jälkeiset haetaan, muoto YYYYMMDDHH24MISS tai DD.MM.YYYY |
Myyntitilaukset:
p_mtil | haetaanko myyntitilaukset, arvoina 1 = noudetaan kaikki tai 2 = noudetaan annetun päivämäärän jälkeen muutetut, tyhjä tai puuttuu = ei haeta |
p_mtilpvm | päiväys jonka jälkeiset haetaan, muoto YYYYMMDDHH24MISS tai DD.MM.YYYY |
Myyntihistoria:
p_mhist | haetaanko myyntihistoria, arvoina 1 = noudetaan kaikki tai 2 = noudetaan annetun päivämäärän jälkeen kirjatut, tyhjä tai puuttuu = ei haeta |
p_mhistpvm | päiväys jonka jälkeiset haetaan, muoto YYYYMMDDHH24MISS tai DD.MM.YYYY |
Tietyn projektin/seurantakohteen tapahtumat kirjanpidossa:
p_skarvo | haetaanko seurantakohteen kirjaukset, haetaan jos arvo annettu, muuten ei |
p_sknro | seurantakohdetaso (1-4) jolta edellinen rajaava arvo on |
p_skpvm | päiväys jonka jälkeiset haetaan, muoto YYYYMMDDHH24MISS tai DD.MM.YYYY, tyhjä = kaikki |
Kirjanpidon kaikki viennit:
p_skpvm | tositteen päiväys jonka jälkeiset haetaan, muoto DD.MM.YYYY, pakollinen |
Kiinteistöhallinnon tiedot
p_kh | haetaanko kiinteistöhallinto, arvoina 1 = noudetaan kaikki tai 2 = noudetaan annetun päivämäärän jälkeen muutetut, tyhjä tai puuttuu = ei haeta |
p_khpvm | päiväys jonka jälkeiset haetaan, muoto YYYYMMDDHH24MISS tai DD.MM.YYYY |
Paluusanoma on Fivaldin XML-skeeman mukainen.
Osoite aineiston noutoon on https://asp.fivaldi.net/pls/fv00X/xml_web.aineisto_ulos
jossa X on asiakaskohtainen skeemanumero 1-6, jonka voit tarkistaa ohjeesta XML-siirron käyttöönotto.
Paluusanoma on joko virheilmoitus muotoa
<virhekoodi> 0 <selväkielinen ilmoitus> Esim. "3 0 Ei oikeutta aineiston vastaanottoon".
Onnistuneessa siirrossa XML-tiedosto joka alkaa < -merkillä.