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.

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:

  1. Käyttäjän ohjelmistorajapintatunnukset (käyttäjätunniste id ja avain). Käyttäjän ohjelmistorajapintatunnukset luodaan Netvisorissa: https://support.netvisor.fi/fi/support/solutions/articles/77000498452-ohjelmistorajapintatunnusten-luominen
  2. 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/support/solutions/articles/77000498452-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 00: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, josta 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 headerArvo
Uri (jonne pyyntö lähetetään)https://isvapi.netvisor.fi/accounting.nv
X-Netvisor-Authentication-SenderClientName
X-Netvisor-Authentication-CustomerIdIntegration user identifier
X-Netvisor-Authentication-TimeStamp2023-05-04 00:00:00.000
X-Netvisor-Interface-LanguageFI
X-Netvisor-Organisation-ID1967543-8
X-Netvisor-Authentication-TransactionId123456
X-Netvisor-Authentication-TimestampUnix1683147600
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:
86b8f6510744913deab32da404d7668eba2a75775b3ac78c9c48bca65e0fbd27

HUOM! Jos käyttämäsi URI sisältää erikoismerkkejä tai ääkkösiä niin se tulee enkoodata ISO-8859-1 merkistöllä. Jotta MAC lasketaan oikein ja rajapinta tunnistaa sen.

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 hashlib
import random
import time
import requests
import hmac


# headers


Sender= "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())
timestamp = "2023-05-04 12:00:00.000"
timestampUnix = 1683147600
MacHashAlgorithm = "HMACSHA256"
Organisationid = "1967543-8"
URL = "https://isvapi.netvisor.fi/accounting.nv"
Language = "FI"
# TransactionID = "TRANSID"+"%0.12d" % random.randint(0,99999999)
TransactionID = "123456"


# compile the string for mac-hash
sha256string = URL + "&" + Sender + "&" + CustomerID + "&" + timestamp + "&" + Language + "&" + Organisationid + "&" + TransactionID + "&" + str(timestampUnix) + "&" + CustomerKey + "&" + PartnerKey


# encode the string to ISO-8859-1 and perform the sha256-hash
key = CustomerKey + "&" + PartnerKey
h_mac = hmac.new(bytes(key, "ISO-8859-1"), bytes(sha256string, "ISO-8859-1"), hashlib.sha256).hexdigest()


print(h_mac)


# # HTTP-headers being sent with the request
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-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
}

SHA256 autentikointi

HUOM! Tämä ohje koskee vanhaa SHA256 autentikointia! Uusissa toteutuksissa käytetään HMACSHA256 autentikointa

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,
    "X-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 = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime())
language="FI"
organisationId="0123456-7" #Netvisor environment's organisation id / business id

customerKey = "XXX"
partnerKey = "XXX"

#MAC calculation
sha256string = url+"&"+sender+"&"+customerId+"&"+timestamp+"&"+language+"&"+organisationId+"&"+transactionId+"&"+customerKey+"&"+partnerKey
h_mac = hashlib.sha256(sha256string.encode('ISO-8859-15')).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.