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
Ohjelmistorajapinnan tietoturva on toteutettu kahdella eri tavalla:
1. Salattu yhteys
Kommunikointi rajapinnan tuotanto- ja testiympäristöön tehdään salattuja yhteyksiä käyttäen (HTTPS).
2. Tunnistautumistietojen yksisuuntainen salaus
Rajapintaan lähetettävät tunnistautumistiedot salataan luomalla niistä tarkistussumma, josta alkuperäisiä tunnuksia ei voida muodostaa takaisinpäin.
Proxyn käyttö ja konfigurointi
Kun konfiguroit proxyä käytettäväksi Netvisorin integraatiopalveluiden kanssa, varmista seuraavien asetusten käyttö:
Korvaa $host osoitteella integration.netvisor.fi.
Ohjaus proxy_ssl_server_name on; on pakollinen.
proxy_set_header Host integration.netvisor.fi;
proxy_ssl_server_name on;
HMACSHA256 autentikointi
Netvisorin rajapinta tukee toukokuusta 2025 lähtien HMACSHA256 autentikointia. Uudet integraatiot tulee toteuttaa tämän autentikoinnin mukaisesti.
Netvisorin rajapinnan tietoturva on varmistettu sekä ohjelmistorajapintatunnuksien että jokaisen pyynnön yksilöivän tunnisteen avulla.
Jotta tietoa saadaan siirrettyä Netvisorin rajapinnan yli, tarvitaan:
Käyttäjän ohjelmistorajapintatunnukset (käyttäjätunniste id ja avain). Käyttäjän ohjelmistorajapintatunnukset luodaan Netvisorissa: https://support.netvisor.fi/fi/articles/766837-ohjelmistorajapintatunnusten-luominen
Ohjelmistokumppanin rajapintatunnukset (kumppanitunnus id ja avain). Ohjelmistokumppanin rajapintatunnukset toimitetaan kumppanille asiakaspalvelun toimesta.
Kun Netvisorin rajapintaan lähetetään pyyntöjä, tulee jokaisessa pyynnössä näkyä kuvassa listatut tunnistetiedot. HMACSHA256-arvo lasketaan käyttäen kaikkia kuvassa oikealla lueteltuja tietoja. Rajapintaan lähetettävien pyyntöjen otsakkeissa ei ole mukana ohjelmistokumppanin ja käyttäjän yksilöiviä avaimia, nämä tarvitaan kuitenkin HMACSHA256-laskentaa varten. Pyynnön oikeellisuus varmistetaan rajapinnassa HMACSHA256-laskennalla muodostettavalla MAC-tunnisteella. MAC-tunniste lasketaan erikseen jokaiselle rajapintaan lähetettävälle pyynnölle. Jos rajapintaan on lähetetty aiemmin pyyntö samalla transaktiotunnisteella, rajapinta antaa virheen.
Tunnistautumisen HTTP otsikot selitteineen
HTTP Headers
'X-Netvisor-Authentication-Sender'
'X-Netvisor-Authentication-CustomerId'
'X-Netvisor-Authentication-PartnerId'
'X-Netvisor-Authentication-TimestampUnix'
'X-Netvisor-Authentication-Timestamp'
'X-Netvisor-Authentication-TransactionId'
'X-Netvisor-Interface-Language'
'X-Netvisor-Organisation-ID'
'X-Netvisor-Authentication-MAC'
'X-Netvisor-Authentication-MACHashCalculationAlgorithm': HMACSHA256
‘X-Netvisor-Authentication-UseHTTPResponseStatusCodes’: 1
Kaikkien otsikoiden on oltava tyyppiä string
X-Netvisor-Authentication-Sender
Integraation vapaamuotoinen nimi. Mikäli kumppanilla on useampia järjestelmiä liitettynä Netvisoriin, jokainen integraatio tulee nimetä yksiselitteisesti. Tämä tieto helpottaa Netvisorin tukea ja tekniikkaa selvitystilanteissa.
X-Netvisor-Authentication-CustomerId
Asiakasyrityksen käyttäjän ohjelmistorajapintatunnukset. Tämä on käyttäjäkohtainen tunnus.
Testiympäristössä ohjelmistorajapintatunnuksen luo ohjelmistokumppanin työntekijä
Tuotannossa tunnuksen luo integraation käyttöönsä ottavan yrityksen Netvisor-käyttäjä. Hän toimittaa luodun rajapintatunnuksen ja integraatiokäyttäjän yksilöivän avaimen integraation toteuttajalle tai lisää itse tunnukset integraation asetuksiin.
Ohjeet ohjelmistorajapintatunnusten luomiseen: https://support.netvisor.fi/fi/articles/766837-ohjelmistorajapintatunnusten-luominen
X-Netvisor-Authentication-PartnerId
Kumppanitunnus. Netvisorin tuki luo kumppanille tunnuksen ja avaimen integraatiokohtaisesti. Tunnukset toimitetaan kumppanille sähköpostitse. Mikäli kumppanilla on useampia järjestelmiä liitettynä Netvisoriin, jokaiselle integraatiolle luodaan omat kumppanitunnukset
X-Netvisor-Authentication-Timestamp
Integraatiopyynnön aikaleima ansi-muodossa kellonajan kanssa, GMT+0. Esim. 2023-05-04 12:00:00.000
X-Netvisor-Authentication-TimestampUnix
Pyynnön aikaleima UNIX-muodossa UTC-ajassa. Toisin sanoen 1. tammikuuta 1970 jälkeen kuluneiden sekuntien määrä. Esimerkiksi 1744635366.
X-Netvisor-Interface-Language
Kielitieto rajapinnalle. Vastaussanomien kielituki, joka vaikuttaa lähinnä virheviesteihin. Tiedon tulee olla ISO-3166 –muodossa. Kielivaihtoehdot ovat FI/SE/EN.
X-Netvisor-Organisation-ID
Kohdeyrityksen y-tunnus. Y-tunnus määrää yrityksen, johon pyynnöt kirjautuvat tai jonka tietoja haetaan. Yrityksen Netvisor-käyttäjällä, jonka ohjelmistorajapintatunnuksia käytetään integraatiossa, tulee olla oikeus tähän yritykseen.
X-Netvisor-Authentication-TransactionId
Pyynnön yksilöivä tunniste, GUID (Globally Unique Identifier). Arvon tulee olla jokaisessa pyynnössä eri. Jos aikaisemmin on lähetetty aineistoa käyttäen samaa tunnistetta, pyyntö hylätään ja palautetaan REQUEST_NOT_UNIQUE -virhe. Tunniste tarkistetaan kumppanitunnustasolla, eli samaa tunnistetta ei voi käyttää eri asiakkailla.
X-Netvisor-Authentication-UseHTTPResponseStatusCodes
Mahdollistaa oikeiden statuskoodien käytön rajapinnan vastauksissa. Arvoksi annetaan 1.
X-Netvisor-Authentication-MACHashCalculationAlgorithm
Jotta rajapinta ottaa vastaan HMACSHA-256 tiivisteen, tulee tieto antaa otsikoissa. Arvoksi annetaan HMACSHA256.
X-Netvisor-Authentication-MAC
MAC-koodilla tarkistetaan pyynnön lähettäjä. Koodin laskennassa käytetään kaikkia yllämainittuja HTTP-otsikoita sekä integraatiokumppanille toimitettua yksilöivää avainta ja käyttäjän ohjelmistorajapintatunnuksen yksilöivää avainta. Tunnusten avaimia ei kuitenkaan toimiteta HTTP-otsikoissa. Niitä käytetään pelkästään MAC-koodin laskentaan ja tarkastukseen. MAC-koodi muodostetaan yhdistämällä alla olevan taulukon tiedot yhdeksi merkkijonoksi joka pitää olla täysin alla olevan dokumentaation järjestyksessä. Tästä merkkijonosta lasketaan HMACSHA256-tarkistesumma. Tietoja yhdistettäessä tietojen välissä käytetään &-merkkiä; URI-osuus pitää olla sama minne pyyntö lähetetään mukaan lukien isot ja pienet kirjaimet.
HTTP header | Arvo |
Uri (jonne pyyntö lähetetään) | https://isvapi.netvisor.fi/accounting.nv |
X-Netvisor-Authentication-Sender | ClientName |
X-Netvisor-Authentication-CustomerId | Integration user identifier |
X-Netvisor-Authentication-TimeStamp | 2023-05-04 12:00:00.000 |
X-Netvisor-Interface-Language | FI |
X-Netvisor-Organisation-ID | 1967543-8 |
X-Netvisor-Authentication-TransactionId | 123456 |
X-Netvisor-Authentication-TimestampUnix | 1683147600 |
Integraatiokäyttäjän yksilöivä avain (userkey) | 7CD680E89E880553358BC07CD28B0EE2 |
Integraatiokumppanin yksilöivä avain (partnerkey) | 7F94228D149A96B2F25E3EDAD55096E |
Tiedoista muodostettu merkkijono:
https://isvapi.netvisor.fi/accounting.nv&ClientName&Integration user identifier&2023-05-04 12:00:00.000&FI&1967543-8&123456&1683147600&7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E
Lisäksi secrets parametri muodostetaan Integraatiokäyttäjän yksilöivästä avaimesta ja Integraatiokumppanin yksilöivästä avaimesta:
7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E
Laskemalla merkkijonoista HMACSHA256-tarkistesumma, saadaan MAC-koodiksi:
e920b92df2be6668b283fc03041c6aea09cdb2bf42a72d814131bb811a0e926e
HUOM! Jos merkkijono, josta MAC-laskenta tehdään, sisältää erikoismerkkejä tai ääkkösiä, tulee se enkoodata ISO-8859-15 merkistöllä.
Yleisimmät virhetilanteet:
PHP esimerkki
PHP-esimerkki MAC-koodin ja HTTP-otsikoiden muodostukseen:
<?php#MAC calculation:class MACCalculation { public $url; public $sender; public $customerId; public $timestamp; public $language; public $organisationId; public $transactionId; public $timestampUnix; public $customerKey; public $partnerKey; public function get_MAC() { $parameters = array( $this->url, $this->sender, $this->customerId, $this->timestamp, $this->language, $this->organisationId, $this->transactionId, $this->timestampUnix, $this->customerKey, $this->partnerKey ); $key = array( $this->customerKey, $this->partnerKey ); $key = array_map("strval", $key); $parameters = array_map("strval", $parameters); return hash_hmac("sha256", implode("&", $parameters), implode("&", $key)); } #HTTP headers: public function get_authentication_headers() { $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-TimestampUnix:" . $this->timestampUnix, "X-Netvisor-Authentication-TransactionId:" . $this->transactionId, "X-Netvisor-Interface-Language:" . $this->language, "X-Netvisor-Organisation-ID:" . $this->organisationId, "X-Netvisor-Authentication-UseHTTPResponseStatusCodes: 1", "X-Netvisor-Authentication-MAC:" . $this->mac, "X-Netvisor-Authentication-MACHashCalculationAlgorithm: HMACSHA256", ); return $headers; } }$mac = new MACCalculation();$mac->url = "https://isvapi.netvisor.fi/accounting.nv";$mac->sender = "ClientName";$mac->customerId = "Integration user identifier";$mac->timestamp = "2023-05-04 12:00:00.000";$mac->language = "FI";$mac->organisationId = "1967543-8";$mac->transactionId = "123456";$mac->timestampUnix = 1683147600;$mac->customerKey = "7cd680e89e880553358bc07cd28b0ee2";$mac->partnerKey = "7f94228d149a96b2f25e3edad55096e";echo $mac->get_MAC();?>
Python esimerkki
Python esimerkki MAC-koodin ja HTTP-otsikoiden muodostukseen:
import hashlibimport randomimport timeimport requestsimport hmac# headersSender= "ClientName"PartnerId = "Partner identifier"PartnerKey = "7f94228d149a96b2f25e3edad55096e"CustomerID = "Integration user identifier"CustomerKey = "7cd680e89e880553358bc07cd28b0ee2"timestampUnix = int(time.time())timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime())MacHashAlgorithm = "HMACSHA256"Organisationid = "1967543-8"URL = "https://isvapi.netvisor.fi/accounting.nv"Language = "FI"# TransactionID = "TRANSID"+"%0.12d" % random.randint(0,99999999)# compile the string for mac-hashsha256string = URL + "&" + Sender + "&" + CustomerID + "&" + timestamp + "&" + Language + "&" + Organisationid + "&" + TransactionID + "&" + str(timestampUnix) + "&" + CustomerKey + "&" + PartnerKey# encode the string to ISO-8859-15 and perform the sha256-hashkey = CustomerKey + "&" + PartnerKeyh_mac = hmac.new(bytes(key, "ISO-8859-15"), bytes(sha256string, "ISO-8859-15"), hashlib.sha256).hexdigest()print(h_mac)# # HTTP-headers being sent with the requestheaders = { "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-TimestampUnix": str(timestampUnix), "X-Netvisor-Authentication-TransactionId": TransactionID, "X-Netvisor-Interface-Language": Language, "X-Netvisor-Organisation-Id": Organisationid, "X-Netvisor-Authentication-UseHTTPResponseStatusCodes: "1", "X-Netvisor-Authentication-MAC": h_mac, "X-Netvisor-Authentication-MACHashCalculationAlgorithm": MacHashAlgorithm}