General

The Netvisor API lets external systems exchange data with Netvisor automatically. It is a secure way to build integrations. You can use the API both to retrieve data from Netvisor and to import data to Netvisor. The API resources are grouped into main categories.

Before you start

An integration always needs external software that transfers the data between the systems. To use the API, the company needs:

• A suitable service package: The API is included in the Professional, Premium and Palkat packages. For prices, see API pricing.

• API identifiers: A Netvisor user of the company creates the API identifiers. See API identifiers.

• Access rights to API resources: The company allows the integration to use the API resources it needs. See Rights of API resources.

Our software partners have built many ready-made integrations. You can find them on the Netvisor MarketPlace. If there is no suitable integration on the MarketPlace, a developer can build a new one within the limits of the API. Visma Solutions Oy does not build or subcontract integrations.

To build a new integration, see Implementing new integration and Netvisor Software Partnership.

What data you can transfer

The API is suitable for integrating both small and large systems.

Data you can import to Netvisor

• Sales invoices

• Purchase invoices

• Purchase orders

• Products

• Customers

• Accounting vouchers

• Bank transfers

• Salary parameters for payroll

• Working hours

• Travel expense reports

Data you can retrieve from Netvisor

• Payments

• Invoice payment information

• Customers

• Purchase orders

• Products

• Invoices and invoice balances

• Accounting information (by dimensions)

Systems you can integrate

You can integrate, for example, these systems with Netvisor:

• Web shops

• ERP systems

• Timecard and work time entry systems

• Invoicing systems

• Project management systems

How the API works

REST architecture

The Netvisor API follows the REST (Representational State Transfer) model. REST is an architecture model for programming interfaces, and it is based on the HTTP protocol.

• HTTP methods: You choose the operation with the HTTP method. For example, use GET to retrieve data and POST to import data.

• Resources: Unlike in pure REST, each method in Netvisor has its own resource.

• URI structure: The API has a root URI. The resource you call follows the root URI, for example https://isvapi.netvisor.fi/salesinvoice.nv.

Two-way data transfer

The API works in both directions. You can import data to Netvisor and retrieve data from it.

• Messages: When you import data, you send it as a UTF-8 encoded XML message. When you retrieve data, the response is also an XML message.

• Responses: The API always returns a response with an OK or FAILED status.

• Roles: Netvisor is always the passive party (the server). It only responds to the requests it receives.

Security and authentication

All communication with the API is protected with modern encryption.

• Encrypted connection: All traffic to the production and test environments uses a secure HTTPS connection.

• One-way encryption of credentials: You send a checksum that is calculated from your credentials. The original credentials cannot be recovered from the checksum.

• MAC code: The API identifies each request from its HTTP headers and a MAC (Message Authentication Code) calculated from them. Include the correct headers in every request.

If the headers are missing or incorrect, the API returns the AUTHENTICATION_FAILED error. For details, see API authentication.

Message format

These rules apply to all requests:

• Dates are in ANSI format.

• Country codes are in ISO 3166 format.

• Attachments are Base64 encoded in the XML message.

• Elements must be in the same order as in the DTD of the resource.

• Do not leave mandatory elements empty.

• The XML message must always start with the <root> element. You do not need an XML declaration, because Netvisor preprocesses the content.

Character encoding

Send the message body UTF-8 encoded. This makes sure that Nordic letters (Ä, ä, Ö, ö, Å, å) and other special characters are saved correctly. Give the character set in the Content-Type header, for example Content-Type: text/plain; charset=utf-8.

Empty and self-closing elements

You do not need to include elements that you do not use. Empty elements and self-closing tags work differently in POST requests:

• Empty element: The API clears the value. For example, <email></email> clears the email address on the customer card in Netvisor.

• Self-closing tag: The API ignores the tag and its attributes. For example, <email/> is not read at all.

Sending requests

Follow these practices to avoid unnecessary errors:

• One request at a time: Wait for the response before you send the next request. Overlapping requests to the same customer environment cause errors.

• Timeout: Use a timeout of at least 120,000 ms (2 minutes).

• Logging: Log and monitor the API traffic, including errors. Log each request that the integration makes by transaction.

• Retries: If the API does not respond, try again a few times. Then wait longer before you try again.

• Error handling: Handle errors in your own system. Save the error description that the API returns and show it as it is.

Timing and frequency

Run large retrieves and imports outside office hours, unless you need them during office hours. The right frequency depends on the resource and the use case. In many cases, once a day or once a month is enough. You can make transfers faster by limiting the data with the resource parameters.

If you need help with an error message, contact partner support at tuki.netvisor@visma.com.

How to read the resource descriptions

The API reference describes each resource in the same way.

Request:

• Basic data: The resource and the HTTP method. GET usually retrieves data from Netvisor, and POST usually imports data to Netvisor.

• Parameters: Usually given in the query string. Separate the first parameter from the resource with ? and the next parameters with &. Not all resources have parameters.

• XML structure (POST): The structure of the XML message. This includes how many times each element can occur and whether it is mandatory.

Response: Every request gets an XML response, and its structure largely matches the request. The Responses and errors page describes the general structure of responses.

Using a ready-made integration

Follow these steps to start using a ready-made integration in Netvisor.

1. Choose an integration partner. First, list your needs and requirements. Then look for ready-made integrations on the Netvisor MarketPlace. The integrations are grouped into categories, and each one has a short description of the integration and the data it transfers. The MarketPlace offers, for example, BI solutions, collection services and solutions for importing sales invoices from web shops. When you find a suitable integration, contact the service provider for more information and prices. Our integration partners maintain the integrations and decide their content and prices.

2. Check your service package. The API is included in the Professional, Premium and Palkat packages. If needed, you can change the package in Netvisor Store.

3. Create API identifiers. In Netvisor, go to Company menu > API Identifiers and click Create new api identifier at the top right. Give the user identifier and key to the integration developer, or add them to the integration settings yourself. See API identifiers.

4. Enable access rights to API resources. In Netvisor, go to Company menu > Interface resource access rights and enable the resources that the integration needs. See Rights of API resources.