Yleistä

Netvisorin ohjelmistorajapinta (API) mahdollistaa tietojen automaattisen siirron ulkoisten järjestelmien ja Netvisorin välillä. Rajapinta on suunniteltu turvalliseksi tavaksi rakentaa integraatioita. Ohjelmistorajapinta mahdollistaa sekä aineistojen noudon Netvisorista että aineistojen tuonnin Netvisoriin. Rajapinnan tarjoamat resurssit on jaettu ylätason kategorioihin.
Yhteistä kaikille tapahtumille on:

Päivämäärät ovat ANSI–muodossa
Maakoodit ovat aina ISO 3166 –muodossa
Liitteet ovat aina Base64 -enkoodattuna XML-sanomaan
Tyhjiä elementtejä ei tarvitse kirjoittaa XML-sanomaan, esimerkiksi päivityspyynnössä tyhjä elementti tulkitaan rajapinnassa käskyksi päivittää arvo tyhjäksi
Pakollisia kenttiä ei tule jättää tyhjäksi
Elementtien täytyy olla DTD:n mukaisessa järjestyksessä

Skandinaavisten kirjainten (Ä, ä, Ö, ö tai Å, å) saamiseksi käyttöliittymään on sanoman oltava ISO/IEC 8859-15-enkoodatussa muodossa, mutta xml-deklaraatiota ei kuitenkaan tarvita. Netvisorin palvelinpuoli tekee sisällölle tarvittavat esikäsittelyt, jolloin aineiston tulee aina alkaa <root>.

Suosittelemme tekemään isot haut ja tietojen siirrot virka-ajan ulkopuolella, jollei niiden siirtoon virka-aikana ole erityistä tarvetta. Tietojen siirron aiheellinen tiheys eroaa resurssi- ja käyttötapauskohtaisesti. Monissa tapauksissa siirto kerran vuorokaudessa tai kuukaudessa riittää. Voit nopeuttaa siirtoja myös sopivilla rajauksilla käyttäen resurssien parametreja.

Rajapinnan arkkitehtuuri (REST)

Netvisorin rajapintatoteutus mukailee REST-mallia (Representational State Transfer). Se on HTTP-protokollaan perustuva arkkitehtuurimalli ohjelmointirajapintojen toteuttamiseen.

Toimintaperiaate: Yksinkertaistettuna yhdellä sanomalla voi tehdä kaikki toiminnot vaihtamalla vain HTTP-metodia (esim. GET tietojen noutoon, POST tietojen tuontiin).
Resurssit: Erona puhtaaseen REST-malliin on se, että Netvisorissa jokaiselle metodille on oma resurssinsa.
URI-rakenne: Rajapinnalla on juuri-URI, jonka jatkeena on kutsuttava resurssi, esimerkiksi: https://isvapi.netvisor.fi/salesinvoice.nv

Kaksisuuntainen tiedonsiirto

Netvisorin rajapinta on kaksisuuntainen, mikä tarkoittaa, että tietoa voidaan sekä tuoda järjestelmään että noutaa sieltä.

Sanomaliikenne: Tuonnissa aineisto lähetetään XML-muodossa ja noutaessa vastaus palautuu vastaavasti XML-sanomana.
Vastaukset: Rajapinta palauttaa aina vastauksen, joka sisältää OK/FAILED status-elementin.
Toimintatapa: Netvisor on rajapinnassa aina passiivinen osapuoli (palvelin), joka vastaa sille tehtyihin pyyntöihin.
Suositus: Pyynnöt suositellaan tekemään yksi kerrallaan odottaen vastausta jokaisen kutsun välissä.

Tietoturva ja yhteys

Kaikki kommunikointi rajapinnan kanssa on suojattu nykyaikaisilla salaustekniikoilla.

Salattu yhteys: Sekä tuotanto- että testiympäristön viestintä hoidetaan aina suojatun HTTPS-yhteyden ylitse.
Tunnistautumistietojen yksisuuntainen salaus: Lähetettävät tunnistautumistiedot salataan luomalla niistä tarkistussumma. Tästä summan muodosta alkuperäisiä tunnuksia ei voida enää palauttaa takaisinpäin.

Autentikointi (Tunnistautuminen)

Rajapinta tunnistaa jokaisen pyynnön HTTP-otsikoissa (headers) olevien tietojen perusteella.

MAC-koodi: Tunnistautuminen perustuu otsikkotietoihin ja niistä laskettuun MAC-koodiin (Message Authentication Code).
Otsikoiden käyttö: Asianmukaiset otsikkotiedot tulee kirjoittaa jokaiseen HTTP-pyyntöön.
Virhetilanteet: Mikäli otsikot puuttuvat tai ne ovat virheellisiä, rajapinta palauttaa virheilmoituksen tunnistautumisen epäonnistumisesta selitteineen (AUTHENTICATION_FAILED).

Tulkintaohje

Ohessa on kuvattu integraatiorajapinnan eri merkintöjen tarkoitus ja tulkinnat.
Eri sanomien XML-rakenne on kuvattu taulukkomuotoisesti niistä kohdista sanomia, kun se on mahdollista ja loogista. XML:n rakenteellisuudesta johtuen kuvauksissa on jouduttu käyttämään esimerkiksi viittauksia ohjeistuksen eri kohtiin, jotta kokonaisuus on pysynyt selkeänä.

Rakennekuvausten perusrakenne on seuraava:
Kutsu:

Perustiedot
- Käytettävä resurssi
- GET - yleensä datan noutoa Netvisorista
- POST - yleensä datan tuontia Netvisoriin
Parametrit
- Yleensä QueryString:ssä määritettäviä, erotetaan varsinaisesta resurssista ?-merkillä ja tämän jälkeen &-merkillä
- Kaikilla resursseilla ei ole käytössään parametrejä
XML-rakenne dataa tuotaessa (POST)
- Kuvattu XML:n rakenne sekä esim. elementtien määrät ja pakollisuus

Mikäli POST-sanomalla käytetään itsesulkevia tageja, niin huomaa että näitä ei lueta ollenkan, mukaanlukien mahdolliset attribuutit. Esimerkiksi asiakaskortin elementtiä <email/> ei lueta ollenkaan, mutta <email></email> taas tyhjentää kyseisen arvon Netvisorin asiakaskortilta.

Vastaus:
Jokaiseen kutsuun vastataan XML-vastauksella, jonka rakenne vastaa suurilta osin kutsua. Sanoman yleisrakenteen voi katsoa alemmasta kappaleesta. Vastaus GET-tyyppisiin noutosanomiin sisältää resurssikohtaisen datarakenteen, joka on kuvattu kussakin resurssikuvauksessa erikseen. POST-tyyppisiin tuontisanomiin tulee sanomasta riippuen vastauksessa Replies-elementti, jonka sisällä on esim. InsertedDataIdentifier-elementti sisältäen lisätyn asian ID-arvon.

Rajapintaan lähettävät kutsut

Lähetä yksi kutsu kerrallaan ja odota vastausta ennen seuraavan kutsun lähetystä. Päällekkäiset kutsut samaan asiakasympäristöön aiheuttavat erilaisia virhetilanteita. Kutsujen aikakatkaisuksi suosittelemme vähintään 120 000 ms. Näin vältät turhat virhetilanteet.

Lokita ja seuraa rajapinnan liikennettä, mukaan lukien virheet. Integraation tekemät pyynnöt tulee tallentaa lokiin transaktiokohtaisesti. Jos ohjelmointirajapinta ei syystä tai toisesta vastaa, on suositeltavaa kokeilla yhteyttä muutaman kerran uudelleen ja tämän jälkeen pitää pidempi tauko. Virheiden hallinnan tulee tapahtua ulkoisessa järjestelmässä ja ohjelmointirajapinnan välittämä virhekuvaus on hyvä tallettaa ja näyttää sellaisenaan.

Mikäli tarvitset apua virheviestin tulkinnassa, voit olla yhteydessä kumppanitukeemme osoitteessa tuki.netvisor@visma.com.

Sanomavastaukset

Jokaiseen rajapintakutsuun vastataan vakioidulla sanomavastauksella. GET-tyyppisissä sanomissa vastaus sisältää pyydetyn datan (<resurssikohtainen elementti>) ja POST-tyyppisissä mahdollisesti tapauskohtaisen vastauksen (Replies).
Vastaussanoman yleinen rakenne:
Elementti: Root (1 ilmentymä)
Elementti: Root/ResponseStatus (1 ilmentymä)

Elementti	Muoto	Kuvaus	Esimerkki	Lisätiedot
Status	Merkkijono	Indikoi tapahtuiko kutsun käsittelyssä virhettä	OK	FAILED
Status	Merkkijono	Virhevakio ja -kuvaus		Tämä elementti vain jos FAILED tilassa. Ks. Virheden hallinta
TimeStamp	Päivämäärä	Vastauksen aikaleima	01.01.2018 12:00:00

Vastauksen tyyppi on sidoksissa dataliikenteen suuntaan:
1. Noudettaessa dataa Netvisorista
Noudettu data on omana elementtinään sanomassa:
Elementti: Root/ResponseStatus/<resurssikohtainen elementti>
2. Tuotaessa dataa Netvisoriin
Vastaus sisältää Replies-elementin ja sen sisällä tapauskohtaisesti dataa:
Elementti: Root/ResponseStatus/Replies (0-1 ilmentymä)

Elementti	Muoto	Kuvaus	Esimerkki	Lisätiedot
InsertedDataIdentifier	Merkkijono
TAI
Reply	Merkkijono

Oheiset elementit esiintyvät 0-n kertaa.

Rajapinnan palauttama virheviesti

Mikäli käsittelyssä tapahtuu virheitä, rajapinta palauttaa ResponseStatus-elementissä <Status>FAILED</Status> -merkinnän.

Esimerkki vastauksesta virheelliseen pyyntöön:

<Root>

<Status>FAILED</Status>

<Status>AUTHENTICATION_FAILED :: Integraatioavaimet eivät kelpaa. Ole hyvä ja tarkista käyttäjä- ja kumppanikohtaiset avaimet></Status>

</ResponseStatus>

</Root>

Virheviestien kategoriat

AUTHENTICATION_FAILED

Integraatiopyynnön tunnistautuminen epäonnistui. Tarkista sanoman tunnistustietojen oikeellisuus, HTTP-otsikot ja MAC-laskenta.

INVALID_DATA, INVALID_DATA_SIZE

Rajapinnalle lähetetty tieto on virheellistä tai väärän kokoista. Tarkista aineisto ja annetut parametrit.

DUPLICATE_DATA

Rajapinnalle lähetetty tieto on jo olemassa järjestelmässä. Tarkista aineisto ja annetut parametrit.

REQUEST_NOT_UNIQUE

Aineiston yksilöivä tunnus on jo käytetty. Käytä jokaisessa kutsussa yksilöllistä tunnusta.

PERIOD_LOCK

Kirjanpitokausi on lukittu eikä sille voida tuoda aineistoa.

SERVICE_ACCESS_ERROR

Ei käyttöoikeutta tai sovellus, jonka materiaalia yritetään tuoda/noutaa, ei ole käytössä.

SYSTEM_MAINTENANCE

Järjestelmässä on huoltokatko. Huoltokatkon aikana rajapintapyyntöjä ei voi lähettää.

TECHNICAL_ERROR

Muusta teknisestä virheestä sanoman käsittelyssä tapahtunut virhe. Palautesanomassa annetaan vain virhekategoria ja virheen yksilöivä tunniste ilman tarkempaa selitettä. Tekniset virheet myös lokitetaan, jolloin virhetilanteiden selvitteleminen yksilöivällä tunnisteella on mahdollista kumppanituen ja ylläpidon toimesta jälkikäteen.

Tarkemmat virheviestit löytyvät tästä ohjeesta

Rajapinnan liitteiden sallitut tiedostomuodot

ApiBatchSharedAttachments (purchaseinvoicebatch.nv, salesinvoicebatch.nv )

- Ostolaskut:

- Laskun kuva (invoiceimage): .pdf, .xml

- Laskun liitteet (otherattachment): .bmp, .csv, .doc, .docx, .emf, .exif, .gif, .gzip, .heic, .eml, .html, .ico, .jpg, .msg, .mp3, .odp, .ods, .odt, .pdf, .png, .pptx, .rtf, .tiff, .txt, .wmf, .xls, .xlsm, .xlsx, .xml, .xsl, .zip, .7z

- Max 20 MiB

- Myyntilaskut:

- (pdf) .pdf

- (finvoice) .csv, .doc, .docx, .gif, .html, .jpg, .pdf, .tiff, .txt, .xls, .xlsx, .xsl

- Max 5 MiB

ProductAttachment (product.nv)

- .bmp, .csv, .doc, .docx, .emf, .exif, .gif, .gzip, .heic, .eml, .html, .ico, .jpg, .msg, .mp3, .odp, .ods, .odt, .pdf, .png, .pptx, .rtf, .tiff, .txt, .wmf, .xls, .xlsm, .xlsx, .xml, .xsl, .zip, .7z

- Max 20 MiB

PurchaseInvoiceAttachment (purchaseinvoice.nv)

- Laskun kuva (invoiceimage): .pdf, .xml

- Max 20 MiB

SalesInvoiceAttachment (salesinvoice.nv)

- (pdf) .pdf

- (finvoice) .csv, .doc, .docx, .gif, .html, .jpg, .pdf, .tiff, .txt, .xls, .xlsx, .xsl

- Max 5 MiB

TripExpenseAttachment (tripexpense.nv)

- Max 20 MiB

VoucherAttachment (accounting.nv)

- Max 20 MiB

AccountingAttachment(accountingedit.nv)

- Max 20 MiB

Oliko tästä vastauksesta apua? Kyllä Ei

Vie osaamisesi seuraavalle tasolle ja tutustu koulutuksiimme jo tänään opi.netvisorissa!

Miten Netvisorin rajapinta toimii

Yleistä

Rajapinnan arkkitehtuuri (REST)

Kaksisuuntainen tiedonsiirto

Tietoturva ja yhteys

Autentikointi (Tunnistautuminen)

Tulkintaohje

Rajapintaan lähettävät kutsut

Sanomavastaukset

Rajapinnan palauttama virheviesti

Virheviestien kategoriat

Rajapinnan liitteiden sallitut tiedostomuodot