Kaksisuuntainen rajapintapalvelu
Ohjelmistorajapintapalvelun käyttöperiaate
Yhteydenottotapa
Tietoturva ja tunnistautuminen
Virhetilanteiden hallinta
Esimerkkejä virheviesteistä
Sanomavastaukset
Resurssit
Ohjelmistorajapintakirjasto

 

Kaksisuuntainen rajapintapalvelu

Kaksisuuntainen ohjelmistorajapintapalvelu mahdollistaa asiakkaan järjestelmän liittämisen Netvisoriin modernilla tavalla. Käytettävissä olevat resurssit on listattu täällä: ResurssitNetvisorAPI_kuva.jpgLiittymä soveltuu pienien ja suurien järjestelmien liittämiseksi. Järjestelmään voidaan välittää liittymän kautta Netvisorin tukemia tietoja:

  • Myyntilaskuja
  • Ostolaskuja
  • Ostotilauksia
  • Tuotteita
  • Asiakkaita
  • Kirjanpidon tositteita
  • Maksutoimeksiantoja
  • Palkanlaskennan palkkaperusteita
  • Resurssienhallinnan työaikakirjaustietoja

Järjestelmästä voidaan hakea liittymän kautta tietoja:

  • Suorituksia
  • Pankkitapahtumia
  • Asiakkaita
  • Ostotilauksia
  • Tuotteita
  • Laskuja ja laskujen saldoja
  • Kirjanpidon tietoja (laskentakohteittain)

Järjestelmään voidaan liittää rajapinnan avulla esim. seuraavia järjestelmiä:

  • Verkkokauppoja
  • Toiminnanohjausjärjestelmiä
  • Kellokortti- / työajankirjausjärjestelmiä
  • Laskutusjärjestelmiä
  • Projektinhallinnan järjestelmiä

Ohjelmistorajapintapalvelun käyttöperiaate
Ohjelmistorajapintapalvelun käyttöperiaatteessa on kuvattu käytännöt ja menetelmät, joita tarvitaan rajapinnan kanssa kommunikointiin.

Yhteydenottotapa
Netvisorin tarjoama Web Service-ohjelmointirajapinta on REST–mallin mukainen. Kommunikointi asiakasohjelman ja palvelimen välillä tapahtuu HTTP-pyynnöillä. Rajapinta on kaksisuuntainen ja tapahtumapohjainen.
Tuotaessa tietoa lähettävä järjestelmä muodostaa aineistoa kuvaavan XML-sanoman ja lähettää sen HTTP-pyynnön päällä Netvisoriin. Pyyntö osoitetaan integraatiotapahtumasta riippuen oikeaan resurssiin. Osassa tapahtumista käyttäjä saa tunnistetietoa lisätystä aineistosta myöhempää käyttöä varten.
Vietäessä aineistoa poispäin Netvisorista pyynnössä ei tarvitse lähettää XML-sanomaa. Pyyntö osoitetaan haluttuun resurssiin ja rajataan tarvittaessa kyseisen resurssin mahdollistamilla parametreilla. Vastauksessa pyydetty tapahtuma esitetään käyttäjälle XML-muodossa. 

Kaikki rajapinnan lähettämät vastaukset ovat XML:nä ja sisältävät aina ResponseStatus –elementin, josta voidaan tulkita pyynnön onnistuminen. Virhetilanteessa välitetään myös virheselite ja virheen tyyppi. Onnistuneessa vastauksessa on vakiona "OK" status-elementin sisällä ja vastaavasti virheellisessä vakiona "FAILED". Virhetilanteita varten katso erillinen virhetilanteiden hallintaohje.

Esimerkkivastaus onnistuneesta pyynnöstä:
<Root>
<ResponseStatus>
<Status>OK</Status>
<TimeStamp>01.01.2018 12:00:00</TimeStamp>
</ResponseStatus>
<Replies>
<InsertedDataIdentifier>1802</InsertedDataIdentifier>
</Replies>
</Root>

Tietoturva ja tunnistautuminen

Tarkemman dokumentaation rajapintatunnistautumiseen saat Netvisorin kumppanituelta testiympäristön toimituksen yhteydessä rekisteröityessäsi Netvisorin ohjelmistokumppaniksi. Tämän sivun ohjeistus on tarkoitettu sen tueksi, mutta ei yksinään selitä tunnistautumisen logiikkaa. Tutustuthan siis ensin ohjeeseen: Uusille integraatiototeutuksen tekijöille

Ohjelmointirajapinnan tietoturva on toteutettu kahdella eri tavalla:

1. Salattu yhteys
Kommunikointi integraatiopalvelun tuotanto- ja testiympäristöön tehdään salattuja yhteyksiä käyttäen (HTTPS).

2. Tunnistautumistietojen yksisuuntainen salaus
Integraatiopalveluun lähetettävät tunnistautumistiedot salataan luomalla niistä tarkistussumma, josta alkuperäisiä tunnuksia ei voida muodostaa takaisinpäin.

Tunnistautuminen
Rajapinta tunnistaa integraatiopyynnön HTTP-otsikoissa olevien otsikkotietojen ja niistä lasketun MAC-koodin perusteella. Asiakasohjelman tulee kirjoittaa kaikki otsikot jokaiseen lähettämäänsä HTTP-pyyntöön. Jos kaikkia tarvittavia otsikoita ei ole annettu, rajapinta palauttaa virheen tunnistautumisen epäonnistumisesta selitteineen. Tunnistautumisessa tapahtuneet virheet erottaa AUTHENTICATION_FAILED–vakiosta ennen virheselitettä.

Rajapintaresurssien tulee olla sallittu kohdeyrityksessä, jotta sille tulevat pyynnöt sallitaan.

PHP esimerkki MAC-koodin ja HTTP-otsikoiden muodostukseen
MAC -laskenta:

2019-09-05_11-59-38.png

Lähetettävät HTTP-otsikot:

2019-09-05_12-00-16.png

Python esimerkki MAC-koodin ja HTTP-otsikoiden muodostukseen
MAC -laskenta, SHA256 laskentaa käyttäen:Screenshot_2.png

Lähetettävät HTTP-otsikot, huomaa annettu MACHashCalculationAlgorithm otsikko ja sille arvoksi annettu "SHA256" merkkijonona,  joka vaaditaan, että SHA256 MAC-laskenta hyväksytään:

http-otsikot2.PNG

Virhetilanteiden hallinta

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 käsittelyssä tapahtuu virheitä, rajapinta palauttaa ResponseStatus-elementissä <Status>FAILED</Status> -merkinnän.

Esimerkki vastauksesta virheelliseen pyyntöön:
<Root>
<ResponseStatus>
<Status>FAILED</Status>
<Status>AUTHENTICATION_FAILED :: Integraatiokumppania ei löydy, katso dokumentaatio</Status>
<TimeStamp>01.01.2018 12:00:00</TimeStamp>
</ResponseStatus>
</Root>

Rajapinta hallitsee virhetilanteet seuraavissa eri kategorioissa:

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_MAINTANANCE
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.

Yleiset ohjeet virheviestien ilmetessä

INVALID_DATA
Luethan virheviestistä tarkemman kuvauksen virheen syystä.
Tarkistathan myös, että syntaksi on oikein:

  1. Annetut XML-elementit ovat samassa järjestyksessä kuin resurssin DTD:ssä.
  2. Kaikki pakolliset elementit on annettu.
  3. Kaikille pakollisille elementeille on annettu arvo.
  4. Kaikille tageille löytyy vastinpari.

Työaikatietojen tuonnissa:
INVALID_DATA :: Tiedon muoto virheellinen:. Palkkalajia ei löydy annetulla kohdistustiedolla.
Tarvitaan kirjauslaji, jolla on palkkalajin tuonnissa määritelty numero (esim. <CollectorRatio type="number">123</CollectorRatio> -> lisää kirjauslaji numerolla 123). Kirjauslaji voidaan tehdä käyttöliittymästä, siihen löytyy ohjeet täältä. Kun tiedot on saatu tuotua, tarkistetaan kaavat kirjauslajilta kuntoon, jotta tuo tieto tulee palkkalaskemille.
Tämän jälkeen tuonti onnistuu. Tämä kannattaa testata testiympäristössä. 

Myyntilaskun tuonnissa:
INVALID_DATA :: Tiedon muoto virheellinen:. Ei voida hakea alv-koodia tiliöintiehdotuksen takaa, koska tiliöintiehdotusta ei ole annettu.
Virhe johtuu siitä, että alv-koodia ei ole annettu laskurivillä. Tästä seuraa, että alv-koodia yritetään kaivaa tiliöintiehdotuksessa annetun tilin takaa. Koska tiliä ei ole annettu, tulee virhe. Alv-koodi on annettava laskurivillä. Oletettavasti se olisi tässä tapauksessa KOMY. Huomaathan, että lisäksi tulee määrittää myös arvo Alv:lle.
 
AUTHENTICATION_FAILED
AUTHENTICATION_FAILED :: Integraatiokumppania ei löydy, katso dokumentaatio
a) Käyttäjää ei löydy otsikon 'X-Netvisor-Authentication-CustomerId' arvolla tai se ei ole aktiivinen
b) Kumppania ei löydy otsikon 'X-Netvisor-Authentication-PartnerId' arvolla

TECHNICAL_ERROR
TECHNICAL_ERROR :: Virhe käsiteltäessä aineistoa:. Virhetunniste: 000001
Muusta teknisestä virheestä johtuen, sanoman käsittelyssä on tapahtunut virhe. Ota yhteyttä kumppanitukeen virheen selvittämistä varten

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ä)

ElementtiMuotoKuvausEsimerkkiLisätiedot
StatusMerkkijonoIndikoi tapahtuiko kutsun käsittelyssä virhettäOKFAILED
StatusMerkkijonoVirhevakio ja -kuvaus Tämä elementti vain jos FAILED tilassa. Ks. Virhetilanteiden hallinta
TimeStampPäivämäärä Vastauksen aikaleima01.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ä)

ElementtiMuotoKuvausEsimerkkiLisätiedot
InsertedDataIdentifierMerkkijono   
TAI
ReplyMerkkijono   

Oheiset elementit esiintyvät 0-n kertaa.

Netvisorin tarjoama rajapintakirjasto

Ohjelmistorajapintakirjasto on mallitoteutus, joka on tarkoitettu helpottamaan integraatiototeutuksen tekoa ja sitä saa vapaasti muokata sekä laajentaa. Ohjelmistorajapintakirjasto ei ole valmis toteutus ja siellä ei ole kaikkia rajapintaresursseja lisättynä. Rajapintakirjastoa ei enää päivitetä, joten se voi sisältää vanhentunutta tietoa, eikä se välttämättä toimi sellaisenaan.

Netvisor tarjoaa integraatiokumppaneilleen .NET-työkalut ohjelmointirajapinnan käyttöön. Kirjastossa on toteutettu eri tapahtumien aineistojen muodostukset, liittymäpyyntöjen luonti sekä lähetys ja vastaussanoman käsittely.
Ohjelmistorajapintakirjaston löydä Visma Solutions Oy:n GitHub tililtä.

 



Oliko tästä vastauksesta apua? Kyllä Ei

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.