Bidirectional data transfer
Fundamentals of Web Service Interface usage
API security and authentication
Examples of error responses
Netvisor WS Client library
Bidirectional data transfer enables integrating customer's external system to Netvisor in a modern way. Available Web Service Integration resources are listed here: Resouces
The interface can be integrated with large and small systems. Netvisor supports transmitting the following information via Web Service Interface:
- Sales invoices
- Sales orders
- Purchase invoices
- Purchase order
- Accounting vouchers
- Bank transfers
- Salary parameters for payroll
- Working hours for resource management
The following information can be retreived from Netvisor Web Service Interface:
- Bank transfers
- Purchase orders
- Invoices and invoice balances
- Accounting information (by dimensions)
The following systems (for example) can be integrated to Netvisor:
- Web shops
- Timecard-/work time entry systems
- Invoicing systems
- Project management systems
Here we describe the fundamentals and methods that are needed in order to communicate with Netvisor's Web Service Interface
- Sending requests
- API security and authentication
- Controling errors
- Examples of error responses
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. Please see our instruction For new Software Partners first.
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
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:
Log and follow Web Service Interface traffic, including errors. The requests should be recorded transaction based. If the Web Service Interface does not respond it is recommended that you try to send the message a few times and then take a longer break. Controlling errors should be done in the external system and the error description received from the Web Service Interface should be saved and shown as it is.
If errors occur the Web Service Interface returns <Status>FAILED</Status> inside ResponseStatus element.
Here is an example of a response to a failed request:
<Status>AUTHENTICATION_FAILED :: Integraatiokumppania ei löydy, katso dokumentaatio</Status>
Web Service Interface controlls error in the following categories:
Authentication of the request failed. Check the credentials, HTTP-headers and MAC-calculation.
The sent data is invalid or of wrong size. Check the material and given parameters.
The sent data already exists in Netvisor. Check the material and given parameters.
The transaction ID has already been used. The ID must change in every request.
The accounting period is locked and material can not be imported before opening the period in Netvisor.
No access rights or the application where the material is imported/retreived is not in use.
System is under maintenance. During maintenance requstes can not be made.
Other error caused by a technical error. The response message returns only error category and error identifier without any further explanation. Technical errors should also be logged. Using the error identifier our partner support and maintenance can help in figuring out the error.
Please read the more detailed description of the error from the error message.
Make sure the syntax is correct:
- The given elements are in the same order as in the resource DTD.
- All compulsory elements are given.
- All compulsory elements have a value.
- All tags have a counterpart.
Importing work hours:
INVALID_DATA :: Data form incorrect:. Entry type not found with given allocation data.
An entry type with the same number as the collector ratio number is needed (e.g. <CollectorRatio type="number">123</CollectorRatio> -> ad an entry type with number 123.). The entry type can be added in Netvisor UI and instructions in Finnish can be found here. When work hours are imported, check the entry type's forms so that the hours will appear on the pay slip. This should always be tested in the test environment.
Importing sales invoices:
INVALID_DATA :: Data form incorrect:. VAT code cannot be retrieved from posting suggestion because no posting suggestion has been given.
The error appears because VAT code is not given in the invoice row. When the VAT code is not given, the system tries to find VAT code from the account suggested in the element accountingAccountSuggestion. When no account is given in that element, an error is returned. VAT code should always be given in the invoice row. Also note that the VAT percentage should also be given.
AUTHENTICATION_FAILED :: Integration keys are not valid. Please check the keys specific to the user and partner.
- The user given in HTTP-header 'X-Netvisor-Authentication-CustomerId' does not exsist or is not active.
- The partner given in HTTP-header 'X-Netvisor-Authentication-PartnerId' is not found.
TECHNICAL_ERROR :: Error when handling material:. Error identifier: 00001
An error in handling material caused by some other technical error. Contact partner support for help in solving the error.
Every request is responded with a standard response message. In GET type request the response includes the requested data (<resouce specific element>) and in POST type request the response might include a event spefic response (Replies).
The general sturcture of a response message:
Element: Root (occurs: 1)
Element: Root/ResponseStatus (occurs: 1)
|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 retreiving data from Netvisor
The retreived data is in its own element in the response message:
Element: Root/ResponseStatus/<resource 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)
The enclosed elements occur times 0-n.
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 excuted in the library.
WS Client library can be found from Visma Solutions Oy GitHub account.
Did you find it helpful?Send feedback