Resources - General : Netvisor

TABLE OF CONTENTS

General
Interface architecture (REST)
Bidirectional data transfer
Security and connection
Authentication
Interpretation instructions
Response messages
Error message categories
Allowed file formats for attachments

General

Netvisor's software interface (API) enables automatic data transfer between external systems and Netvisor. The interface is designed as a secure way to build integrations. The software interface allows both retrieving material from Netvisor and importing material to Netvisor. The resources offered by the interface are divided into upper-level categories.
Common for all transactions:

Dates are in ANSI format
Country codes are always in ISO 3166 format
Attachments are always Base64 encoded in XML message
Empty elements don't need to be given in the XML message. For example, in edit request the empty element is interpreted as an order to update the value to blank
Compulsory elements should not be given empty
Elements have to be in the same order as in the DTD

To be able to import Scandinavian characters (Ä, ä, Ö, ö or Å, å) the message has to be encoded in ISO/IEC 8859-15 but xml declaration does not need to be given. Netvisor's server side performs the necessary preprocessing for the content, so the message should always start with <root>.

Make large retrieves and imports outside office hours if there is no special need to do these during that time. The frequency for transfers varies from resource and use case. In many cases transfers once a day or month is sufficient. You can speed up the transfers with appropriate limitations using resource parameters.

Interface architecture (REST)

Netvisor's interface implementation follows the REST model (Representational State Transfer). It is an architecture model based on the HTTP protocol for implementing programming interfaces.

Operating principle: Simplified, all operations can be done with one message by only changing the HTTP method (e.g. GET for retrieving data, POST for importing data).
Resources: Unlike pure REST model, in Netvisor each method has its own resource.
URI structure: The interface has a root URI, followed by the resource to be called, for example: https://isvapi.netvisor.fi/salesinvoice.nv

Bidirectional data transfer

Netvisor's interface is bidirectional, meaning that data can be both imported into the system and retrieved from it.

Message traffic: In import, material is sent in XML format and in retrieval, the response returns as an XML message.
Responses: The interface always returns a response containing an OK/FAILED status element.
Operating method: Netvisor is always the passive party (server) in the interface, responding to requests made to it.
Recommendation: Requests are recommended to be made one at a time, waiting for a response between each call.

Security and connection

All communication with the interface is protected with modern encryption techniques.

Encrypted connection: Both production and test environment communication is always handled over a secure HTTPS connection.
One-way encryption of authentication information: Authentication information sent is encrypted by creating a checksum from them. From this checksum, the original credentials cannot be returned.

Authentication

The interface identifies each request based on the information in the HTTP headers.

MAC code: Authentication is based on header information and the MAC code (Message Authentication Code) calculated from them.
Use of headers: Appropriate header information must be written in each HTTP request.
Error situations: If headers are missing or incorrect, the interface returns an error message indicating authentication failure with specification (AUTHENTICATION_FAILED).

Interpretation instructions

Enclosed is a description of different entries and their meaning and interpretation in Netvisor's Web Service Interface.
The XML structure of different messages is described in tables for the part it is possible and logical. Due to the XML structure, the resource descriptions have references to different parts of the instructions to be able to keep the entity as clear as possible.

The basic structure of resource description is the following:
Query:

Basic data
- The used resource
- GET - generally retrieving data from Netvisor
- POST - generally posting data to Netvisor
Parameters
- Usually defined in the QueryString, separated from the actual resource with ?- and after the parameter there is &-
- Not all resources have them
XML structure when importing data (POST)
- Described is the XML structure and e.g. the amount of different elements and their compulsion

Note that when using self-closing tags in POST-messages, Netvisor ignores these completely, including possible attributes. For example, when importing customer details, the element <email/> is ignored, while <email></email> updates that particular value in Netvisor to blank.

Response:
Every query is answered with an XML response. The structure of the response matches the query for the most part and the general structure can be seen in the chapter below. The response to GET type queries includes resource-specific data structure that is described in each resource description. Depending on the POST type query, Netvisor Web Service Interface returns Replies element that can include e.g. InsertedDataIdentifier element with added item's ID value.

Response messages

Every request is responded with a standard response message. In GET type request the response includes the requested data (<resource specific element>) and in POST type request the response might include a case-specific response (Replies).
The general structure of a response message:
Element: Root (occurs: 1)
Element: Root/ResponseStatus (occurs: 1)

Element	Type	Description	Example	Details
Status	String	Indicates if there was an error in handling the request	OK	FAILED
Status	String	Error type and description		This element only occurs if the status is FAILED. Check Controlling errors
TimeStamp	Date	Time stamp of the response	01.01.2018 12:00:00

The response type is related to the direction of the data transfer:
1. When retrieving data from Netvisor
The retrieved data is in its own element in the response message:
Element: Root/ResponseStatus/<resource specific element>
2. When importing data to Netvisor
The response includes Replies element and in that element there is data in some occasions:
Element: Root/ResponseStatus/Replies (occurs 0-1)

Element	Type	Description	Example	Details
InsertedDataIdentifier	String
OR
Reply	String

The enclosed elements occur times 0-n.

Rajapintaan lähettävät kutsut

Send one call at a time and wait for a response before sending the next call. Overlapping calls to the same customer environment cause various error situations. We recommend a timeout of at least 120,000 ms for calls. This way you avoid unnecessary error situations.

Log and monitor the interface traffic, including errors. Requests made by the integration should be stored in the log transaction-wise. If the programming interface does not respond for some reason, it is recommended to try the connection a few times again and then take a longer break. Error management should take place in the external system, and the error description provided by the programming interface should be stored and displayed as is.

If you need help interpreting the error message, you can contact our partner support at tuki.netvisor@visma.com.

Virheviestien kategoriat

AUTHENTICATION_FAILED

Authentication of the integration request failed. Check the correctness of the message's authentication information, HTTP headers, and MAC calculation.

INVALID_DATA, INVALID_DATA_SIZE

The data sent to the interface is incorrect or of the wrong size. Check the material and given parameters.

DUPLICATE_DATA

The data sent to the interface already exists in the system. Check the material and given parameters.

REQUEST_NOT_UNIQUE

The unique identifier of the material has already been used. Use a unique identifier for each call.

PERIOD_LOCK

The bookkeeping period is locked and material cannot be imported to it.

SERVICE_ACCESS_ERROR

No access rights or the application whose material is being imported/retrieved is not in use.

SYSTEM_MAINTENANCE

There is a maintenance break in the system. During the maintenance break, interface requests cannot be sent.

TECHNICAL_ERROR

An error occurred in processing the message due to another technical error. The response message only provides the error category and a unique identifier without a detailed specification. Technical errors are also logged, allowing investigation of error situations with a unique identifier by partner support and maintenance afterwards.

Detailed error messages can be found in this guide

Allowed file formats for attachments

ApiBatchSharedAttachments (purchaseinvoicebatch.nv, salesinvoicebatch.nv )

- Purchase invoices:

- Invoice image (invoiceimage): .pdf, .xml

- Invoice attachments (otherattachment): .bmp, .csv, .doc, .docx, .emf, .exif, .gif, .gzip, .heic, .eml, .html, .ico, .jpg, .msg, .mp3, .odp, .ods, .odt, .pdf, .png, .pptx, .rtf, .tiff, .txt, .wmf, .xls, .xlsm, .xlsx, .xml, .xsl, .zip, .7z

- Max 20 MiB

- Sales invoices:

- (pdf) .pdf

- (finvoice) .csv, .doc, .docx, .gif, .html, .jpg, .pdf, .tiff, .txt, .xls, .xlsx, .xsl

- Max 5 MiB

ProductAttachment (product.nv)

- .bmp, .csv, .doc, .docx, .emf, .exif, .gif, .gzip, .heic, .eml, .html, .ico, .jpg, .msg, .mp3, .odp, .ods, .odt, .pdf, .png, .pptx, .rtf, .tiff, .txt, .wmf, .xls, .xlsm, .xlsx, .xml, .xsl, .zip, .7z

- Max 20 MiB

PurchaseInvoiceAttachment (purchaseinvoice.nv)

- Invoice image (invoiceimage): .pdf, .xml

- Max 20 MiB

SalesInvoiceAttachment (salesinvoice.nv)

- (pdf) .pdf

- (finvoice) .csv, .doc, .docx, .gif, .html, .jpg, .pdf, .tiff, .txt, .xls, .xlsx, .xsl

- Max 5 MiB

TripExpenseAttachment (tripexpense.nv)

- Max 20 MiB

VoucherAttachment (accounting.nv)

- Max 20 MiB

AccountingAttachment(accountingedit.nv)

- Max 20 MiB

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.

Did you find it helpful? Yes No