Tässä ohjeessa käydään läpi Netvisorin ohjelmistorajapintapalvelun käyttöperiaatteet sekä intergaation rakentamisen vaiheet Netvisorin kumppaniohjelman näkökulmasta. Kumppaniohjelman kuvaus pitää sisällään tiedon siitä, miten integraatiokumppanit voivat tilata testiympäristön sekä uuden kumppanin tarkistuslistan. Ohjelmistorajapintapalvelun käyttöperiaatteessa on kuvattu käytännöt ja menetelmät, joita tarvitaan rajapinnan kanssa kommunikointiin.

Uusille integraatiototeutuksen tekijöille
Kumppaniksi rekisteröityminen
Uuden kumppanin tarkistuslista
Testiympäristö
Ohjelmistorajapintakirjasto
Yhteydenottotapa
Tietoturva ja tunnistautuminen

Uusille integraatiototeutuksen tekijöille

Ulkoisen sovelluksen integroiminen Netvisoriin voidaan toteuttaa käyttämällä Web Service-ohjelmistorajapintapalveluamme, joka mahdollistaa kaksisuuntaisen tiedonsiirron järjestelmien välillä.

Toteuttamalla integraatioliittymän Netvisoriin ja liittymällä ISV-kumppaniohjelmaamme, tarjoamme muun muassa oheiset edut kumppaneillemme:

  • Ilmainen pääsy kumppaniohjelmaan ja vapaus liiketoimintaan
  • Hyvin dokumentoitu API ja ohjeet
  • Näkyvyys markkinapaikalla
  • Yhteisö kehitystyösi ja markkinoinnin tukena
  • Kasvava ja valmis asiakaskunta

Pääset myös osalliseksi Visma Solutions Communityymme, yhteistyö- ja kommunikointikanavaamme, jota käyttävät sekä asiakkaamme, kumppanimme että omat työntekijämme.

Visma Solutions:n Partner Communityn avoimessa yleisessä osassa yhdistyvät Ohjelmisto- eli ISV-kumppanit, Tilitoimistokumppanit ja Visma. ISV-kumppaneiden sivusto on suunnattu kaikille ohjelmistokumppaneillemme ja se on yleinen tiedotuskanava kumppanuuteen liittyvissä asioissa. Sieltä löydät myös Netvisor ISV Partner -ohjelmaan, koulutuksiin ja kaupalliseen yhteistyöhön liittyvää tietoutta.

Netvisor Developer Community on suunnattu tuki ja keskustelualueeksi kehittäjille ja teknisille henkilöille. Täällä ilmoitamme myös kaikki päivitykset Netvisorin ohjelmistorajapintaan. Tarjoamme myös mahdollisuuden rajapintaideoinnille.

Kumppaniksi rekisteröityminen

Jos haluat integroida palvelusi toimimaan yhdessä Visman SaaS-ratkaisujen kanssa tai haluat kehittää uutta liiketoimintaa niiden pohjalle, rekisteröidy Visma Solutions ohjelmistokumppanuus -lomakkeella.

Rekisteröitymällä ISV-kumppaniohjelmaamme saat avuksesi integraatiototeutusta varten muun muassa ohjelmistodokumentaation verkkoversiona, Microsoft vb.net/.NETv2 -ohjelmistorajapintakirjaston helpottamaan integraation toteutusta sekä oman ohjelmistotestaus- ja kehitysympäristön testausmpäristössämme. 

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.

Netvisorin ohjelmistokumppanuudesta vastaavat Netvisorin kumppanivastaavat ja heidät tavoittaa sähköpostitse osoitteesta isv.solutions@visma.com. Ohjelmistorajapinnan teknisiin toiminnallisuuksiin koskeviin kysymyksiin vastaa Netvisorin kumppanituki osoitteesta kumppanit.netvisor@visma.com. 

Uuden kumppanin tarkistuslista

Listauksen ideana on tarjota listaus huomioon otettavista asioista, että pääsette nopeasti ja helposti testaamaan toteutustanne sekä saattamaan sen tuotantoon. Ongelmatilanteissa ota yhteys kumppanitukeen.

  1. Selvitä, mitä olet tekemässä ja tarjoaako rajapinta mahdollisuuden tähän. Tarvittaessa voit konsultoida kumppanitukea.
  2. Täytä ohjelmistokumppaniksi rekisteröitymislomake ja tilaa samalla lomakkeella testitunnukset sekä testiympäristö.
  3. Kirjaudu Netvisoriin ja tutustu saamaasi testiympäristöön. Voit tarvittaessa tehdä myös muutoksia oletusasetuksiin ja palveluihin.
  4. Luo ohjelmistorajapintatunnukset.
  5. Lue "Tietoturva ja tunnistautuminen.pdf", jonka vastaanotit sähköpostin liitteenä samalla kun sait testitunnukset.
  6. Lähetä pyyntö asiakaslistan nouto -resurssiin (customerlist.nv) niin varmistut, että MAC-laskenta tehdään oikein ja tunnistautuminen rajapintaan onnistuu.
  7. Jos tarvitset testiaineistoa Netvisoriin käytä DemoDataGenerator.vb -skriptiä.
  8. Käy läpi Best practise -toimintamallit täältä.
  9. Kun olet valmis testaa toteutuksesi läpikotaisesti.
  10. Testauksen jälkeen täytä kumppanitietolomake tuotantotunnusten toimittamista varten. Ennen tunnusten toimittamista lähetämme kumppanisopimuksen allekirjoitettavaksi.
  11. Sopimuksen allekirjoittamisen jälkeen, saat kumppaniavaimet tuotantoon.
  12. Liittymän käyttöönottamiseksi asiakkaan Netvisorissa tarvitset ohjelmistorajapintatunnukset asiakkaalta, jotka luodaan tämän ohjeen mukaisesti. Lisäksi asiakkaan tulee aktivoida Netvisorissa ohjelmistorajapintapalvelu ja sallia liittymän käyttö Rajapintaresurssien käyttöoikeudet -näkymästä. Lue lisää ohjeesta Rajapintaresurssien käyttöoikeuksien salliminen ja poistaminen.

Testiympäristö

Tuotantoympäristö ei ole testaamista varten eli testaa kaikki toteutukset ja muutokset testiympäristössä ennen tuotantoon siirtämistä. Emme suosittele käytettävän testiympäristössä oikeaa ja sensitiivistä dataa. Testausvaiheessa on syytä kiinnittää huomiota erityisesti suorituskyvyn hallinnointiin ja tietoturvaan. 

Kun saatte tunnukset testiympäristöön niin se on täysin tyhjä. Dataa voitte luoda joko manuaalisesti käyttöliittymän kautta tai tuoda asiakkaita, tuotteita ja tositteita csv-muodossa Netvisorin sisäisten työkalujen kautta.

Mikäli teillä on mahdollisuus käyttää meidän WSClientiä, voitte hyödyntää myös NetvisorDemoDataGenerator.vb skriptiä testiaineiston generointiin.

Kyseinen skripti generoi:
- Muutamia tuotteita, asiakkaita ja toimittajia (10 kutakin)
Tilinumeron toimittajille (alkaen jollain pääpankkien alkunumerolla jolle lisätään tarkiste loppuun)
- Myyntilaskuja + niiden kirjaustositteet (10 kpl per kk * 12 kk) (porautumisessa löytyy laskulinkki)
- Ostolaskuja + niiden kirjaustositteet (10 kpl per kk * 12 kk) + jokin PDF liite
- Kirjanpidon tapahtumia useille kulutileille, kirjaus = kulutili debet AN 1910 Pankkitili Kredit
7000 – 7999 välisiä tilejä. Eli 7000 debet alv 8-22 ja 1910 kredit

Kumppanituki voi myös ajaa skriptin ympäristöönne.

Ohjelmistorajapintakirjasto

Tarjoamme käyttöön myös ohjelmistorajapintakirjaston. 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ät Visma Solutions Oy:n GitHub tililtä.

Yhteydenottotapa

Netvisorin tarjoama Web Service -ohjelmistorajapinta 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. Valittu resurssi määrittelee integraatiotapahtuman tyypin. 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-muodossa 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ä. Tämän sivun ohjeistus on tarkoitettu sen tueksi, mutta ei yksinään selitä tunnistautumisen logiikkaa. Tutustu siis ensin kohtaan: Uusille integraatiototeutuksen tekijöille

Huomioittehan, että asiakkaan tulee aina toimittaa integraation toteuttajalle ohjelmistorajapintatunnukset ja sallia rajapintaresurssit Netvisorissa, että tunnistautuminen ja aineiston siirto onnistuu.

Ohjelmistorajapinnan 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. PHP-esimerkin MAC-laskennassa userKey on kahdesti ja nämä tarkoittavat kohdeyrityksen käyttäjän ohjelmistorajapintatunnuksia.
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



Oliko tästä vastauksesta apua? Kyllä Ei

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