In this instruction we take a closer look into to the fundamentals of Netvisor's Web Service Interface and setting up an integration from our Software Partner program's point of view. The description of Software Partner program tells how Software Partners can order a test environment and it also includes a check list for new partners. The fundamentals of Web Service Interface descibes the practices and methods that are needed in order to communicate with our Web Service Interface.

For new Software Partners
Registering as Software Partner
Checklist for new integration partner
Test environment
Netvisor WS Client library
Sending requests
API security and authentication

For new Software Partners

External application / service can be integrated to Netvisor by using our Web Service Interface. It enables bidirectional data transfer between two systems. When using our Web Service Interface, data transfer to and from Netvisor must be done by an active software component. Data is transferred in XML format. Web Service Interface uses REST style communication over HTTP:

  •  Request is sent by POSTing (in some rare cases only query string parameters are used) data to service address
  •  Service replies with a response containing result data for request. 

Depending on used integration resource, request and response can contain various amount of data. Communication is always done by XML payloads

Integrating external application to Netvisor and joining our ISV partner program we offer e.g. the following benefits:

  • Free partner program and freedom of business
  • Well documented API and instructions
  • Visibility on market place
  • Community to support your development and marketing
  • Growing and stable customer base

Netvisor integration partners get to join Visma Solutions Community, our cooperation and communication channel, that is used by our customers, developers and our employees.

Visma Solutions Developer Community connects our ISV (software) partners, Accounting company partners and Visma. You can discuss with developers and technical support. Developer Community is targeted for all our software partners and it is a general information channel for matters regarding software partners. We inform all updates to Netvisor API in Developer Community. Community also has information related to ISV Partner program, training and business cooperation.

Registering as a Software Partner

If you wish to integrate your service with Visma SaaS solutions or wish to develop new business based on those, register as a software partner with Visma Solutions ISV-Partner form: https://goo.gl/forms/ehK3AcCovkZYiZAC3 

To help you get started we give you Netvisor's Web Service interface online documentation and a WS Client (written by using Microsoft vb.net/.NETv2). Netvisor WS Client is a ready made library for communicating with Netvisor Web Service. It is a reference implementation where you can find examples and an implementation for sending requests, handling responses and writing authentication headers in it. You can freely modify and expand the example implementation.

Please note that the WS Client library is an example and it does not include all our interface resources. The library is no longer updated so it can include old information and it may not work as it is.

If you have any questions or you run into problems with your integration, contact Netvisor partner support by email kumppanit.netvisor@visma.com.

Checklist for new integration partner

In the list below you can find things that should be noted when you want to get started on your implementation quick and easy and efficiently get the implementation to production. If you run into problems with your integration, contact Netvisor partner support by email kumppanit.netvisor@visma.com.

  1. Find out what you are doing and check if our web service interface has the opportunity to implement that. If you need support, contact our partner support
  2. Fill in this form https://goo.gl/forms/ehK3AcCovkZYiZAC3 to register as ISV-Partner. With the same form you can order the testing environment and needed credentials.
  3. Login to Netvisor and get to know the test environment. You can change default settings and services.
  4. Create API identifiers: API identifiers
  5. Read the "Netvisor API Security and authentication.pdf" that you received in the email with the test credentials.
  6. Send a request to get customerlist -resource (customerlist.nv) to make sure the MAC-calculation and authentication is succesfull.
  7. If you need test material for Netvisor, use DemoDataGenerator.vb script.
  8. Go through our Best practice -models here (unfortunately only in Finnish at the moment)
  9. When you are ready, please test your implementation thoroughly
  10. When you have tested the implementation, fill in this form: https://goo.gl/forms/1sn8D356kNXR6Qkr1 to move it to production environment. Before providing the credentials for production environment we will send the partner agreemet to be signed
  11. After signing the partner agreement we will send the partner credentials to production environment
  12. To be able to get the implementation deployed you need the customer's Netvisor API credentials that the customer can create following this instruction: API identifiers. In addition Netvisor customer needs to activate web service interface in Netvisor and enable the integration in Rights of interface resources page. Please read more in Rights of interface resources

Test enviroment

Production environment is not meant for testing and that is why all implementations and changes should be tested in test enviroment before moving to production environment. We do not recommend testing with real or sensitive material. In testing phase performance control and information security should be paid extra attention.

When you receive the credentials for test environment, the environment doesn't have any data. You can create data manually in UI or import customers, products and vouchers in csv format using Netvisor's internal tools.

If you have the opportunity to use our WSClient, you can utilise also NetvisorDemoDataGenerator.vb script to generate test material. The script generates:

  • Few products, customers and vendors (10 each). Account number for vendors 
  • Sales invoices and their vouchers (10 each month * 12 months)
  • Purchase invoices and their vouchers (10 each month * 12 months) + some PDF attachment
  • Vouchers for multiple cost accounts, entry = cost account Debet AN 1910 Bank account Credit using accounts between 7000-7999. So 7000 debet vat 10-24 and 1910 credit

Partner support can also generate the script to your test environment.

Netvisor WS Client library

The WS Client library is meant to facilitate building the integration and it can be modified and exteded freely. The library is not a ready implementation and it does not include all Web Service Interface resources. The WS Client is no longer updated so it can include dated information and it may not work as it is.

Netvisor offers its integration partners .NET tools for using our Web Service Interface. Forming material, creating requests and handling post and get messages is executed in the library.

WS Client library can be found from Visma Solutions Oy GitHub account.

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. UserKey is shown twice in PHP excample's MAC calulation. The userKeys are the API user's API identifiers.

MAC calculation:

HTTP-headers:

Python example of MAC generation and HTTP headers using SHA256:

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:




Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.