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ö
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ä ohjemistokumppaniksemme, tarjoamme muun muassa oheiset edut:

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

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.

Ohjelmistokumppanuuden eduista ja hyödyistä sekä Kumppani-tasoista löydät lisätietoa Ohjelmistokumppaneiden materiaalipankista

Mitä tarkoittaa ohjelmistokumppanuus?

Kun haluat integroida palvelusi toimimaan yhdessä Netvisorin kanssa tai haluat kehittää uutta liiketoimintaa niiden pohjalle, liity täyttämällä Visma Solutions ohjelmistokumppanuus -lomake.

Liittymällä ohjelmistokumppaniksi saat avuksesi integraatiototeutusta varten muun muassa ohjelmistodokumentaation verkkoversiona sekä oman ohjelmistotestaus- ja kehitysympäristön testausmpäristössämme. 

Mikäli sinulla on kysymyksiä ohjelmistokumppanuuden sisällöstä tai liittymisestä kumppaniksi, lähetä viestiä osoitteeseen partner.solutions@visma.com

Ohjelmistorajapinnan teknisiin toiminnallisuuksiin koskeviin kysymyksiin vastaa Netvisorin kumppanituki osoitteesta tuki.netvisor@visma.com. 

Uuden kumppanin tarkistuslista

Tavoitteenamme  on tarjota kumppaneillemme tehokas ja nopea tapa integroitavan toteutuksen testaamiseksi ja laadukkaan tuotantoon siirtymisen varmistamiseksi. Ongelmatilanteissa ota yhteys kumppanitukeen.

  1. Varmista, tarjoaako Netvisorin rajapinta mahdollisuuden integraation toteuttamiseen. Tarvittaessa voit konsultoida kumppanitukea.
  2. Valitse Sinulle sopivin kumppanuus taso. Löydät kumppaniohjelman tasot sekä lisätietoa kumppanuuden eduista ja hyödyistä Ohjelmistokumppaneiden materiaalipankista
  3. Liity kumppaniksi täyttämällä oheinen lomake. Tilaa samalla lomakkeella testitunnukset sekä testiympäristö käyttöösi. Lähetämme testiympäristöön tunnukset ja ohjeet lomakkeella ilmoitettuun sähköpostiosoitteeseen. Mikäli valitsit kumppanuustasoksi Partner, lähetämme erillisen sopimuksen Visma Signilla allekirjoitettavaksi.
  4. Kirjaudu Netvisoriin ja tutustu saamaasi testiympäristöön. Voit tarvittaessa tehdä myös muutoksia oletusasetuksiin ja palveluihin.
  5. Luo ohjelmistorajapintatunnukset ja salli integraatiota varten käyttöoikeudet rajapintaresursseihin.
  6. Lue "Tietoturva ja tunnistautuminen.pdf", jonka vastaanotit sähköpostin liitteenä samalla kun sait testitunnukset.
  7. Lähetä pyyntö asiakaslistan nouto -resurssiin (customerlist.nv) niin varmistut, että MAC-laskenta tehdään oikein ja tunnistautuminen rajapintaan onnistuu.
  8. Jos tarvitset testidataa ympäristöön, ole yhteydessä tuki.netvisor@visma.com.
  9. Käy läpi Best practise -toimintamallit täältä.
  10. Kun olet valmis testaa toteutuksesi läpikotaisesti.
  11. Testauksen jälkeen ilmoita kumppanituelle (tuki.netvisor@visma.com) integraation valmistumisesta. Kerro viestissä, miten integraatio on toteutettu resurssien osalta. 
  12. Ilmoituksen jälkeen kumppanituki validoi integraatiototeutuksen ja toimittaa tuotantoympäristössä tarvittavat kumppanitunnukset.
  13. 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.

Kumppanituki voi myös halutessanne ajaa testidataa valmiilla scriptillä tyhjään testiympäristöön. Tällöin ole yhteydessä tuki.netvisor@visma.com.

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 10-24 ja 1910 kredit

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.
MAC -laskenta:

public function getMAC()
{
  $parameters = array(
    $this->url,
    $this->sender,
    $this->customerId,
    $this->timestamp,
    $this->language,
    $this->organisationId,
    $this->transactionId,
    $this->customerKey,
    $this->partnerKey
  );
  
  $parameters = array_map("strval", $parameters);
  return hash("sha256", implode("", $parameters));
}

Lähetettävät HTTP-otsikot:

public function getAuthenticationHeaders() {

  $headers = array(
    "X-Netvisor-Authentication-Sender:"     . $this->sender,
    "X-Netvisor-Authentication-CustomerId:"   . $this->customerId,
    "X-Netvisor-Authentication-PartnerId:"     . $this->partnerId,
    "X-Netvisor-Authentication-Timestamp:"     . $this->timestamp,
    "X-Netvisor-Authentication-TransactionId:"   . $this->transactionId,    
    "X-Netvisor-Interface-Language:"       . $this->language,
    "X-Netvisor-Organisation-ID:"         . $this->organisationId,
    "Netvisor-Authentication-MAC:"         . $this->mac,
    "X-Netvisor-Authentication-MACHashCalculationAlgorithm: SHA256",
  );

  return $headers ;
}

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

#Url, where the request is sent
url = "https://isvapi.netvisor.fi/customerlist.nv"

#Give variables
sender = "ClientName"
customerId = "XXX"
partnerId = "XXX"
transactionId = "TRANSID"+"%0.12d" % random.randint(0,99999999) #Generate random TransactionId, type string
timestamp = strftime("%Y-%m-%d %H:%M:%S", gmtime())
language="FI"
organisationId="0123456-7" #Netvisor environment's organisation id / business id

customerKey = "XXX"
partnerKey = "XXX"

#MAC calculation
h_mac = hashlib.sha256(url+"&"+sender+"&"+customerId+"&"+timestamp+"&"+language+"&"+companyId+"&"+transactionId+"&"+customerKey+"&"+partnerKey).hexdigest()

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:

headers = {
"Content-Type": "text/plain",
"X-Netvisor-Authentication-Sender": sender,
"X-Netvisor-Authentication-CustomerId": customerId,
"X-Netvisor-Authentication-PartnerId": partnerId,
"X-Netvisor-Authentication-Timestamp": timestamp,
"X-Netvisor-Authentication-TransactionId": transactionId,
"X-Netvisor-Interface-Language": language,
"X-Netvisor-Organisation-Id": organisationId,
"X-Netvisor-Authentication-MAC": h_mac,
"X-Netvisor-Authentication-MACHashCalculationAlgorithm": "SHA256"
}



Oliko tästä vastauksesta apua? Kyllä Ei

Send feedback
Pahoittelut, että emme voineet auttaa. Anna palautetta, jotta voimme parantaa tätä artikkelia.