Contact method

The Web Service interface provided by Netvisor follows the REST model. Communication between the client application and the server takes place via HTTP requests. The API is bidirectional and transaction-based.

When importing data, the sending system forms an XML message describing the material and sends it UTF-8 encoded in the body of the HTTP request to Netvisor. The selected resource defines the type of integration transaction. In some transactions, the user receives identification information about the added material for later use.

When exporting material 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 using the parameters available for that resource. In the response, the requested transaction is presented to the user in XML format.

All responses sent by the API are in XML format and always contain a ResponseStatus element, which can be used to determine whether the request was successful. In case of an error, an error specification and error type are also provided. In a successful response, the default value inside the Status element is "OK", and in a failed response, the default value is "FAILED". For error cases, 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 environments of the interface is done using encrypted connections (HTTPS).

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

Proxy use and configuration

When configuring the proxy for use with Netvisor's integration services, ensure the following settings are applied:

Replace $host with integration.netvisor.fi.
The directive proxy_ssl_server_name on; is mandatory.

proxy_set_header Host integration.netvisor.fi;

proxy_ssl_server_name on;

HMACSHA256 authentication

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

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

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

User's api identifiers (user identifier CustomerId and user key CustomerKey). The user's api identifiers are created in Netvisor: https://support.netvisor.fi/en/articles/766837-api-identifiers
Software partner's api identifiers (partner identifier PartnerId and key PartnerKey). The software partner's api identifiers are delivered to the partner by customer service.

Note! Both sets of identifiers – the user's api identifiers (CustomerId and CustomerKey) and the software partner's identifiers (PartnerId and PartnerKey) – are always mandatory, including for self-implemented integrations. PartnerKey is included in the HMACSHA256 calculation, so without it a connection to the API cannot be established. The software partner's identifiers are delivered via Netvisor 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 side of the picture. The headers of the requests sent to the API do not include the software partner's and user's unique keys, but these are required for the HMACSHA256 calculation. The validity of the request is verified in the API using the MAC identifier formed by the HMACSHA256 calculation. The MAC identifier is calculated separately for each request sent to the API. If a request with the same transaction identifier has been sent to the API previously, the API returns 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 of type string

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 technical teams in troubleshooting situations.

X-Netvisor-Authentication-CustomerId
User identifier (CustomerId) of the customer company's api identifiers.

In a test environment, the api identifiers are created by the software partner's employee.

In production, the identifier is created by the Netvisor user of the company adopting the integration. They deliver the created api identifier and the integration user's unique key to the integration implementer or add the identifiers themselves to the integration settings.

Instructions for creating api identifiers: https://support.netvisor.fi/en/articles/766837-api-identifiers

X-Netvisor-Authentication-PartnerId
Partner identifier (PartnerId). Netvisor support creates a partner identifier (PartnerId) and key (PartnerKey) 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 12: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 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 access 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 identifier level, meaning the same identifier cannot be used for different customers.

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

X-Netvisor-Authentication-MACHashCalculationAlgorithm
To accept the HMACSHA-256 digest, this 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 the HTTP headers listed in the table below, as well as the user's api identifier key (CustomerKey) and the key delivered to the integration partner (PartnerKey). The keys are not delivered in the HTTP headers, but are used solely for MAC code calculation and verification.

The MAC code is formed by combining the information in the table into a single string in exactly the order shown in the table. The & character is added between the pieces of information. The URI part must be the same as the address to which the request is sent, including uppercase and lowercase letters. From this string, the HMACSHA256 checksum is calculated.

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 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
Integration user's unique key (CustomerKey)	7CD680E89E880553358BC07CD28B0EE2
Integration partner's unique key (PartnerKey)	7F94228D149A96B2F25E3EDAD55096E

The string is formed in the following order:
URL&Sender&CustomerId&Timestamp&Language&OrganisationId&TransactionId&TimestampUnix&CustomerKey&PartnerKey

The headers PartnerId, UseHTTPResponseStatusCodes and MACHashCalculationAlgorithm are not used in MAC calculation.

String formed from the example 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 (key for the HMAC calculation) is formed from the user's key and the partner's key in the form CustomerKey&PartnerKey:
7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E

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

NOTE! If the string used for MAC calculation contains special characters or umlauts (å, ä, ö), it must be encoded with the ISO-8859-15 character set before calculating the checksum. This applies only to MAC calculation. The body of the message is not used in MAC calculation, and the body is sent UTF-8 encoded.

Common error situations.

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

*This article has been translated using an AI-based translation tool. The contents or wording of these instructions may differ from those in other instructions or in the software.
*

API authentication