API authentication

Sending requests

Web Service Interface uses REST style communication over HTTP. The interface is bidirectional and transaction based. 

When importing data the importing system forms an XML-message of the data. The message is sent over HTTP request to Netvisor. The request is addressed to the right resource depending on the event. In some resources, Netvisor API returns identification information to be used later.

When retreiving information from Netvisor no XML-message is sent. The request is addressed to the right resouce and defined with the parameters in use if needed. The response is shown in XML.

All responses are in XML and they always include ResponseStatus -element, that can be used for defining if the request was successfull. In case the message fails, an error is returned with error description and error type. When the message is successfull the ResponseStatus -element is "OK" and if the message fails the ResponseStatus -element is "FAILED". In case of errors, please see the separate instrucion for controlling errors.

Example response of a successfull 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

You get more detailed documentation of API security and authentication when you register as Netvisor Software Partner and our partner support delivers the test environment information. This page is meant to support that documentation but it doesn't itself explain the logic of Netvisor authentication. See our instruction For new Software Partners first.

Please note, that the end customer should always deliver API identifiers for Softeware partners and allow Web Service Interface resources in Netvisor in order for authentication and data transfer to work.

The API security is excecuted in two different ways:

1. Encrypted connection
The communication to production and test environment is done using encrypted connections (HTTPS).

2. Authentication identifier unidirectional encryption
The authentication credentials are encrypted by creating a check sum. The check sum can not be calculated backwards to figure out original credentials.

Authentication

Netvisor Web Service Interface identifies the integration request according to the header information given in the HTTP-headers and from the MAC check sum calculated from the headers. The client has to write all headers to every HTTP-request. If all headers are not given, the Web Service Interface returns an error of failed authentication with definition. The errors concerning authentication can be distinguished from the AUTHENTICATION_FAILED constant before the error definition.

Rights of Interface Resources must be enabled in the target company in order for the requests to be allowed.

Here's a PHP example for calculating MAC and forming HTTP-headers. The userKeys are the API user's API identifiers.

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

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 of MAC generation and HTTP headers 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()

The HTTP-headers that are sent. Note the header MACHashCalculationAlgorithm and its value "SHA256" as string is needed in order for the MAC calculation to be approved:

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