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.
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.
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://netvisor.fi/isv-materiaalipankki/isv-yhteydenotto/
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 firstname.lastname@example.org.
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 email@example.com.
- 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 in firstname.lastname@example.org
- Fill in this form https://netvisor.fi/isv-materiaalipankki/isv-yhteydenotto/ to register as ISV-Partner. With the same form you can order the testing environment, needed credentials and info package.
- Login to Netvisor and get to know the test environment. You can change default settings and services.
- Create API identifiers: API identifiers
- Read the "Netvisor API Security and authentication.pdf" that you received in the email with the test credentials.
- Send a request to get customerlist -resource (customerlist.nv) to make sure the MAC-calculation and authentication is succesfull.
- If you need test material for Netvisor, use DemoDataGenerator.vb script.
- Go through our Best practice -models here (unfortunately only in Finnish at the moment)
- When you are ready, please test your implementation thoroughly.
- When you have tested the implementation, send an email to our partner support (email@example.com) to inform that the integration is ready. Describe how different resoruces are used in the integration.
- After sending the email, our partner support will validate your integration and send the needed partner credentials to be used in production environment.
- 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
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.
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.
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:
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.
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.
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?Send feedback