API-autentisering

• Yhteydenottotapa
• Tietoturva ja tunnistautuminen
• HMACSHA256 autentikointi
  • Tunnistautumisen HTTP otsikot selitteineen
  • PHP esimerkki
  • Python esimerkki
• SHA256 autentikointi

Yhteydenottotapa

Netvisorin tarjoama Web Service -programgränssnittskoder on REST–mallin mukainen. Kommunikointi asiakasohjelman ja tjänstimen välillä tapahtuu HTTP-pyynnöillä. Rajapinta on kaksisuuntainen ja transaktionpohjainen.
Tuotaessa tietoa skicka järjestelmä muodostaa material kuvaavan XML-sanoman ja skicka sen HTTP-pyynnön päällä Netvisoriin. Valittu resurssi määrittelee integraatiotransaktion tyypin. Osassa transaktionista käyttäjä saa tunnistetietoa lisätystä material myöhempää käyttöä varten.
Vietäessä material poispäin Netvisorista pyynnössä ei tarvitse skicka XML-sanomaa. Pyyntö osoitetaan haluttuun resurssiin ja rajataan tarvittaessa kyseisen resurssin mahdollistamilla parametreilla. Vastauksessa pyydetty transaktion esitetään käyttäjälle XML-muodossa. 

Kaikki rajapinnan skicka vastaukset ovat XML-muodossa ja sisältävät aina ResponseStatus –elementin, josta voidaan tulkita pyynnön onnistuminen. Virhetilanteessa välitetään myös virheförklaring ja virheen tyyppi. Onnistuneessa vastauksessa on vakiona "OK" Status-elementin sisällä ja vastaavasti virheellisessä vakiona "FAILED". Virhetilanteita varten katso erillinen virhetilanteiden hanteringohje.

Esimerkkivastaus onnistuneesta pyynnöstä:


OK
01.01.2018 12:00:00


1802

Tietoturva ja tunnistautuminen

Programgränssnittskoder tietoturva on toteutettu kahdella eri tavalla:
1. Salattu förbindelse
Kommunikointi rajapinnan tuotanto- ja testiympäristöön tehdään salattuja förbindelsejä käyttäen (HTTPS).

2. Tunnistautumistietojen yksisuuntainen salaus
Rajapintaan skicka tunnistautumistiedot salataan luomalla niistä tarkistussumma, josta alkuperäisiä tunnuksia ei voida muodostaa takaisinpäin.

HMACSHA256 autentikointi

Netvisorin rajapinta tukee maj 2025 lähtien HMACSHA256 autentikointia. Uudet integraatiot tulee toteuttaa tämän autentikoinnin mukaisesti.

Netvisorin rajapinnan tietoturva on varmistettu sekä programgränssnittskoder että jokaisen pyynnön yksilöivän tunnisteen avulla.

Jotta tietoa saadaan siirrettyä Netvisorin rajapinnan yli, tarvitaan:

1. Käyttäjän programgränssnittskoder (käyttäjätunniste id ja avain). Käyttäjän programgränssnittskoder 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 skicka pyyntöjä, tulee jokaisessa pyynnössä näkyä kuvassa listatut tunnistetiedot. HMACSHA256-arvo lasketaan käyttäen kaikkia kuvassa oikealla lueteltuja tietoja. Rajapintaan skicka pyyntöjen otsakkeissa ei ole mukana ohjelmistokumppanin ja käyttäjän yksilöiviä avaimia, nämä tarvitaan kuitenkin HMACSHA256-beräkning varten. Pyynnön oikeellisuus varmistetaan rajapinnassa HMACSHA256-beräkning  muodostettavalla MAC-tunnisteella. MAC-tunniste lasketaan erikseen jokaiselle rajapintaan skicka pyynnölle. Jos rajapintaan on skicka aiemmin pyyntö samalla transaktiontunnisteella, 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 programgränssnittskoder. Tämä on käyttäjäkohtainen tunnus.
Testiympäristössä programgränssnittskoder luo ohjelmistokumppanin arbetstagare
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.
Instruktioner programgränssnittskoder 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. januari 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 fo-nummer. Fo-nummer määrää yrityksen, johon pyynnöt kirjautuvat tai jonka tietoja haetaan. Yrityksen Netvisor-käyttäjällä, jonka programgränssnittskoder 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 skicka material käyttäen samaa tunnistetta, pyyntö avvisa 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 skicka. Koodin laskennassa käytetään kaikkia yllämainittuja HTTP-otsikoita sekä integraatiokumppanille toimitettua yksilöivää avainta ja käyttäjän programgränssnittskoder 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ö skicka mukaan lukien isot ja pienet kirjaimet.

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-15 merkistöllä. Jotta MAC lasketaan oikein ja rajapinta tunnistaa sen.

PHP esimerkki

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

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())
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-hash
sha256string = URL + "&" + Sender + "&" + CustomerID + "&" + timestamp + "&" + Language + "&" + Organisationid + "&" + TransactionID + "&" + str(timestampUnix) + "&" + CustomerKey + "&" + PartnerKey


# encode the string to ISO-8859-15 and perform the sha256-hash
key = CustomerKey + "&" + PartnerKey
h_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 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 skicka HTTP-pyyntöön. Jos kaikkia tarvittavia otsikoita ei ole annettu, rajapinta palauttaa virheen tunnistautumisen epäonnistumisesta förklaring. Tunnistautumisessa tapahtuneet virheet erottaa AUTHENTICATION_FAILED–vakiosta ennen virheförklaring.

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"
}

Hjälpte det här svaret? Ja Nej