API authentication : Netvisor

Contact method
API security and authentication
HMACSHA256 authentication
SHA256 authentication

Contact method

The Web Service Interface provided by Netvisor follows the REST model. Communication between the client application and the server occurs through HTTP requests. The API is bidirectional and event-based.
When importing data, the sending system forms an XML message describing the material and sends it over an HTTP request to Netvisor. The selected resource defines the type of integration transaction. In some transactions, the user receives identification information of the added material for later use.
When exporting material away from Netvisor, there is no need to send an XML message in the request. The request is directed to the desired resource and, if necessary, limited by the parameters enabled by that resource. The requested transaction is presented to the user in XML format in the response.

All responses sent by the interface are in XML format and always contain a ResponseStatus element, which can be used to interpret the success of the request. In case of an error, an error specification and error type are also provided. In a successful response, the default is "OK" inside the Status element, and in a failed response, the default is "FAILED". For error situations, see the separate error management guide.

Example response of a successful request:
<Root>
<ResponseStatus>
<Status>OK</Status>
<TimeStamp>01.01.2018 12:00:00</TimeStamp>
</ResponseStatus>
<Replies>
<InsertedDataIdentifier>1802</InsertedDataIdentifier>
</Replies>
</Root>

API security and authentication

The security of the API is implemented in two different ways:

1. Encrypted connection
Communication to the production and test environment of the integration service is done using encrypted connections (HTTPS).

2. Unidirectional encryption of authentication information
The authentication information sent to the integration service is encrypted by creating a checksum from them, from which the original credentials cannot be reconstructed backwards.

HMACSHA256 authentication

Netvisor's API supports HMACSHA256 authentication starting from May 2025. New integrations should be implemented according to this authentication.

The security of Netvisor's API is ensured by both the API identifiers and the unique identifier for each request.

To transfer data over Netvisor's interface, the following are required:

User's software interface api identifiers (user ID and key). User's software interface api identifiers are created in Netvisor: https://support.netvisor.fi/en/support/solutions/articles/77000498452-api-identifiers
Software partner's interface api identifiers (partner ID and key). Software partner's interface api identifiers are delivered to the partner by customer service.

When requests are sent to the Netvisor API, each request must include the identifiers listed in the picture. The HMACSHA256 value is calculated using all the information listed on the right of the picture. The headers of the requests sent to the API do not include the software partner and user keys, but these are required for the HMACSHA256 calculation. The validity of the request is verified at the API by the MAC identifier generated by the HMACSHA256 calculation. The MAC identifier is calculated separately for each request sent to the interface. If a request with the same transaction identifier has been sent to the interface before, API will return an error.

HTTP headers with descriptions

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
All headers must be string type

X-Netvisor-Authentication-Sender
Free-form name of the integration. If the partner has multiple systems connected to Netvisor, each integration must be uniquely named. This information helps Netvisor support and technology in troubleshooting situations.

X-Netvisor-Authentication-CustomerId
API identifier's user id of the customer company user. This is a user-specific identifier.
In a test environment this is usually created by an integration partner. In production, the identifier is created by the Netvisor user of the company adopting the integration. They deliver the created API identifier's user id and key of the integration user to the integration implementer or add the identifiers themselves to the integration settings.
Instructions for creating user's API identifiers: https://support.netvisor.fi/en/support/solutions/articles/77000498452-api-identifiers

X-Netvisor-Authentication-PartnerId
Identifier of an integration partner. Netvisor support creates a partner id and key for each integration. The identifiers are delivered to the partner via email. If the partner has multiple systems connected to Netvisor, separate partner identifiers are created for each integration.

X-Netvisor-Authentication-Timestamp
Timestamp of the integration request in ANSI format with time, GMT+0. For example, 2023-05-04 00:00:00.000

X-Netvisor-Authentication-TimestampUnix
Timestamp of the request in UNIX format in UTC time. In other words, the number of seconds elapsed since January 1, 1970. For example, 1744635366.

X-Netvisor-Interface-Language
Language information for the API. Language support for response messages, mainly affecting error messages. The information must be in ISO-3166 format. Language options are FI/SE/EN.

X-Netvisor-Organisation-ID
Business ID (y-tunnus in Finnish) of the target company. The business ID determines the company to which requests are logged or whose information is retrieved. The Netvisor user of the company whose API identifiers are used in the integration must have rights to this company.

X-Netvisor-Authentication-TransactionId
Unique identifier of the request, GUID (Globally Unique Identifier). The value must be different in each request. If data has been previously sent using the same identifier, the request is rejected and a REQUEST_NOT_UNIQUE error is returned. The identifier is checked at the partner id level, meaning the same identifier cannot be used for different customers.

X-Netvisor-Authentication-UseHTTPResponseStatusCodes
Enables the use of correct status codes in interface responses. The value is set to 1.

X-Netvisor-Authentication-MACHashCalculationAlgorithm
To accept the HMACSHA-256 digest, the information must be provided in the headers. The value is set to HMACSHA256.

X-Netvisor-Authentication-MAC
The MAC code verifies the sender of the request. The calculation of the code uses all the above-mentioned HTTP headers as well as the unique key provided to the integration partner and the unique key of the user's API identifier. The keys of the identifiers are not delivered in the HTTP headers. They are used solely for MAC code calculation and verification. The MAC code is formed by combining the information in the table below into a single string, from which the HMACSHA256 checksum is calculated. When combining the information, the & character is used between the data; the URI part must be the same where the request is sent, including uppercase and lowercase letters.

HTTP header	Value
Uri (where the request is sent)	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 00:00:00.000
X-Netvisor-Interface-Language	FI
X-Netvisor-Organisation-ID	1967543-8
X-Netvisor-Authentication-TransactionId	123456
X-Netvisor-Authentication-TimestampUnix	1683147600
Integration user's unique key (userkey)	7cd680e89e880553358bc07cd28b0ee2
Integration partner's unique key (partnerkey)	7f94228d149a96b2f25e3edad55096e

String formed from the information:
https://isvapi.netvisor.fi/accounting.nv&ClientName&Integration user identifier&2023-05-04 12:00:00.000&FI&1967543-8&123456&1683147600&7cd680e89e880553358bc07cd28b0ee2&7f94228d149a96b2f25e3edad55096e

Additionally, the secrets parameter is formed from the Integration user's unique key and the Integration partner's unique key:
7cd680e89e880553358bc07cd28b0ee2&7f94228d149a96b2f25e3edad55096e

By calculating the HMACSHA256 checksum from the strings, the MAC code is:
86b8f6510744913deab32da404d7668eba2a75775b3ac78c9c48bca65e0fbd27

NOTE! If the URI you are using contains special characters or umlauts (å,ä,ö), it must be encoded with the ISO-8859-1 character set. To ensure the MAC is calculated correctly and recognized by the API.

PHP example

PHP-example for MAC code and HTTP headers formation:

<?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 example

Python example for MAC code and HTTP headers formation:

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 authentication

NOTE! This instruction is for the old SHA256 authentication! New implementations will use HMACSHA256 authentication.

Authentication
The interface identifies the integration request based on the header information in the HTTP headers and the MAC code calculated from them. The client application must write all headers to each HTTP request it sends. If all necessary headers are not provided, the interface returns an error with a description of the failed authentication. Errors in authentication are distinguished by the AUTHENTICATION_FAILED constant before the error specification.

Interface resources must be allowed in the target company for the requests to be permitted.

PHP-example for MAC code and HTTP headers formation.
MAC calculation:

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 headers to be sent:

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 example for MAC code and HTTP headers formation
MAC calculation using 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()

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

Did you find it helpful? Yes No