API-autentisering

• Kontaktmetod
• Datasäkerhet och autentisering
• HMACSHA256-autentisering
  • HTTP-rubriker för autentisering med förklaringar
  • PHP-exempel
  • Python-exempel
• SHA256-autentisering

Kontaktmetod

Netvisors Web Service-programgränssnitt är REST-baserat. Kommunikation mellan klientprogrammet och tjänsten sker med HTTP-anrop. Gränssnittet är tvåvägs och transaktionsbaserat.
Vid import av data skapar det sändande systemet ett XML-meddelande som beskriver materialet och skickar det ovanpå ett HTTP-anrop till Netvisor. Den valda resursen definierar typen av integrationstransaktion. I vissa transaktioner får användaren identifieringsuppgifter om det tillagda materialet för senare bruk.
Vid export av material från Netvisor behöver inget XML-meddelande skickas i anropet. Anropet riktas till önskad resurs och avgränsas vid behov med de parametrar som resursen möjliggör. I svaret presenteras den begärda transaktionen för användaren i XML-format. 

Alla svar som gränssnittet skickar är i XML-format och innehåller alltid elementet ResponseStatus, utifrån vilket man kan tolka om anropet lyckades. Vid fel förmedlas också en felförklaring och feltyp. I ett lyckat svar är standardvärdet ”OK” inne i elementet Status och i ett felaktigt svar är standardvärdet ”FAILED”. För felsituationer, se separat anvisning för hantering av felsituationer.

Exempelsvar på ett lyckat anrop:


OK
01.01.2018 12:00:00


1802

Datasäkerhet och autentisering

Programgränssnittets datasäkerhet har implementerats på två olika sätt:
1. Krypterad förbindelse
Kommunikation till gränssnittets produktions- och testmiljö sker via krypterade förbindelser (HTTPS).

2. Enkelriktad kryptering av autentiseringsuppgifter
Autentiseringsuppgifterna som skickas till gränssnittet krypteras genom att skapa en kontrollsumma av dem, från vilken de ursprungliga uppgifterna inte kan återskapas.

Användning och konfiguration av proxy

När du konfigurerar en proxy för användning med Netvisors integrationstjänster, säkerställ att följande inställningar används:

• Ersätt $host med adressen integration.netvisor.fi.
• Direktivet proxy_ssl_server_name on; är obligatoriskt.
  

proxy_set_header Host integration.netvisor.fi;

proxy_ssl_server_name on;

HMACSHA256-autentisering

Netvisors gränssnitt stöder från och med maj 2025 HMACSHA256-autentisering. Nya integrationer ska implementeras enligt denna autentisering.

Datasäkerheten i Netvisors gränssnitt säkerställs både med programgränssnittskoder och med en identifierare som är unik för varje anrop.

För att data ska kunna överföras via Netvisors gränssnitt behövs:

1. Användarens programgränssnittskoder (användaridentifierare id och nyckel). Användarens programgränssnittskoder skapas i Netvisor: https://support.netvisor.fi/fi/support/solutions/articles/77000498452-ohjelmistorajapintatunnusten-luominen
2. Programvarupartnerns gränssnittskoder (partner-id och nyckel). Programvarupartnerns gränssnittskoder levereras till partnern av kundtjänsten.

När anrop skickas till Netvisors gränssnitt ska de identifieringsuppgifter som listas i bilden synas i varje anrop. HMACSHA256-värdet beräknas med alla uppgifter som listas till höger i bilden. I rubrikerna för anrop som skickas till gränssnittet ingår inte de unika nycklarna för programvarupartnern och användaren, men de behövs för HMACSHA256-beräkning. Anropets korrekthet verifieras i gränssnittet med en MAC-identifierare som skapas med HMACSHA256-beräkning. MAC-identifieraren beräknas separat för varje anrop som skickas till gränssnittet. Om ett anrop med samma transaktionsidentifierare har skickats tidigare till gränssnittet returnerar gränssnittet ett fel.

HTTP-rubriker för autentisering med förklaringar

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
Alla rubriker ska vara av typen string

X-Netvisor-Authentication-Sender
Fritt formulerat namn på integrationen. Om partnern har flera system kopplade till Netvisor ska varje integration namnges entydigt. Denna uppgift underlättar Netvisors support och teknik vid felsökning.

X-Netvisor-Authentication-CustomerId
Kundföretagets användares programgränssnittskoder. Detta är en användarspecifik kod.
I testmiljön skapas programgränssnittskoder av programvarupartnerns arbetstagare
I produktion skapas koden av Netvisor-användaren i det företag som tar integrationen i bruk. Hen levererar den skapade gränssnittskoden och integrationsanvändarens unika nyckel till den som implementerar integrationen eller lägger själv in koderna i integrationens inställningar.
Instruktioner för att skapa programgränssnittskoder: https://support.netvisor.fi/fi/support/solutions/articles/77000498452-ohjelmistorajapintatunnusten-luominen

X-Netvisor-Authentication-PartnerId 
Partnerkod. Netvisors support skapar en kod och nyckel för partnern per integration. Koderna levereras till partnern per e-post. Om partnern har flera system kopplade till Netvisor skapas separata partnerkoder för varje integration.

X-Netvisor-Authentication-Timestamp
Tidsstämpel för integrationsanropet i ansi-format med klockslag, GMT+0. T.ex. 2023-05-04 12:00:00.000

X-Netvisor-Authentication-TimestampUnix
Tidsstämpel för anropet i UNIX-format i UTC-tid. Med andra ord antalet sekunder som förflutit efter 1. januari 1970. Till exempel 1744635366.

X-Netvisor-Interface-Language
Språkuppgift till gränssnittet. Språkstöd för svarsmeddelanden, vilket främst påverkar felmeddelanden. Uppgiften ska vara i ISO-3166-format. Språkalternativen är FI/SE/EN.

X-Netvisor-Organisation-ID
Målbolagets fo-nummer. Fo-nummer avgör vilket företag anropen registreras på eller vars uppgifter hämtas. Netvisor-användaren i företaget vars programgränssnittskoder används i integrationen måste ha rättigheter till detta företag.

X-Netvisor-Authentication-TransactionId
Unik identifierare för anropet, GUID (Globally Unique Identifier). Värdet ska vara olika i varje anrop. Om material tidigare har skickats med samma identifierare avvisas anropet och felet REQUEST_NOT_UNIQUE returneras. Identifieraren kontrolleras på partnerkodnivå, dvs. samma identifierare kan inte användas för olika kunder.

X-Netvisor-Authentication-UseHTTPResponseStatusCodes
Möjliggör användning av korrekta statuskoder i gränssnittets svar. Värdet ska vara 1.

X-Netvisor-Authentication-MACHashCalculationAlgorithm
För att gränssnittet ska ta emot en HMACSHA-256-hash måste uppgiften ges i rubrikerna. Värdet ska vara HMACSHA256.

X-Netvisor-Authentication-MAC
Med MAC-koden verifieras avsändaren av anropet. Vid beräkningen av koden används alla ovan nämnda HTTP-rubriker samt den unika nyckeln som levererats till integrationspartnern och den unika nyckeln för användarens programgränssnittskoder. Nycklarna levereras dock inte i HTTP-rubrikerna. De används enbart för beräkning och kontroll av MAC-koden. MAC-koden bildas genom att kombinera uppgifterna i tabellen nedan till en enda teckensträng som måste vara exakt i den ordning som anges i dokumentationen nedan. Från denna teckensträng beräknas HMACSHA256-kontrollsumman. När uppgifterna kombineras används tecknet & mellan uppgifterna; URI-delen måste vara densamma som den adress dit anropet skickas, inklusive stora och små bokstäver. 

Teckensträng bildad av uppgifterna:
https://isvapi.netvisor.fi/accounting.nv&ClientName&Integration user identifier&2023-05-04 12:00:00.000&FI&1967543-8&123456&1683147600&7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E

Dessutom bildas parametern secrets av den unika nyckeln för integrationsanvändaren och den unika nyckeln för integrationspartnern:
7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E

Genom att beräkna HMACSHA256-kontrollsumman av teckensträngarna fås följande MAC-kod:
86b8f6510744913deab32da404d7668eba2a75775b3ac78c9c48bca65e0fbd27

OBS! Om den URI du använder innehåller specialtecken eller nordiska tecken ska den kodas med teckenuppsättningen ISO-8859-15 för att MAC ska beräknas korrekt och gränssnittet ska känna igen den.

Vanligaste felsituationerna:

PHP-exempel

PHP-exempel för att skapa MAC-kod och HTTP-rubriker:

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-exempel

Python-exempel för att skapa MAC-kod och HTTP-rubriker:

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-autentisering

OBS! Denna anvisning gäller den gamla SHA256-autentiseringen! I nya implementationer används HMACSHA256-autentisering.

Autentisering
Gränssnittet identifierar integrationsanropet utifrån rubrikuppgifterna i HTTP-rubrikerna och den MAC-kod som beräknas av dem. Klientprogrammet ska skriva alla rubriker i varje HTTP-anrop som skickas. Om inte alla nödvändiga rubriker har angetts returnerar gränssnittet ett fel om misslyckad autentisering med förklaring. Fel som uppstår vid autentisering känns igen på konstanten AUTHENTICATION_FAILED före felförklaringen.

Gränssnittsresurserna måste vara tillåtna i målbolaget för att anrop till dem ska tillåtas.

PHP-exempel för att skapa MAC-kod och HTTP-rubriker.
MAC-beräkning:

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));
}

HTTP-rubriker som skickas:

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-exempel för att skapa MAC-kod och HTTP-rubriker
MAC-beräkning med SHA256:

#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()

HTTP-rubriker som skickas, observera rubriken MACHashCalculationAlgorithm och värdet ”SHA256” som sträng, vilket krävs för att MAC-beräkning med SHA256 ska godkännas:

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